A Micromouse simulator: write and test maze-solving code without a physical robot
mms is a Micromouse simulator.
It makes it easy to write and test maze-solving code without a physical robot.
With it, you can:
Previous versions of mms exist in the old/
directory.
For information about Micromouse, see the Micromouse Wikipedia page.
You can download pre-compiled binaries from the releases page. Simply download the asset corresponding to your platform:
Windows: Download and unzip windows.zip
and run the "mms" exe
macOS: Download and unzip macos.zip
and run the "mms" app
If pre-compiled binaries for your platform are unavailable, you'll have to build from source.
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 |
Java | mackorone/mms-java |
JavaScript | mackorone/mms-javascript |
Python | mackorone/mms-python |
Rust | hardliner66/mms-rs |
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!
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.
int mazeWidth();
int mazeHeight();
bool wallFront();
bool wallRight();
bool wallLeft();
// 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
mazeHeight
wallFront
true
if there is a wall in front of the robot, else false
wallRight
true
if there is a wall to the right of the robot, else false
wallLeft
true
if there is a wall to the left of the robot, else false
moveForward [N]
N
- (optional) The number of full steps to move forward, default 1
crash
if N < 1
or the mouse cannot complete the movementack
once the movement completesmoveForwardHalf [N]
N
- (optional) The number of half steps to move forward, default 1
crash
if N < 1
or the mouse cannot complete the movementack
once the movement completesturnRight
or turnRight90
ack
once the movement completesturnLeft
or turnLeft90
ack
once the movement completesturnRight45
ack
once the movement completesturnLeft45
ack
once the movement completessetWall X Y D
X
- The X coordinate of the cellY
- The Y coordinate of the cellD
- The direction of the wall: n
, e
, s
, or w
clearWall X Y D
X
- The X coordinate of the cellY
- The Y coordinate of the cellD
- The direction of the wall: n
, e
, s
, or w
setColor X Y C
X
- The X coordinate of the cellY
- The Y coordinate of the cellC
- The character of the desired color
clearColor X Y
X
- The X coordinate of the cellY
- The Y coordinate of the cellclearAllColor
setText X Y TEXT
X
- The X coordinate of the cellY
- The Y coordinate of the cellTEXT
- The desired text, max length 10clearText X Y
X
- The X coordinate of the cellY
- The Y coordinate of the cellclearAllText
wasReset
true
if the reset button was pressed, else false
ackReset
ack
once the movement completesgetStat
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)
-1
if no value exists yet. The value will either be a float or integer, according to the types listed above.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 true
moveForward crash
setColor 0 1 r <NO RESPONSE>
setText 0 1 whoops <NO RESPONSE>
wasReset false
...
wasReset true
clearAllColor <NO RESPONSE>
clearAllText <NO RESPONSE>
ackReset ack
The Stats tab displays information that can be used to score an algorithm's efficiency. This tab displays stats such as the total distance and total number of turns. It also displays the distance and number of turns for the algorithm's best start-to-finish run, if the algorithm makes multiple runs from the start tile to the goal. The distance and number of turns for the current start-to-finish run is also displayed.
There is another value displayed, called Effective Distance. This number may
differ from Distance if moveForward
is called with the optional distance
parameter. If moveForward
is called with an integer greater than 2, each tile
after the second tile will add only half a point to the effective distance. This
simulates a mouse driving faster if it can drive in a straight line for more
than a few tiles. For example, moveForward(5)
will increase the distance by 5
but will increase the effective distance by only 3.5. A mouse will incur a
15-point penalty on its next run's Effective Distance if it uses ackReset
to
return to the start tile.
A final score is computed for the algorithm after it terminates. A lower score is better. The final score depends on the best start-to-finish run and on the overall run, according to the following equation.
score = best run turns + best run effective distance + 0.1 * (total turns + total effective distance)
The mouse must reach the goal to receive a score. If the mouse never reaches the goal, the score will be 2000.
Cell walls allow the robot to diplay where it thinks walls exist, and where it thinks they don't. At the beginning of each run, all walls are assumed non-existent. By default, the simulator will display walls that haven't been discovered as dark red. As the robot explores the maze, it should set walls as it discovers them.
The available colors are as follows:
Char | Color |
---|---|
k | Black |
b | Blue |
a | Gray |
c | Cyan |
g | Green |
o | Orange |
r | Red |
w | White |
y | Yellow |
B | Dark Blue |
C | Dark Cyan |
A | Dark Gray |
G | Dark Green |
R | Dark Red |
Y | Dark Yellow |
All printable ASCII characters,
except for <DEL>
, can be used as cell text. Any invalid characters, such as a
newline or tab, will be replaced with ?
.
When no algorithm is running, the simulator displays the distance of each cell from the center of the maze.
The reset button makes it possible to test crash handling code. Press the
button to simulate a crash. Your algorithm should periodically check if the
button was pressed via wasReset
. If so, your algorithm should reset any
internal state and then call ackReset
to send the robot back to the beginning
of the maze.
The simulator supports a few different maze file formats, as specified below. If your format isn't supported, feel free to put up a pull request.
Note that, in order to use a maze in the simulator, it must be:
Also note that official Micromouse mazes have additional requirements:
Here are some links to collections of maze files:
Example:
+---+---+---+
| | |
+ + + +
| | |
+---+---+---+
+ x +
x x
+ x +
Format:
X Y N E S W
1
if there is a wall on the north side, else 0
1
if there is a wall on the east side, else 0
1
if there is a wall on the south side, else 0
1
if there is a wall on the west side, else 0
Example:
0 0 0 1 1 1
0 1 1 0 0 1
1 0 0 0 1 1
1 1 1 1 0 0
2 0 0 1 1 0
2 1 1 1 0 1
Result:
+---+---+---+
| | |
+ + + +
| | |
+---+---+---+
If you want to write code for the simulator itself, you'll need to build the project from source. Below are some OS-specific instructions. If instructions for your platform are unavailable, you can probably still run the simulator, you'll just have to figure it out on your own for now.
Install Qt:
Build the project using QtCreator:
mms/src/mms.pro
Install Xcode: https://developer.apple.com/xcode/
Install Qt:
Build the project using QtCreator:
mms/src/mms.pro
Install Qt:
chmod +x qt-unified-linux-x64-3.0.6-online.run
./qt-unified-linux-x64-3.0.6-online.run
qmake
binary can be found in the installation directoryClone, build, and run the project:
# Clone the repo
git clone [email protected]:mackorone/mms.git
# Build the simulator
cd mms/src
qmake && make
# Run the simulator
../../bin/mms
Feel free to open a pull request if you want your work listed here!
Name | Author | Used For |
---|---|---|
polypartition | Ivan Fratric | Polygon Triangulation |
Qt | The Qt Company | Framework and GUI |