mms <a href="https://www.buymeacoffee.com/mackorone"><img align="right" height=36 alt="Save the Children" src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png"></a>

Table of Contents

1. Introduction
2. Download
3. Quick Start
4. Mouse API
5. Scorekeeping
6. Cell Walls
7. Cell Color
8. Cell Text
9. Reset Button
10. Maze Files
11. Building From Source
12. Related Projects
13. Citations
14. Acknowledgements

Introduction

mms is a Micromouse simulator.

It makes it easy to write and test maze-solving code without a physical robot.

With it, you can:

• Test how your robot would behave in a real maze
• Visualize what your robot is thinking
  • Show known/unknown walls
  • Set the color of the cells
  • Display ASCII text on the cells
• Simulate a crash-and-reset scenario
• Test your algorithm on custom maze files
• Write code in any language you want

Previous versions of mms exist in the old/ directory.

For information about Micromouse, see the Micromouse Wikipedia page.

Download

You can download pre-compiled binaries from the releases page.

• Linux: Download and unzip linux.zip and run mms-x86_64.AppImage
• macOS: Download and unzip macos.zip and run mms.app
• Windows: Download and unzip windows.zip and run mms/mms.exe

If pre-compiled binaries for your platform are unavailable, you'll have to build from source.

[!IMPORTANT] The macOS version fails with the following error:

"mms.app" is damaged and can’t be opened. You should move it to the Trash.

To get past the error, manually remove the quarantine attribute:

xattr -d com.apple.quarantine mms.app

[!NOTE] On Windows, you may get a warning like:

Microsoft Defender SmartScreen prevented an unrecognized app from starting. Running this app might put your PC at risk.

To get past that warning, click "More info" and then "Run anyway."

Quick Start

Writing a Micromouse algorithm is easy! Here are some available templates:

| Language | Repo | |-|-| | Arduino | mackorone/mms-arduino | C | mackorone/mms-c | C++ | mackorone/mms-cpp | Go | cpellet/mms-go | Java | mackorone/mms-java | JavaScript | mackorone/mms-javascript | Python | mackorone/mms-python | Rust | hardliner66/mms-rs | Zig | kouosi/mms_zig

If a template for a particular language is missing, don't fret! Writing your own template is as easy as writing to stdout, reading from stdin, and implementing the mouse API below. If you have a template you'd like to share, please make a pull request!

Mouse API

Algorithms communicate with the simulator via stdin/stdout. To issue a command, simply print to stdout. To read a response, simply read from stdin. All valid commands are listed below. Invalid commands are simply ignored.

For commands that return a response, it's recommended to wait for the response before issuing additional commands.

Summary

int mazeWidth();
int mazeHeight();

bool wallFront(int numHalfSteps = 1);
bool wallRight(int numHalfSteps = 1);
bool wallLeft(int numHalfSteps = 1);
bool wallBack(int numHalfSteps = 1);

// Both of these commands can result in "crash"
void moveForward(int distance = 1);
void moveForwardHalf(int numHalfSteps = 1);

void turnRight();
void turnLeft();
void turnRight45();
void turnLeft45();

void setWall(int x, int y, char direction);
void clearWall(int x, int y, char direction);

void setColor(int x, int y, char color);
void clearColor(int x, int y);
void clearAllColor();

void setText(int x, int y, string text);
void clearText(int x, int y);
void clearAllText();

bool wasReset();
void ackReset();

int/float getStat(string stat);

mazeWidth

• Args: None
• Action: None
• Response: The height of the maze

mazeHeight

• Args: None
• Action: None
• Response: The width of the maze

wallFront [N]

• Args:
  • N - (optional) Check for a wall this many half-steps away, default 1
• Action: None
• Response: true if there is a wall, else false

wallRight [N]

• Args: None
  • N - (optional) Check for a wall this many half-steps away, default 1
• Action: None
• Response: true if there is a wall, else false

wallLeft [N]

• Args: None
  • N - (optional) Check for a wall this many half-steps away, default 1
• Action: None
• Response: true if there is a wall, else false

wallBack [N]

• Args: None
  • N - (optional) Check for a wall this many half-steps away, default 1
• Action: None
• Response: true if there is a wall, else false

moveForward [N]

• Args:
  • N - (optional) The number of full steps to move forward, default 1
• Action: Move the robot forward the specified number of full-steps
• Response:
  • crash if N < 1 or the mouse cannot complete the movement
  • else ack once the movement completes

moveForwardHalf [N]

• Args:
  • N - (optional) The number of half steps to move forward, default 1
• Action: Move the robot forward the specified number of half-steps
• Response:
  • crash if N < 1 or the mouse cannot complete the movement
  • else ack once the movement completes

turnRight or turnRight90

• Args: None
• Action: Turn the robot ninty degrees to the right
• Response: ack once the movement completes

turnLeft or turnLeft90

• Args: None
• Action: Turn the robot ninty degrees to the left
• Response: ack once the movement completes

turnRight45

• Args: None
• Action: Turn the robot forty-five degrees to the right
• Response: ack once the movement completes

turnLeft45

• Args: None
• Action: Turn the robot forty-five degrees to the left
• Response: ack once the movement completes

setWall X Y D

• Args:
  • X - The X coordinate of the cell
  • Y - The Y coordinate of the cell
  • D - The direction of the wall: n, e, s, or w
• Action: Display a wall at the given position
• Response: None

clearWall X Y D

• Args:
  • X - The X coordinate of the cell
  • Y - The Y coordinate of the cell
  • D - The direction of the wall: n, e, s, or w
• Action: Clear the wall at the given position
• Response: None

setColor X Y C

• Args:
  • X - The X coordinate of the cell
  • Y - The Y coordinate of the cell
  • C - The character of the desired color
• Action: Set the color of the cell at the given position
• Response: None

clearColor X Y

• Args:
  • X - The X coordinate of the cell
  • Y - The Y coordinate of the cell
• Action: Clear the color of the cell at the given position
• Response: None

clearAllColor

• Args: None
• Action: Clear the color of all cells
• Response: None

setText X Y TEXT

• Args:
  • X - The X coordinate of the cell
  • Y - The Y coordinate of the cell
  • TEXT - The desired text, max length 10
• Action: Set the text of the cell at the given position
• Response: None

clearText X Y

• Args:
  • X - The X coordinate of the cell
  • Y - The Y coordinate of the cell
• Action: Clear the text of the cell at the given position
• Response: None

clearAllText

• Args: None
• Action: Clear the text of all cells
• Response: None

wasReset

• Args: None
• Action: None
• Response: true if the reset button was pressed, else false

ackReset

• Args: None
• Action: Allow the mouse to be moved back to the start of the maze
• Response: ack once the movement completes

getStat

• Args:
  • stat: A string representing the stat to query. Available stats are:
    • total-distance (int)
    • total-turns (int)
    • best-run-distance (int)
    • best-run-turns (int)
    • current-run-distance (int)
    • current-run-turns (int)
    • total-effective-distance (float)
    • best-run-effective-distance (float)
    • current-run-effective-distance (float)
    • score (float)
• Action: None
• Response: The value of the stat, or -1 if no value exists yet. The value will either be a float or integer, according to the types listed above.

Example

Algorithm Request (stdout)  Simulator Response (stdin)
--------------------------  --------------------------
mazeWidth                   16
mazeWidth                   16
wallLeft                    true
setWall 0 0 w               <NO RESPONSE>
wallFront                   false
moveForward                 ack
turnLeft                    ack
wallFront