简介：2012年RoboCup 3D仿真足球赛冠军南邮（南京邮电大学）的可执行代码包，面向机器人仿真、多智能体系统与策略学习研究者，可用于剖析夺冠队伍在三维赛场中的决策与协同机制。包体共175个文件，压缩后大小约29.13MB，核心文件包括76个rsg行为配置、69个svn-base版本记录、5个rb逻辑脚本、4个sh运行脚本，以及apollo3d仿真平台相关文件；rsg定义了虚拟球员的形态与参数，rb承载了行为决策与战术控制，so动态库与sh辅助运行环境，结合其余元数据可还原完整项目结构。目前已有898人学习下载。研读这套代码可深入理解南邮当年在攻防转换、协作防守、快速反击等方面的实现方式，同时借鉴其在Apollo3D仿真环境中的工程化处理方法，无论用于复现实验还是拓展到其他多智能体场景，都有较高的参考价值。 写这篇文章前，我先交代下背景。RoboCup 3D是RoboCup机器人世界杯下的仿真足球项目，参赛队伍不是让实体机器人在场上跑，而是把代码塞进SimSpark仿真服务器里的虚拟NAO机器人中，让20个左右的身高约57厘米的虚拟球员自己去踢球。2012年南京邮电大学在这一项目里拿了冠军，他们的可执行代码和赛后开放的文档，至今仍然是很多3D仿真新手入门时最重要的参考材料之一。这篇文章就围绕这套代码，从仿真平台机制、冠军队的整体技术路线、代码模块拆解到复现环境搭建，一层层讲清楚。
如果你是刚接触RoboCup 3D的本科生、研究生，或者是在做多智能体决策、仿人机器人步态控制相关工作的人，这篇内容可以帮你省掉至少一个月的摸索时间。我不会把所有代码贴出来（那没什么意义），而是把代码背后那些文档里不写的思路、参数和小坑点透。
1. 先搞明白RoboCup 3D到底在比什么
很多人第一次看RoboCup 3D比赛录像，会觉得画面很粗糙——几个小机器人在场上慢慢挪，传球成功率还不高。但真正做过这个项目的人都知道，画面越平淡，底下算法越复杂。3D仿真组的比赛，本质上是把一个完整的机器人足球决策链压缩到每秒30次心跳里跑完。
1.1 SimSpark仿真器给Agent设下的三道门槛
SimSpark是RoboCup 3D的标准仿真平台，它给每个虚拟NAO机器人提供的是带关节、带角速度、带惯性的物理世界。第一道门槛是感知模型——Agent每轮能拿到的不是上帝视角的全局坐标，而是来自虚拟摄像头、关节传感器、陀螺仪、加速度计和触觉传感器的噪声数据。你需要从这些数据里反推自己在哪里、球在哪里、队友在哪里，这个环节叫自定位与球跟踪。
第二道门槛是运动模型。NAO的腿只有6个关节，脚掌很小，走路、转身、踢球全要靠调整关节角度和力矩来实现重心控制。仿真环境中的地面摩擦、脚底打滑、惯性延迟都是真实存在的，不能像2D组那样直接给个速度指令就能移动。
第三道门槛是时间约束。SimSpark的交互周期是20毫秒左右，一个周期内你要完成"感知处理->状态预测->决策->动作计算->发指令"整条链路。复杂算法如果跑不完30Hz的循环，Agent就会表现为"发呆"或者"抽搐"，这在比赛里比实力差更难看。
1.2 规则演进对代码结构的影响
2012年前后的3D比赛用的是一个通用规则集，包括任意球、点球、角球、越位判罚等。这些规则听起来跟真实足球一样，但落到代码层面就非常棘手。比如任意球需要指定执行者和配合角色，代码里得有清晰的FoulState机；点球大战时的GoToBall和GoalieState切换，则是守门员模块里最容易出bug的部分。
2012年冠军队代码里比较值得称道的一点，就是把比赛规则处理从决策模块里剥离开，单独划分成了RefereeMessage解析、GameState管理、Strategy选择三层。这意味着每一轮仿真里，裁判发来的指令只影响GameState的字段，不会污染底层运动控制的计算逻辑。这个设计在当时很多队伍里并不常见，大多数队伍会把裁判状态直接塞进行为树的判断条件里，导致加一个新规则就要改动处调用。
2. 2012年那支南邮队伍的技术底色：为什么这套代码值得看
南京邮电大学在RoboCup 3D项目上的积累并不是突然爆发的。2012年夺冠之前，他们已经连续多年在国内外赛中打磨一套完整的仿真平台工具链，包括可视化的离线日志分析器、自动评测脚本、针对SimSpark物理参数的调参工具。说白了，冠军代码只是整个科研体系露在水面以上的那一小块。
2.1 底层运动控制：把NAO的步态当成一个带约束的优化问题
我研究过不少3D队伍的底层运动代码，2012年南邮那套在稳定性上的处理方法是很有代表性的。它把走路抽象为一个周期性步态规划问题，每个周期分为支撑相和摆动相，通过调节髋关节内外翻角度和踝关节的俯仰角度来维持重心（CoM）在支撑多边形内的投影。
核心参数大概是这样一组：步高（FootHeight）约 2.5 到 3.0 厘米，步长（StepLength）约 6 到 8 厘米，步频约 1.2 到 1.6 赫兹。仿真环境里这些数值不是越大越好，步长大了重心偏移厉害，步频快了关节力矩跟不上，都容易摔倒。他们代码里有一套根据球距离和目标角度动态调整步行参数的逻辑，跑起来比固定步态灵活很多。
2.2 高层决策：分层状态机和效用函数的混合体
2012年那个时代的3D仿真队伍，高层决策主要分两派：一派是纯状态机流，把场上情况划分为进攻、防守、带球、拦截等状态，逻辑简单但僵硬；另一派是纯效用函数流，每个动作算一个分数取最大，灵活但需要精细调权。
南邮那套代码采用的是两者混合的方式。比赛刚开始的阶段，Agent根据场上角色（前锋、中场、后卫、门将）进入各自的角色状态机；在每个状态内部，再通过效用函数选择具体动作。比如前锋在进攻状态下，面对"直接射门"、"短传队友"和"继续带球"三个选择，会分别计算成功率、风险值和对团队的收益，最后取综合分最高的动作。
这种设计的好处是，状态机保证了行为边界，效用函数保证了行为连续性，两者结合让Agent的动作既稳定又不至于太过机械。对于想做二次开发的队伍来说，这种架构改起来也最顺手——你可以只调效用函数的权重，就不动整体框架。
2.3 定位与感知：卡尔曼滤波在当时还是奢侈品
有一说一，2012年的3D仿真比赛里，大部分队伍的自定位仍然依赖简单三角函数加噪声假设，能做到标准卡尔曼滤波的都算认真，用无迹卡尔曼或者粒子滤波的屈指可数。南邮那套代码里，对自身位置的估计用的是一套带运动模型的多假设跟踪，对球的位置则用的是带指数平滑的扩展卡尔曼滤波。
这套组合的好处在于计算量可控。20个Agent如果每个周期都跑粒子滤波，对当时的机器性能压力太大；而多假设跟踪在计算复杂度和精度之间取得了很好的平衡。球的位置用扩展卡尔曼滤波，则可以很好地处理球在碰撞后的非线性速度变化，预测点的轨迹会更平滑。
3. 可执行代码核心模块拆解：控制链路里的五个层次
拿到一套比赛代码，最忌讳的是直接从头到尾读代码，读完就忘。我建议按照控制链路的分层结构来拆解。2012年南邮的代码，从最底层到最顶层可以分成五个层次：物理控制层、运动执行层、行为决策层、角色协调层和策略指挥层。
3.1 物理控制层：负责跟SimSpark的通信骨架和关节伺服
这一层主要封装了跟SimSpark服务器的通信逻辑。包括连接管理、消息解析与封装、模型初始化读取、每周期传感器数据入库和动作指令出库。看代码的时候，重点要看两个类：一个是WorldModel，它存放所有感知数据的当前快照；另一个是ActionCommand，它负责把高层下发的动作目标转换成SimSpark能识别的MotorCommand。
在二次开发时，这层几乎不需要动，但你必须理解它的数据流：每轮循环开始时，Agent从socket收一条消息，解析后塞进WorldModel；各上层模块从WorldModel读数据、写决策；最后ActionCommand把决策结果编码成关节目标角度和扭矩，发回服务器。理解清楚这个循环，就理解了整个Agent的呼吸节奏。
3.2 运动执行层：从走路到踢球的所有动作生成器
运动执行层是实现"想做动作"到"关节真的动了"的关键环节。这套代码里包括：
- WalkEngine：周期性的步态发生器，负责输出双腿6个关节（髋关节pitch/roll、膝关节pitch、踝关节pitch/roll）的角度曲线。
- KickEngine：根据踢球方向、球距离、支撑脚位置自动生成踢球动作。2012年的实现里已经把踢球分成了几种类型：大力射门、精准短传、调整球位后的扫射。
- TurnEngine：转身动作，依靠双脚交替的微小步幅实现原地转向，速度不快，但不会摔倒。
- GetUpEngine：摔倒起身动作，与2D仿真不同，3D里的NAO摔倒后无法自动恢复姿态，这个引擎是比赛中的隐形MVP。
这些引擎的共同点是都维护着一个动作参数结构和相位变量。理解起来可以把每个引擎看作一个黑盒函数：输入目标（比如"以6cm步长往前走1.2米"），输出每一帧的关节角度增量。
3.3 行为决策层：单Agent的Skill和Tactic框架
行为决策层负责"单个Agent这次心跳该干什么"。这层代码里有一个经典的双循环：技能（Skill）循环负责执行原子动作，比如WalkToPoint、TurnToAngle、KickToTarget；战术（Tactic）循环负责根据球位置、自身位置、比赛时间等信息在这些技能之间切换。
我特别建议看他们代码里Skill的接口设计。一个技能类一般有三个方法：初始化（Init）、每帧执行（Execute）、判断结束（Finished）。这种设计让上层策略可以非常优雅地组合技能——比如"带球推进"这个技能内部其实是"面向球跑->加速带球->避障"三个子技能串行执行的结果。如果理解了这个套路，你自己写新动作时就不会把逻辑全堆在一个巨大的函数里了。
3.4 角色协调层：所谓团队足球，其实是靠角色互斥和区域约束撑起来的
3D仿真里没有真正的"传球意识"，所谓团队配合，本质上是通过每个Agent对场上角色的自我认定和对手行为的约束来实现的。这套代码里，角色协调层由RoleManager统一管理，每个周期它会读取全队Agent的"位置-角色映射表"，然后根据动态优先级规则做互斥调整。
这里有一个非常关键的经验，也是很多队伍复现时容易忽略的：Agent之间的通信范围是有限的，而且是基于相对位置的。SimSpark里Agent之间可以通过无线通信模块发消息，但距离远了会丢包。所以角色协调层必须设计成"部分可观测"的——也就是说，每个Agent只能根据它能收到的队友消息和自身的感知来做本地判断，不能假设自己了解场上所有Agent的位置。
3.5 策略指挥层：进攻、防守、定位球的全局参数选择
最顶层是一个全局策略管理器，它会根据比分、比赛阶段（上半场/下半场/加时）、球的位置片段统计来切换整体打法和节奏参数。比如落后时加强进攻压上，领先时收缩防守。2012年那套代码里这个模块最实际的产出，是一组可以被管理员在比赛前通过配置文件覆盖的参数——比如阵型坐标、压上比例、边缘防守宽度等。
这里有个细节值得学习：他们把策略参数全部外部化到了一个XML/Config文件里，比赛前可以快速针对不同对手调整，而不需要重新编译。如果你要复刻这套架构，建议也这么干，省得比赛现场改代码还得改一个重新编译一个。
4. 自己跑起来：环境搭建与数据流验证的全过程
理论学习再多，不如把代码跑起来看一次真实比赛回放。下面我基于这套2012年代码的常见运行方式，整理一个完整的复现流程。不同版本细节不同，但大体思路一致。
4.1 编译环境的三个注意事项
RoboCup 3D Agent的代码大多基于Linux开发，推荐的发行版是Ubuntu 20.04或22.04（18.04也可，但新老依赖容易冲突）。编译整套代码之前，先装好以下几个核心依赖：
- SimSpark仿真器（从官方源码编译安装，别用预编译包，因为比赛版本跟预编译包的接口有差异）
- Boost库（版本1.74左右尽量不要太高，高版本编译早期代码容易出现兼容报错）
- CMake 3.10以上
编译的时候有个坑：有些代码依赖 Qt 的GUI模块来显示实时窗口，如果你是在纯服务器环境编译会报缺这些库。解决办法是安装 libqt4-dev 或 libqt5-dev 之后，重新生成 CMakeCache。如果只是跑仿真不看重显示，其实也可以关闭GUI编译选项。
4.2 启动一局比赛的完整命令流
自己验证代码能否正常工作，最简单的方式是让同一套代码打一场"镜像对战"——也就是红蓝双方用同一套Agent逻辑。这样能排除策略差异，只验证代码本身的稳定性。
# 启动SimSpark仿真服务器 rcssserver3d & # 启动一个示例Agent（蓝队前锋） ./agent --host=127.0.0.1 --port=3100 --team=left --number=1 & # 启动另一个示例Agent（红队前锋） ./agent --host=127.0.0.1 --port=3100 --team=right --number=1 &如果你用的是比赛官方比赛管理工具（rcssmonitor3d），还可以把全部20个Agent一起拉起来，直接自动开始一场仿真比赛。
4.3 用离线回放工具验证决策质量
跑通了还不够，比赛场地里18个外场球员加2个门将，20行日志看起来让人头大。我的建议是：第一步先只启动2个Agent（1 vs 1），边跑边用监控器看动作是否正常；第二步启动4个Agent（2 vs 2），初步验证传接配合和守门员反应；第三步才全开20个Agent看整体阵型和策略切换。
这过程中，SimSpark会自动生成本地日志文件（一般是 .rsg 和 .log 格式）。你可以用官方回放工具打开日志，逐帧查看某个Agent在某时刻为什么做了某个动作，这是排查"诡异行为"最直接的手段。
5. 复现冠军思路时最容易踩的五个坑
复现一套冠军代码，最难的不是让代码跑起来，而是让代码在你自己的环境里跑得跟描述一致。以下五个坑，我基本每次给新生培训都会强调一遍。
5.1 关节角度单位混淆：弧度与度数的经典失误
SimSpark底层的数据接口对关节角度的单位沿用了真实的SI单位制，关节角度使用弧度制。但很多早期的代码在配置文件中为了方便调试，用的是度数制。这就导致一个经典问题：Agent收到一个180度的指令，实际关节转过了3.14弧度，表现成转半圈就停了。排查方法很简单，看WorldModel里关节传感器的反馈角度值，如果数值范围明显跟预期不符，第一反应检查单位换算。
5.2 消息频率不平衡：决策周期跑不过物理周期
SimSpark的物理仿真周期是固定的（通常20ms一步），但Agent端的感知周期和决策周期不一定一致。有些代码在决策层里加入了复杂的路径规划算法，导致每帧计算时间超过20ms。这样会造成指令队列积压，表现为Agent的动作明显卡顿、延迟甚至漂移。遇到这种情况，优先优化决策层的时间复杂度，把成本高的计算（比如全局路径规划）改为多帧分期完成，而不是堆在一个周期里硬跑。
5.3 守门员状态机死循环：从右扑切换到左扑之间的边界条件
守门员模块是每支队伍最脆弱的部分。2012年那套代码里，守门员状态机在设计时通过一组"安全角"条件来防止死循环——只有当球进入守门员身前的扇形区域时，才允许发生左右扑救切换；如果球已经逼近到危险距离，则禁止切换状态，保持当前扑救动作。复现代码时，如果你发现守门员在球接近时反复左右抖动，八成就是边界条件写错了。
5.4 通信距离模型与位置预测的误差叠加
3D仿真里的Agent通信默认受距离衰减影响，如果你的代码假设队友永远能收到你的传球协作指令，那在球远离队友时就会出现"指令石沉大海"的情况。很多队伍在自测时只看20个Agent截图，觉得配合不错，但实际比赛中通信距离截断会让战术执行效果大打折扣。处理思路是在决策层给每次传球协作加一个距离置信度，距离越远置信度越低，超过阈值直接放弃协作转为本队控球。
5.5 不要迷信参数文件里的默认值
比赛代码的配置文件里写着一堆参数，比如重心高度比例、脚步相位偏移、射门阈值等，这些数值都是在特定物理引擎版本、特定NAO模型下调试出来的。当你更新了SimSpark版本，或者换了比赛用球的质量参数（球的半径、弹性系数），这些默认值很可能当场失效。复现代码后，一定要做的第一件事是自己重新跑一遍基础动作回归测试：走路、转身、踢球、起身、扑救，每项都观察是否符合预期，不符合就重新调参。
6. 后面可以怎么扩展这套代码
如果你已经成功跑通了这套2012年冠军代码，并且理解了它的分层架构，接下来有几个值得尝试的扩展方向，按难度递增。
第一个方向是给决策层接入机器学习模型。早期版本的行为决策大多是规则驱动的，你可以在Skill层里加入一个简单的强化学习模块，让Agent通过试错学习踢球的角度和力度映射。注意不要一上来就尝试端到端深度强化学习，仿真环境下很容易过拟合，而且一局仿真时间太长，样本效率很低。
第二个方向是优化通信协议。原始代码里的队友通信消息结构比较简单，通常只包含位置、自定位置信度、目标角色。你可以扩展消息类型，加入队友的意图预测（比如"我准备射门"或者"我在回防"），这样角色协调层就能做出更合理的全局调整。
第三个方向是把这套架构迁移到其他仿真环境。SimSpark和Webots在物理引擎上有很多相通之处，如果你把运动执行层的接口抽象得足够干净，底层接Webots，高层决策完全可以复用。这也是很多做仿真到真实迁移的研究组所走的路径。
我在实际看这套代码和指导学生复现的过程中，最深的一个体会是：冠军代码最值钱的不是某个巧妙技巧，而是整个工程结构的稳定性。你随手改一个效用函数的权重，比赛成绩可能就跌一个档次，但如果你把模块间的交互接口保持干净，改哪里、影响哪里永远清晰可见，这种确定性在比赛现场比任何花哨算法都靠得住。希望这篇拆解能让你少走一些弯路，哪怕只看懂其中一层，也算没白读。
本文还有配套的精品资源，点击获取
