1. 项目缘起与整体设计思路
1.1 为什么选推箱子这个题材
推箱子这个游戏，年纪稍微大一点的玩家都不陌生。规则简单到一句话能说清：把箱子推到目标点上，不能拉只能推，不能穿墙。但真正玩起来，关卡稍微复杂一点就能让人抓耳挠腮。我选它作为Rokid AIUI平台的练手项目，核心原因有三个。
第一，逻辑边界清晰。推箱子的状态空间是有限的、可枚举的，地图用二维数组就能完整描述，不需要复杂的物理引擎，也不需要渲染管线。对于验证一个交互平台的输入输出能力来说，这种“纯逻辑”的游戏是最合适的试金石。
第二，天然适配多种交互方式。推箱子只需要四个方向加一个撤销/重置操作，这恰好是语音识别最擅长的指令集——短词、固定词汇、高重复率。同时，方向操作又天然适合陀螺仪的姿态映射。一个游戏能同时把语音和体感两条交互链路跑通，性价比极高。
第三，童年情怀加成。说实话，做项目这件事，如果没有一点个人情感在里面，很容易半途而废。推箱子是我小学时在文曲星上玩的第一批游戏之一，那种“再推一步就过关了”的执念，到现在还记得。用自己手里的技术把它重新做一遍，本身就是一件有意思的事。
1.2 技术选型背后的考量
Rokid AIUI这个平台，核心能力在于语音交互链路的封装。它提供了唤醒、语音识别（ASR）、自然语言理解（NLU）、语音合成（TTS）的完整工具链。我选择它而不是从零搭一套语音方案，主要基于以下判断：
- 唤醒和识别是脏活累活。自己接语音识别引擎，要处理降噪、端点检测、断句、热词优化，这些工作量大且容易踩坑。AIUI把这些封装好了，我只需要定义意图和槽位。
- NLU的意图配置是可视化的。推箱子需要的指令无非是“上、下、左、右、撤销、重置”这几类，在AIUI的意图编辑器里配置同义词和槽位，比写正则表达式维护成本低得多。
- TTS输出可以直接播报游戏状态。推箱子是回合制游戏，每一步之后播报当前状态（比如“已推入2个箱子，还剩1个”），对视觉障碍用户也友好。
陀螺仪这块，我选用的是MPU6050模块。原因很直接：它便宜、资料多、I2C接口简单，而且自带数字运动处理器（DMP），可以直接输出姿态角，不需要我在主控上跑复杂的卡尔曼滤波。对于推箱子这种只需要判断“倾斜方向”的场景，MPU6050的精度绰绰有余。
主控方面，我用了一块支持Python的嵌入式开发板，通过I2C读取MPU6050数据，通过串口和AIUI模块通信，游戏逻辑本身用Python实现。整个架构是：
MPU6050（姿态） ──I2C──> 主控（游戏逻辑） ──UART──> AIUI（语音交互） │ └──> 显示/播报输出这个架构的好处是职责分离：姿态归姿态，语音归语音，游戏逻辑独立于两者之外。任何一路输入出问题，另一路还能正常工作，调试的时候可以单独隔离。
1.3 游戏核心数据结构的设计
推箱子的地图，我用一个二维列表来表示。每个格子用一个字符标记：
#表示墙- （空格）表示空地
.表示目标点$表示箱子*表示箱子已经在目标点上@表示玩家+表示玩家站在目标点上
这个表示法是从经典的Sokoban文本格式沿袭下来的，好处是可读性极强，调试的时候直接print出来就能看懂地图长什么样。关卡数据我单独存在一个列表里，每个关卡是一个字符串列表，加载的时候解析成二维数组。
游戏状态除了地图本身，还需要记录：玩家位置、箱子位置集合、目标点位置集合、步数、撤销栈。撤销栈是一个列表，每走一步就把移动前的状态压进去，撤销的时候弹出来恢复。这个设计让“撤销”操作变成O(1)复杂度的栈操作，非常高效。
注意：撤销栈如果无限增长，长时间游玩会吃内存。我的做法是限制栈深度为200步，超过就丢弃最早的记录。对于推箱子这种关卡制游戏，200步足够覆盖任何单关的解法。
2. 核心细节解析与实操要点
2.1 MPU6050陀螺仪的姿态读取与方向判定
MPU6050的使用，网上教程很多，但真正落到“用倾斜方向控制游戏”这个场景，有几个细节必须说清楚。
首先，原始加速度计数据不能直接用。加速度计输出的是三轴加速度，静止时只有重力分量。理论上通过重力在各轴的分量可以算出倾角，但实际使用中，手部的微小抖动会让读数剧烈波动。我一开始直接读加速度计算角度，结果玩家角色像抽风一样乱走。后来改用DMP输出的姿态角（俯仰角pitch和横滚角roll），稳定性好了很多。
DMP的初始化流程大致如下：
# 伪代码示意，具体寄存器操作参考MPU6050数据手册 mpu.initialize() mpu.dmp_initialize() mpu.set_dmp_enabled(True) # 设置采样率 mpu.set_sample_rate(50) # 50Hz足够 # 启用DMP的6轴姿态输出 mpu.set_dmp_feature(DMP_FEATURE_6X_LP_QUAT)初始化完成后，通过FIFO读取四元数，再转换成欧拉角。这里有个坑：四元数转欧拉角的公式如果写错，角度会出现跳变。我建议直接用现成的库，比如mpu6050或pyMPU6050，不要自己手写转换。
方向判定的逻辑是这样的：
| 姿态条件 | 判定方向 | 说明 |
|---|---|---|
| pitch > 25度 | 上 | 向前倾斜 |
| pitch < -25度 | 下 | 向后倾斜 |
| roll > 25度 | 右 | 向右倾斜 |
| roll < -25度 | 左 | 向左倾斜 |
| 其他 | 无操作 | 死区 |
25度这个阈值是实测调出来的。太小容易误触发，太大操作费力。死区的设置很关键，否则手稍微不稳就会连续触发移动。
实操心得：MPU6050的零偏会随温度漂移。我在初始化时做了一次静态校准——让设备静止2秒，采集100个样本取平均作为零偏，后续读数都减去这个零偏。这一步不做的话，玩十分钟后角色就会自己往一个方向飘。
2.2 语音识别的意图配置与指令映射
AIUI的意图配置是可视化的，但配置得好不好，直接决定识别率。推箱子的语音指令我定义了六个意图：
- 移动意图：槽位是方向（上/下/左/右/前/后/左前/右前等）
- 撤销意图：同义词包括“撤销、退一步、回退、悔棋”
- 重置意图：同义词包括“重置、重来、重新开始、复位”
- 状态查询意图：同义词包括“还有几个箱子、进度、状态”
- 暂停意图：同义词包括“暂停、停一下、等等”
- 继续意图：同义词包括“继续、开始、走起”
这里的关键是同义词要覆盖口语习惯。比如“上”，用户可能说“往上”“上面”“向上”“前”，这些都要配进去。AIUI的意图编辑器支持批量导入同义词，我建议先把能想到的说法都列出来，再根据实际测试补充。
语音识别还有一个容易被忽略的点：环境噪声对短词识别的影响很大。推箱子指令都是单字或双字词，信噪比低的时候识别率会明显下降。我的应对策略是：
- 在AIUI配置里开启命令词模式，限定识别范围只在这几个指令内，大幅降低误识别。
- 播报TTS的时候暂停识别，避免自己的声音被识别成指令。这个在AIUI里可以通过设置识别开关来实现。
- 给每个指令加一个确认反馈，比如识别到“上”之后，TTS播报“向上”，让用户知道指令被正确接收了。
2.3 游戏逻辑与交互的桥接设计
游戏主循环是一个事件驱动的结构。我定义了一个GameEngine类，对外暴露move(direction)、undo()、reset()、get_state()这几个方法。语音模块和陀螺仪模块都只是事件的产生者，它们不直接操作游戏数据，而是把事件投递到一个队列里，主循环从队列取事件再调用对应方法。
这样做的好处是避免竞态条件。如果语音识别回调和陀螺仪读取回调都直接改游戏状态，很容易出现两个事件同时到达、状态被覆盖的问题。用队列串行化之后，任何时刻只有一个事件在处理，逻辑清晰得多。
状态播报的时机也有讲究。我一开始每走一步都播报，结果TTS声音还没结束，下一个指令就来了，体验很割裂。后来改成只在关键节点播报：推入一个箱子时播报、通关时播报、撤销时播报、查询时播报。普通移动只给一个短促的提示音，不播报完整语句。
3. 实操过程与核心环节实现
3.1 硬件连接与基础环境搭建
硬件清单如下：
| 组件 | 型号 | 数量 | 备注 |
|---|---|---|---|
| 主控板 | 支持Python的嵌入式板 | 1 | 需有I2C和UART |
| 陀螺仪模块 | MPU6050 | 1 | 注意供电3.3V |
| 语音模块 | AIUI开发套件 | 1 | 按官方文档接线 |
| 连接线 | 杜邦线 | 若干 | 母对母 |
接线方面，MPU6050的VCC接3.3V，GND接GND，SCL和SDA分别接主控的I2C时钟线和数据线。AIUI模块通过UART和主控通信，波特率默认115200。这里有个细节：MPU6050的I2C地址是0x68（AD0接地）或0x69（AD0接VCC），如果读不到数据，先检查地址对不对。
环境搭建步骤：
- 在主控上安装Python3和pip。
- 安装I2C工具：
sudo apt install i2c-tools，然后用i2cdetect -y 1确认MPU6050被识别到。 - 安装MPU6050的Python库：
pip install mpu6050-raspberrypi（根据主控平台选择对应库）。 - 安装串口库：
pip install pyserial。 - 按照AIUI官方文档配置语音模块的固件和授权。
注意：MPU6050对电源噪声比较敏感，如果读数跳动厉害，可以在VCC和GND之间并一个0.1uF的陶瓷电容。这个是我踩过坑之后加的，加了之后数据稳定性明显提升。
3.2 地图解析与游戏引擎实现
地图解析函数的核心逻辑是遍历字符串列表，把每个字符转换成内部表示，同时记录玩家和箱子的初始位置。这里要注意箱子在目标点上的情况，字符是*，解析时要同时加入箱子集合和目标点集合。
移动逻辑是推箱子的核心。当玩家尝试向某个方向移动时，需要判断：
- 目标格子是否是墙？是墙则移动失败。
- 目标格子是否有箱子？
- 没有箱子：玩家直接移动过去。
- 有箱子：再判断箱子后面的格子是否为空或目标点。如果是，箱子和玩家都移动；否则移动失败。
这个判断逻辑用代码表达就是：
def try_move(self, direction): dx, dy = DIRECTION_MAP[direction] new_x = self.player_x + dx new_y = self.player_y + dy if self.map[new_y][new_x] == WALL: return False if (new_x, new_y) in self.boxes: box_new_x = new_x + dx box_new_y = new_y + dy if self.map[box_new_y][box_new_x] == WALL: return False if (box_new_x, box_new_y) in self.boxes: return False # 执行推箱子 self.boxes.remove((new_x, new_y)) self.boxes.add((box_new_x, box_new_y)) # 记录撤销状态 self.undo_stack.append(self.snapshot()) self.player_x = new_x self.player_y = new_y return True胜利条件是所有箱子都在目标点上，即boxes集合和targets集合完全重合。每次移动后检查一次，满足就触发通关播报。
3.3 语音指令的解析与执行链路
语音指令从识别到执行，经过的链路是：
麦克风拾音 -> AIUI唤醒 -> ASR识别 -> NLU意图匹配 -> 串口输出JSON -> 主控解析 -> 投递事件队列 -> 游戏引擎执行AIUI输出的JSON格式大致是：
{ "intent": "move", "slots": [ {"name": "direction", "value": "上"} ] }主控收到后，解析出意图和槽位，转换成内部事件。这里有个细节：AIUI返回的方向词可能是“向上”“上面”等同义词，需要在主控侧做一次归一化，统一映射到“上/下/左/右”四个标准方向。
语音播报的实现，我用了AIUI自带的TTS功能，通过串口发送播报指令。播报内容动态生成，比如“已推入2个箱子，还剩1个”“恭喜通关，共用了35步”。播报的时候要暂停识别，播报结束后再恢复，否则会把自己的声音识别成指令。
3.4 陀螺仪控制的调参与手感优化
陀螺仪控制的手感，是决定这个项目好不好玩的关键。我调了大概三天，总结出几个要点：
第一，采样率要匹配游戏节奏。50Hz的采样率意味着每20毫秒读一次姿态，对于推箱子这种回合制游戏足够了。采样率太高反而增加CPU负担，太低则响应迟钝。
第二，方向判定要加“冷却时间”。倾斜触发一次移动后，如果手还没回正，会连续触发。我的做法是触发一次后，强制等待300毫秒再允许下一次触发。这个冷却时间可以根据个人习惯调整，我试过200毫秒太灵敏，500毫秒太迟钝，300毫秒刚好。
第三，死区要动态调整。固定死区在设备不同姿态下表现不一致。我的改进方案是：以校准时的零偏为基准，死区设为±15度，触发阈值设为±25度。这样从死区到触发有10度的缓冲，不会在阈值附近反复横跳。
第四，提供“回正确认”反馈。每次触发移动后，蜂鸣器短响一声，让用户知道指令已接收。这个反馈很重要，没有它用户会不确定自己是不是倾斜得不够。
实操心得：MPU6050的DMP输出四元数后，转欧拉角的顺序会影响角度范围。我用的转换顺序是Z-Y-X，得到的pitch范围是-90到90度，roll范围是-180到180度。如果你的转换顺序不同，角度范围会变，阈值也要跟着调。
4. 常见问题与排查技巧实录
4.1 语音识别相关的问题
问题一：唤醒后不说话，过几秒就退出了。
这是AIUI的唤醒超时设置问题。默认唤醒后如果3秒内没有识别到有效语音，会退出唤醒状态。推箱子场景下，用户可能需要思考一下再说指令。我的解决办法是在AIUI配置里把唤醒超时延长到10秒，并且在游戏暂停时主动重新唤醒。
问题二：识别到指令但游戏没反应。
排查链路：先看AIUI的调试输出有没有正确识别到意图，再看串口有没有数据发出，再看主控有没有收到数据。我遇到过一次是串口波特率不匹配，AIUI默认115200，主控这边设成了9600，数据全是乱码。还有一次是JSON解析出错，原因是AIUI返回的JSON里带了BOM头，Python的json.loads不认，需要先decode('utf-8-sig')。
问题三：TTS播报和识别互相干扰。
这个前面提过，解决办法是播报时关闭识别。但要注意，关闭识别和恢复识别之间要留一点间隔，否则TTS的尾音可能被截进去。我留了200毫秒的间隔。
4.2 陀螺仪相关的问题
问题一：读数一直为零或不变。
先检查I2C连接，用i2cdetect确认设备地址。如果地址对但读数不变，可能是DMP没有正确初始化。MPU6050的DMP初始化需要加载固件，固件加载失败的话DMP不会输出数据。检查固件文件路径是否正确，以及I2C读写是否正常。
问题二：角度漂移严重。
这是MPU6050的通病。DMP内部有姿态融合算法，但长时间运行仍会漂移。我的应对方案是：每5分钟自动重新校准一次零偏，校准期间暂停游戏输入。另外，避免设备靠近电机、扬声器等磁场源，磁场干扰会严重影响陀螺仪读数。
问题三：倾斜方向判定反了。
这个纯粹是坐标系定义问题。MPU6050的安装方向不同，pitch和roll的正负方向就不同。解决办法很简单：在代码里加一个方向映射配置，如果发现上下颠倒，就把pitch的符号取反；左右颠倒就取反roll。不要改硬件安装方向，改代码更灵活。
4.3 游戏逻辑相关的问题
问题一：撤销之后箱子位置不对。
这是撤销栈快照不完整导致的。快照必须包含玩家位置、箱子集合、步数三个信息。我一开始只存了玩家位置，撤销后箱子还在新位置，就出bug了。后来改成存完整状态，问题解决。
问题二：连续快速操作导致状态错乱。
语音和陀螺仪同时触发时，如果不用队列串行化，就会出现状态覆盖。我实测过，不加队列的话，大概每50次操作会出现一次状态错乱。加了事件队列之后，再没出现过。
问题三：通关判定不触发。
检查目标点集合和箱子集合是否完全相等。这里有个坑：如果地图解析时把*（箱子在目标点上）只加入了箱子集合，没加入目标点集合，通关判定就会失败。解析逻辑要确保目标点集合包含所有.和*的位置。
4.4 常见问题速查表
| 现象 | 可能原因 | 排查方法 | 解决方案 |
|---|---|---|---|
| 语音无响应 | 唤醒超时/麦克风故障 | 查看AIUI调试输出 | 延长唤醒超时，检查麦克风接线 |
| 识别错误 | 环境噪声/同义词未覆盖 | 查看识别日志 | 开启命令词模式，补充同义词 |
| 陀螺仪无数据 | I2C连接/地址错误 | i2cdetect扫描 | 检查接线和地址 |
| 角度漂移 | 零偏未校准/温度变化 | 静止观察读数 | 定期重新校准 |
| 方向判定反 | 坐标系定义不一致 | 倾斜测试 | 代码中取反对应轴 |
| 撤销异常 | 快照不完整 | 检查快照内容 | 存完整状态 |
| 状态错乱 | 并发操作 | 加日志观察 | 事件队列串行化 |
| 通关不触发 | 目标点集合不完整 | 打印集合内容 | 解析时包含所有目标点 |
5. 交互体验的打磨与扩展思路
5.1 双模交互的切换与融合
语音和陀螺仪两套输入方式，如果同时开启，会有冲突。比如用户倾斜设备的时候说了句话，两个事件几乎同时到达。我的处理策略是优先级仲裁：语音指令优先级高于陀螺仪，因为语音是显式意图，陀螺仪是隐式意图。当语音事件到达时，清空陀螺仪的事件缓冲，避免语音执行后陀螺仪又触发一次。
另外，我加了一个模式切换指令。用户可以说“切换语音模式”或“切换体感模式”，只启用其中一种输入。这样在嘈杂环境用体感，在设备不便倾斜时用语音，灵活性更好。
5.2 关卡设计与难度曲线
推箱子的关卡设计是一门学问。我一开始自己画地图，画出来的要么太简单，要么无解。后来参考了经典Sokoban的关卡集，挑选了难度递增的20关。难度曲线大致是：
- 第1-5关：单箱子，开阔地形，熟悉操作。
- 第6-10关：双箱子，有墙角限制，需要规划顺序。
- 第11-15关：三箱子，狭窄通道，需要利用目标点作为临时通道。
- 第16-20关：多箱子，复杂地形，需要深度优先搜索才能找到解法。
这里提一下深度优先搜索（DFS）在关卡验证中的应用。自己设计的关卡，怎么知道有没有解？我写了一个简单的DFS求解器，穷举所有可能的移动序列，看能否达到通关状态。这个求解器也用于生成提示——当用户卡关时，可以说“提示”，系统给出下一步建议。
5.3 语音播报的文案设计
TTS播报的文案，直接影响游戏的沉浸感。我试过几种风格：
- 极简风格：“上”“推入”“通关”。优点是快，缺点是信息量少。
- 播报风格：“已向上移动”“箱子已推入目标点”“恭喜通关”。信息完整，但每步都播报太啰嗦。
- 混合风格：普通移动只播报方向词，关键事件播报完整句子。这是我最终采用的方案。
文案的语速和音调也可以调。AIUI的TTS支持设置语速、音调、音量。我把语速设为正常偏快，音调稍高一点，听起来更有活力。通关时的播报加了一点音效，增强成就感。
5.4 后续可以扩展的方向
这个项目做完之后，我觉得还有不少可以继续挖的方向。比如加入机器翻译，让语音指令支持多语言，说英文也能识别。AIUI本身支持多语言配置，扩展成本不高。
再比如用语音识别做关卡编辑器，用户口述地图布局，系统生成关卡。这个需要定义一套地图描述语法，比如“五乘五地图，左上角是墙，中间是玩家”，然后解析成二维数组。技术上可行，但语法设计需要打磨。
还有一个方向是接入大模型做智能提示。当用户卡关时，不只是给下一步，而是用自然语言解释“为什么这一步要这样走”。这需要把游戏状态和求解器的搜索结果一起喂给语言模型，让它生成解释性文本。这个扩展比较重，但很有意思。
最后分享一个小技巧：调试语音交互的时候，把ASR的原始识别结果和NLU的意图解析结果都打印出来，对照着看。很多时候识别是对的，但意图匹配错了，或者槽位提取错了。分开看这两段日志，定位问题会快很多。
