mms源码解析①:stdin/stdout文本协议如何让你在任意编程语言中驱动迷宫算法

原创2026-11-14 13:13:252,142 阅读
文章标签:开发工具

mms源码解析①:stdin/stdout文本协议如何让你在任意编程语言中驱动迷宫算法

微型老鼠(Micromouse)迷宫模拟器 mms 用一套极简的 stdin/stdout 文本协议,让任何编程语言编写的迷宫算法进程都能直接驱动仿真器——你的算法只需向 stdout 打印一条命令、从 stdin 读回一行响应,就能控制虚拟老鼠走路、探测墙壁、给格子着色写文字,完全不受 C++ 接口限制。本文结合 mms 源码,完整解析这套任意语言迷宫算法驱动协议的工作原理与源码实现。

mms微型老鼠迷宫模拟器界面:左侧为带红色墙壁的迷宫和距离标注,右侧为Build/Run按钮与算法输出面板

为什么选 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

mms迷宫格子特写:蓝色机器人老鼠位于黑色格子中央,两侧是绿色传感器,红色代表墙壁

一次典型会话长什么样

下面是 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() 做三件事:

  1. 创建 QProcess,按配置启动算法进程
  2. 连接 readyReadStandardOutput 信号:每次算法输出可读时,readAllStandardOutput() 取走文本,切成完整命令行后逐条交给 dispatchCommand
  3. 连接 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)——用它们可以实现对角线走法。

三步接入你自己的迷宫算法

  1. 配置:在 mms 的 Mouse 设置里新增一个算法条目,填写工作目录和运行命令(见 SettingsMouseAlgos.cpp)
  2. 写算法:在算法目录写一个"从 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")
  1. 运行:选中算法条目点 Run,算法进程被启动,协议对话开始;算法打印到 stderr 的日志会实时显示在 Run Output 面板

总结:这套 stdin/stdout 协议设计好在哪

mms 源码里没有算法 API 头文件、没有插件接口、没有回调函数——只有 ProcessUtilities.cpp 的十几个字节的进程启动,和 Window.cpp 里约四百行"读一行、校验、执行、写一行"的逻辑。

它把仿真器抽象成"迷宫 API 服务端"、把算法抽象成"外部语言客户端",用纯文本协议完成了:语言无关(9 种官方模板语言)、可调试(文本命令流 + stderr 日志直通界面)、易崩溃恢复(crash/ackReset 握手)。如果你想给自己的 GUI 程序接外部语言脚本,这套 QProcess + 行缓冲 + 命令队列的模式非常值得参考。

下一篇源码解析将拆解 mms 的渲染管线:格子、三角剖分(polypartition)与纹理字体缓存是如何画出来的。

登录后查看全文
mms