mms源码解析①:stdin/stdout文本协议如何让你在任意编程语言中驱动迷宫算法
mms源码解析①:stdin/stdout文本协议如何让你在任意编程语言中驱动迷宫算法
微型老鼠(Micromouse)迷宫模拟器 mms 用一套极简的 stdin/stdout 文本协议,让任何编程语言编写的迷宫算法进程都能直接驱动仿真器——你的算法只需向 stdout 打印一条命令、从 stdin 读回一行响应,就能控制虚拟老鼠走路、探测墙壁、给格子着色写文字,完全不受 C++ 接口限制。本文结合 mms 源码,完整解析这套任意语言迷宫算法驱动协议的工作原理与源码实现。
为什么选 stdin/stdout:一个让迷宫算法语言无关的协议设计
微型老鼠(Micromouse)是 IEEE 的机器人竞赛项目:让一只手掌大小的机器老鼠在未知迷宫中自动探索并找到中心。mms 的价值在于:写迷宫算法不需要真机器人。
如果 mms 把算法做成 C++ 插件,只有 C++ 开发者能用它。而实际做法是:
仿真器 = 迷宫 API 的"服务端";你的算法 = 一个外部进程,通过标准输入/输出与之对话。
这个设计带来三个直接好处:
| 好处 | 说明 |
|---|---|
| 语言无关 | 任何能读写 stdin/stdout 的语言都行:Python、Go、Rust、Zig……甚至 shell 脚本 |
| 天然可调试 | 协议本身就是纯文本,Run Output 面板直接显示算法的调试日志 |
| 崩溃隔离 | 算法进程崩溃不会带崩仿真器,重新点 Run 即可 |
因此 mms 官方模板覆盖了 Arduino、C、C++、Go、Java、JavaScript、Python、Rust、Zig 九种语言;没有你语言的模板也没关系——按协议自己写,难度等于"打印一行 + 读一行"。
协议全貌:算法进程与仿真器的对话规则
完整命令列表见 README.md 的 Mouse API 一节。协议要点:
- 发出命令:算法向自己的 stdout 打印一条文本命令(一行一条)
- 读取响应:算法从 stdin 读一行响应;建议收到响应后再发下一条命令
- 容错:非法命令不会被拒绝执行,而是被忽略(并在界面提示
Invalid command)
按功能分组的命令清单
1. 迷宫信息
| 命令 | 说明 | 响应 |
|---|---|---|
mazeWidth |
迷宫宽度 | 整数 |
mazeHeight |
迷宫高度 | 整数 |
2. 墙壁探测(可选参数 N 表示向前看 N 个半步)
| 命令 | 说明 | 响应 |
|---|---|---|
wallFront [N] |
前方是否有墙 | true / false |
wallBack [N] |
后方是否有墙 | true / false |
wallLeft [N] |
左方是否有墙 | true / false |
wallRight [N] |
右方是否有墙 | true / false |
3. 运动控制
| 命令 | 说明 | 响应 |
|---|---|---|
moveForward [N] |
前进 N 个整步(默认 1) | 完成返回 ack,撞墙或参数非法返回 crash |
moveForwardHalf [N] |
前进 N 个半步 | 同上 |
turnRight / turnRight90 |
右转 90° | 完成后 ack |
turnLeft / turnLeft90 |
左转 90° | 完成后 ack |
turnRight45 / turnLeft45 |
旋转 45° | 完成后 ack |
4. 可视化辅助(无响应,立即生效)
| 命令 | 说明 |
|---|---|
setWall X Y D / clearWall X Y D |
显示/清除格子 (X,Y) 上 D 方向的墙,D 为 n/e/s/w |
setColor X Y C / clearColor X Y / clearAllColor |
格子着色,C 是 15 种颜色字符之一(k 黑、r 红、G 深绿……) |
setText X Y TEXT / clearText X Y / clearAllText |
在格子上显示/清除文字(最长 10 字符) |
5. 重置与统计
| 命令 | 说明 | 响应 |
|---|---|---|
wasReset |
界面上的 Reset 按钮是否被按下 | true / false |
ackReset |
确认后把老鼠送回起点 | ack |
getStat stat |
查询统计项:total-distance、best-run-turns、score 等 10 种 |
数值,无数据时返回 -1 |
一次典型会话长什么样
下面是 README.md 给出的示例,左列是算法打印的命令,右列是仿真器回写的响应:
Algorithm Request (stdout) Simulator Response (stdin)
mazeWidth 16
wallLeft true
setWall 0 0 w <无响应>
wallFront false
moveForward ack
turnLeft ack
wallFront true
moveForward crash
setColor 0 1 r <无响应>
wasReset false
...
wasReset true
ackReset ack
两个值得注意的语义:
- 撞墙是协议级信号:
moveForward撞墙返回crash,算法据此处理"撞墙即复位"的竞赛规则 - reset 握手:仿真器界面按 Reset 按钮只标记状态,算法需主动用
wasReset轮询、清理内部状态后再ackReset回家——这套"crash-and-reset"流程正是协议模拟真实比赛的关键设计
源码解析:外部进程如何接入 Qt 事件循环
整条通信链路分布在几个文件里,核心逻辑集中在 Window.cpp:
第一步:把"算法"配置成一个可执行命令
每个鼠标算法(mouse algo)在设置里保存四样东西:名称、工作目录、构建命令、运行命令,见 SettingsMouseAlgos.cpp。运行时 mms 通过 ProcessUtilities.cpp 启动外部进程:
bool ProcessUtilities::start(const QString &command, const QString &directory,
QProcess *process) {
QStringList args = QProcess::splitCommand(command);
// ...
process->setWorkingDirectory(directory);
process->start(bin, args);
return process->waitForStarted();
}
QProcess::splitCommand 把运行命令拆成程序和参数,工作目录设为算法所在目录——所以你可以直接填 python3 algo.py 或 ./algo 这类任意命令。
第二步:启动 Run 进程并挂接信号
Window.cpp 的 Window::startRun() 做三件事:
- 创建
QProcess,按配置启动算法进程 - 连接
readyReadStandardOutput信号:每次算法输出可读时,readAllStandardOutput()取走文本,切成完整命令行后逐条交给dispatchCommand - 连接
readyReadStandardError信号:算法的 stderr 日志转发到 Run Output 标签页——这就是算法里print("调试信息")能直接看到的原因
无效命令会在 Sim Output 标签页提示 Invalid command: xxx(Window.cpp)。
第三步:按行切分,容忍粘包与半行
管道读取不保证一次给一整行,Window.cpp 的 processText() 用缓冲区处理:
QStringList Window::processText(QString text, QStringList *buffer) {
text.replace("\r", ""); // Windows 兼容
QStringList parts = text.split("\n");
if (1 < parts.size()) { // 出现换行说明至少有一行完整
lines.append(buffer->join("") + parts.at(0));
buffer->clear();
}
for (int i = 1; i < parts.size() - 1; i += 1) {
lines.append(parts.at(i)); // 中间的每一行都是完整的
}
buffer->append(parts.at(parts.size() - 1)); // 最后半行留给下次拼接
return lines;
}
这段"缓存半行、拼接下一批输入"的处理,是文本协议在真实管道上的标准解法。
第四步:命令分发——快路径与慢路径分开
dispatchCommand(Window.cpp)对每条命令做参数校验后分两类处理:
- 无响应命令(
setWall、setColor、setText等 8 条):直接内联执行,不进队列,注释写明"出于性能考虑" - 有响应命令:进入
m_commandQueue队列串行处理
校验是严格的,例如 setWall 要求恰好 4 个 token、方向字符必须在 n/e/s/w 之内(Window.cpp);setText 则专门写了保留空格的解析逻辑(Window.cpp)。
第五步:响应回写与运动调度
有响应命令由 processQueuedCommands()(Window.cpp)串行执行:
response = executeCommand(m_commandQueue.head());
// ...
m_runProcess->write((response + "\n").toStdString().c_str());
executeCommand(Window.cpp)返回 ack / crash / 数字 / true / false。源码里三个响应常量定义在 Window.cpp:ACK = "ack"、CRASH = "crash"、INVALID = "invalid"。
运动命令有个细节:moveForward 不是瞬间完成,而是按界面速度滑条分帧推进(updateMouseProgress),只有运动真正走完(或注定撞墙)时才回写 ack/crash——这解释了 README 的提示"发出命令后建议等待响应":你在等的不是一次 I/O,而是动画跑完。
另一个超出 README 文档的隐藏能力:executeCommand 实际支持 8 个方向的墙壁探测,包括 45° 的 wallFrontRight、wallFrontLeft、wallBackRight、wallBackLeft(Window.cpp)——用它们可以实现对角线走法。
三步接入你自己的迷宫算法
- 配置:在 mms 的 Mouse 设置里新增一个算法条目,填写工作目录和运行命令(见 SettingsMouseAlgos.cpp)
- 写算法:在算法目录写一个"从 stdin 逐行读命令、向 stdout 打印命令"的程序。Python 最小骨架:
import sys
def cmd(s):
sys.stdout.write(s + "\n")
sys.stdout.flush() # 必须刷新,仿真器才能收到
return sys.stdin.readline().strip()
cmd("mazeWidth") # -> "16"
cmd("wallFront") # -> "true" / "false"
if cmd("wallFront") == "false":
cmd("moveForward") # -> "ack" / "crash"
else:
cmd("turnRight")
- 运行:选中算法条目点 Run,算法进程被启动,协议对话开始;算法打印到 stderr 的日志会实时显示在 Run Output 面板
总结:这套 stdin/stdout 协议设计好在哪
mms 源码里没有算法 API 头文件、没有插件接口、没有回调函数——只有 ProcessUtilities.cpp 的十几个字节的进程启动,和 Window.cpp 里约四百行"读一行、校验、执行、写一行"的逻辑。
它把仿真器抽象成"迷宫 API 服务端"、把算法抽象成"外部语言客户端",用纯文本协议完成了:语言无关(9 种官方模板语言)、可调试(文本命令流 + stderr 日志直通界面)、易崩溃恢复(crash/ackReset 握手)。如果你想给自己的 GUI 程序接外部语言脚本,这套 QProcess + 行缓冲 + 命令队列的模式非常值得参考。
下一篇源码解析将拆解 mms 的渲染管线:格子、三角剖分(polypartition)与纹理字体缓存是如何画出来的。

