简介这份2012年RoboCup 3D仿真足球赛南京邮电大学冠军队伍的可执行代码包面向机器人仿真、多智能体协作与竞赛复盘的学习者可用于研究Apollo3D平台下的自主决策、团队配合和实时策略执行。压缩包为gz格式共175个文件、约29.13MB以76个rsg文件与69个svn-base版本库元数据为主辅以Ruby脚本、Shell启动脚本、动态库及apollo3d相关组件保留了较完整的工程组织、依赖关系与版本控制痕迹。已有899人学习适合作为竞赛代码阅读与实验环境搭建的参考。读者可从中观察冠军队伍如何划分策略模块、组织球员角色文件、通过脚本启动仿真并调用底层库进而理解多智能体协同、强化学习策略和实时通信在真实赛题代码中的落地方式也可为自动驾驶、无人机编队等群体智能研究提供借鉴对理解当年参赛工程的环境配置与调试流程亦有帮助。1. 一支仿真球队是怎么跑起来的11 个进程、一个仿真服务器和一堆 UDP 小包2012 年那届 3D 仿真机器人足球赛的冠军智能体解压出来既不是一个大工程也不是一个能双击运行的 exe而是一堆源码、一份 CMake 配置和几张阵型表。比赛的实际情况是仿真服务器里跑一块 20ms 步进的物理世界场上 11 个独立进程各自接收自己视角的视觉、听觉和本体感知各自建一份世界模型各自算决策再用 UDP 报文互相喊话。这份可执行代码包就是那支队伍的完整智能体实现从底层步态、起身、踢球技能到上层阵型、角色分配和多人协作。它适合两类人一类是课程设计或毕设要做多智能体对抗、想找一个能编译能跑的完整参考实现另一类是已经上手过单智能体控制想看多人协同里定位、通信、角色切换怎么写。下面按“能干什么—怎么跑—怎么改”的顺序拆开。2. 代码包结构与技术栈先看清 cmake 与三套依赖再动手拿到压缩包别急着make。这套代码的依赖关系和普通 C 项目不太一样它要和外部仿真服务器做二进制级的协议对接服务器版本、agent 端的解析逻辑、监视器的渲染库三者必须对得上否则编译能过、跑起来就是连不上或者连上就掉线。2.1 目录长什么样从 main.cpp 到 formations我把包解开后按职责重排了一下结构大致是这样各目录的职责边界很清楚看一遍就能知道改哪个文件apollo3d/ ├── CMakeLists.txt # 顶层构建负责找 simspark 三件套 ├── src/ │ ├── main.cpp # 解析命令行参数、建连接、进主循环 │ ├── agent/ │ │ ├── AgentController.* # 与服务器收发报文的封装 │ │ ├── WorldModel.* # 全局世界模型球、我、队友、对手 │ │ └── Behavior.* # 决策层按角色选当前行为 │ ├── perception/ │ │ ├── Vision.* # 视觉对象解析极坐标 斜视角 │ │ ├── Localization.* # 粒子滤波定位 │ │ └── Communication.* # say/listen 报文编解码 │ ├── skills/ │ │ ├── Walk.* Turn.* # 步态与转向 │ │ ├── Kick.* GetUp.* # 踢球与倒地起身 │ │ └── SkillBase.* # 技能基类统一 execute 接口 │ └── utils/ # 数学、日志、参数解析 ├── conf/ │ ├── formations/ # 4-3-3、4-4-2 等阵型表 │ ├── playerTypes.conf # 球员号到身高/速度/臂长的映射 │ └── agent.conf # 阈值、开关、调试输出等级 ├── scripts/ │ ├── start_server.sh # 起仿真服务器 │ ├── start_monitor.sh # 起三维监视器 │ ├── start_team.sh # 一次拉起 11 个 agent │ └── kill_all.sh # 清场调试时一天要跑几十次 └── build/ # 外部构建目录别往仓库里提交src下的分层是典型的“感知—建模—决策—执行”四段式skills和behavior拆开是有原因的技能层只关心关节怎么动决策层只关心现在该不该踢两层之间用世界坐标传参后面改行为树的时候不用碰底层步态。2.2 技术栈定死在三样东西上仿真服务器、三维渲染、C 智能体这套代码的技术栈没有什么花哨的东西但每一样都不能随便换版本层次组件作用备注仿真层3D 仿真服务器物理世界、裁判、比分必须先装agent 依赖它的开发库渲染层三维监视器可视化看球纯观察用不影响比赛结果基础库oxygen / kerosin / zeitgeist数学、渲染、场景图服务器和监视器的公共依赖智能体CC98/03 风格感知解析、决策、技能单进程单球员构建CMake找库、生成二进制需要手动指定依赖前缀协作UDP say 报文队友间共享球和位置有长度上限后面细说语言用 C 而不是脚本是因为 20ms 一个周期里要做粒子滤波更新、十几条腿关节的角度计算还要留出通信和日志的时间脚本语言在那个年代的机器上撑不住。代码里大量裸指针和定长数组看着不现代但延迟稳定这一点在对抗类仿真里比可读性重要。2.3 编译链路与依赖关系CMake 怎么找到那几个库编译顺序不能反先仿真服务器及其依赖再 agent。CMake 找库靠的是前缀路径我第一次编的时候就是库装在/usr/local下但没告诉 CMake报了一屏Could NOT find OXYGEN。# 1. 先确认仿真服务器的开发库装好了头文件和 so 都在 ls /usr/local/include/oxygen /usr/local/lib/liboxygen* # 2. 外部构建别在源码目录里 make避免污染 mkdir -p build cd build # 3. 把依赖前缀显式喂给 CMake这一步是新手最容易漏的 cmake .. \ -DCMAKE_BUILD_TYPERelease \ -DCMAKE_PREFIX_PATH/usr/local \ -DCMAKE_CXX_FLAGS-O2 -marchnative # 4. 并行编机器弱的话 -j2不然内存容易打满 make -j4 # 5. 产物检查应该出现一个 agentspark 之类的可执行文件 ls -lh bin/CMAKE_PREFIX_PATH指的是仿真服务器安装的根目录include和lib都在它下面CMAKE_BUILD_TYPERelease必须开Debug 版本在 20ms 周期里跑粒子滤波会掉帧掉帧就意味着这个周期你的球员什么都没做场上看起来就是“发呆”。-marchnative可加可不加同一台机器上编译和运行才有意义换机器部署要删掉。编完之后先别急着联机用--help确认参数解析正常很多连接问题其实是参数名拼错程序静默用了默认值./bin/agentspark --help提示如果make报链接错误但头文件都找到了八成是服务器装的是静态库、agent 按动态库找。看ldd ./bin/agentspark里有没有not found有就补LD_LIBRARY_PATH。3. 启动全链路从仿真服务器到 11 个智能体接入这套东西的运行方式和普通程序最大的差别是它没有“主程序”。仿真服务器是主agent 是客户端服务器不点头agent 就一直等在那儿。所以启动顺序、端口占用、队名和球衣号的唯一性任何一项出错都会表现为“程序起来了但场上没人”。3.1 先把仿真服务器和监视器跑起来服务器负责物理和裁判监视器负责让你看见发生了什么。调试期我建议始终开着监视器很多逻辑错误比如球员一直原地转圈看两眼就明白了光看日志能查一晚上。# 启动仿真服务器默认监听 agent 端口 3100、监视器端口 3200 # 前台运行日志直接打屏方便第一时间看到连接和判罚信息 rcssserver3d --port 3100 --monitorPort 3200 # 另开一个终端起三维监视器连上去 # 连不上就先确认 3200 没被占ss -lntp | grep 3200 ./scripts/start_monitor.sh --host 127.0.0.1 --port 3200服务器日志里有几个关键信息要盯accepted connection说明 agent 连上了player type说明球衣号绑定到了哪种异构球员kick off说明比赛真的开始了。如果日志里一直停在等待状态通常是场上人数不够或者两队没有都到齐仿真比赛要求两边都有人才会开球。监视器连上后是黑屏先别怀疑代码八成是 OpenGL 环境问题。服务器上跑没有显卡的机器监视器起不来很正常这时候用无头模式跑对抗靠日志和回放分析结果效率反而更高。3.2 智能体接入参数host、port、teamname、unum单个 agent 的启动参数是整套系统里最需要记牢的东西四个参数错一个就连不上或者连上去被踢参数含义常见取值出错表现--host服务器地址127.0.0.1一直重连日志刷屏--portagent 端口3100连上后立刻断开--teamname队名Apollo3D两队同名服务器拒绝--unum球衣号1到11同队重号后到的被踢--syncret同步模式开关0/1不匹配时步进错位启动一个前锋# 参数用等号形式某些解析实现不认空格分隔 ./bin/agentspark \ --host127.0.0.1 \ --port3100 \ --teamnameApollo3D \ --unum11unum不只是编号它同时决定了这个球员的异构类型1 号一般是守门员身高和臂长参数不同抓球判定也不一样2 到 11 号是场上球员速度、加速度、关节范围都在conf/playerTypes.conf里绑定。改球衣号等于换了一个身体步态参数要跟着调这一点后面二次开发会再说。3.3 一队人怎么一次性拉起来脚本与进程管理手动开 11 个终端不现实队里一般都有一份启动脚本。脚本的核心就是循环加后台运行再加一个清场逻辑因为调试期最烦的就是上一场的进程没死干净端口占着新的一队人全连不上。#!/usr/bin/env bash # start_team.sh拉起一整队参数 1 是队名参数 2 是球员数量 set -e TEAM${1:-Apollo3D} COUNT${2:-11} # 先清场把上一轮残留的 agent 全干掉 pkill -f agentspark --teamname${TEAM} || true sleep 1 for i in $(seq 1 ${COUNT}); do # 每个进程独立日志出问题只看对应球衣号那一份 ./bin/agentspark \ --host127.0.0.1 --port3100 \ --teamname${TEAM} --unum${i} \ log/${TEAM}_${i}.log 21 # 稍微错开启动避免 11 个进程同一毫秒抢连接 sleep 0.2 done echo team ${TEAM} started with ${COUNT} playerspkill -f的匹配串要写得足够具体只匹配队名不要匹配agentspark否则会把自己这条脚本之外的调试进程也杀掉。sleep 0.2这个错峰是我踩过坑之后加的11 个进程同时发起连接服务器那边偶发丢包表现就是某一号球员一直连不上重跑一次又好了典型的环境玄学问题加个延时最省事。两队对抗就再跑一遍脚本换个队名。跑起来之后先别改代码用监视器看满一整场观察三件事球员会不会自己站起来、拿到球会不会往对方半场走、丢球之后会不会回追。这三件事对应技能层、决策层、角色分配三个不同层次的问题先定位层次再改代码比上来就翻源码高效得多。4. 核心模块拆解一个感知周期里到底发生了什么20ms 一个周期从服务器推感知过来到 agent 把关节指令发回去中间要过四道手解析感知、更新世界模型、选行为、算技能。这四步任何一步超时这个周期就等于白送。拆代码的时候建议按这个顺序读main.cpp里就是这几行的循环。4.1 主循环step、update、think、execute 四段主循环写得非常朴素所有复杂度都在四个函数里面。这段是整个项目的骨架读懂它剩下的都是细节// main.cpp 核心循环去掉参数解析和异常处理后的主干 while (mController-isAlive()) { // 1. 阻塞等待服务器推来一帧感知内含视觉、听觉、本体感知 if (!mController-step()) break; // 2. 用这一帧感知更新世界模型球、队友、对手、自己的位姿 mWorldModel-update(mController-sensor()); // 3. 决策层根据当前角色和场上态势选一个行为 mBehavior-think(mWorldModel); // 4. 技能层把行为翻译成关节指令本周期内必须算完 mBehavior-currentSkill()-execute(mController); // 5. 心跳日志调试期开比赛期关写盘会拖慢周期 if (mDebug) mLogger-tick(mWorldModel); }step()是阻塞的它返回就意味着这一帧的感知已经到齐此时世界模型里的数据是自洽的不要在多线程里异步改模型。think只管选行为不允许在里面做耗时计算粒子滤波这类重活放在update里。execute只负责下发指令不负责判断该不该做这个边界一旦破坏行为层和技能层就会互相污染后期改一个步态会牵动半个决策树。这里有个隐性的时序约定本周期算出的指令服务器在下一个周期才生效。也就是说你的球员永远在“慢一拍”地响应世界做预测和提前量是必需的不是优化项是正确性的一部分。4.2 世界模型把极坐标视觉拼成球场坐标视觉输入不是笛卡尔坐标而是以头部为中心的极坐标加斜视角还带噪声而且一帧只给你视野锥内的东西。世界模型要干的事就是把这些碎片的观测结合自己的本体感知关节角度、陀螺仪和定位结果拼成一份全局视图。定位这块当年的主流做法是粒子滤波撒一批粒子每个粒子代表一个可能的位姿用观测到的地标球门柱、场地线交点去打分重采样。简化版用两根球门柱做三角解算够用但一旦被遮挡就飘。核心逻辑长这样// WorldModel::update本帧观测融合 void WorldModel::update(const SensorInput in) { // 本体感知始终可信先更新自身关节和朝向 mSelf.updateJoints(in.jointAngles); mSelf.updateGyro(in.gyro); // 视觉对象逐个转成球场坐标beamed 表示服务器直接给的精确值 for (const auto obj : in.visionObjects) { Vec3f pos mSelf.toWorldFrame(obj.polar, obj.azimuth); switch (obj.type) { case OBJ_BALL: // 球用卡尔曼滤波平滑速度比位置更容易被噪声带偏 mBall.update(pos, obj.beamed); break; case OBJ_FLAG: // 地标喂给粒子滤波权重在这里更新 mLocalization.observe(obj.type, pos); break; case OBJ_PLAYER: mPlayers.track(obj.unum, pos, obj.team); break; } } // 每 N 帧重采样一次太频繁会抖动太稀疏会跟丢 if (mFrame % 5 0) mLocalization.resample(); }toWorldFrame里的polar是距离azimuth是水平方位角垂直角度用来算高度三者加上自身位姿就得到世界坐标。beamed是个开关性质的字段服务器在某些情况下比如球进了自家禁区附近会给精确值这时候直接采信不要再过滤波器否则反而引入延迟。粒子滤波的重采样周期 5 帧是个经验值改小了定位抖改大了跟丢人不同球员类型守门员和前锋的运动特性差别很大可以分开配。4.3 技能层走路、转身、踢球的参数化实现技能层的接口很统一都是execute返回是否完成。走路是最基础也最难调的一块仿真里的双足行走本质上是关节角度序列的周期函数参数全靠手工调。以下是转向加前进的组合逻辑实际代码里还有侧移和抗扰// Walk::execute走向世界坐标下的目标点 bool Walk::execute(AgentController* agent, const Vec3f target, double speed) { // 1. 世界坐标转机器人自身坐标系只关心平面 Vec3f local mWorldModel-toRobotFrame(target); double dist local.length(); // 2. 球在侧后方时先转身再走硬走会绕大圈实测差半秒以上 double theta atan2(local.y(), local.x()); if (fabs(theta) DEG2RAD(30.0)) { return mTurn.execute(agent, theta); } // 3. 距离近就降速避免冲过头被球绊倒是的会绊倒 double v speed * clamp(dist / 1.5, 0.3, 1.0); // 4. 按步态表下发关节速度mGait 是离线调好的周期参数 for (int j 0; j mJointNum; j) { double phase mGaitPhase[j]; agent-setJointSpeed(j, mGait[j] * v * sin(phase)); } mGaitPhase mGaitStep; return dist 0.3; // 到点即视为完成 }DEG2RAD(30.0)是转身阈值超过就先转这个值是调出来的设小了走 Z 字设大了绕远路。clamp(dist / 1.5, 0.3, 1.0)是速度缩放1.5 米以内的减速区间下限 0.3 保证再近也在动不然会停在球前面“思考人生”。mGait每个关节一个系数mGaitStep决定步频这两个数组是整个项目里最需要耐心的地方改一个数整个步态就废了。踢球技能类似但它多一个“触球窗口”球必须在脚的可触及范围内且相对速度方向合适才真正发力否则就是空踢。这个窗口判定写错场上表现就是球员对着球疯狂抬腿但球纹丝不动。4.4 通信与协作say 消息怎么塞进有限字节里11 个人各看各的视角不通信就是 11 个近视眼各踢各的。仿真里的 say 是广播同队都能收到但有长度上限当年是 20 个字符左右卡得很死所以消息必须编码压缩不能发自然语言。// 广播球的位置和速度B 是类型前缀后面四个字段各保留两位小数 // 注意总长度必须控制在协议上限内超了会被截断甚至丢弃 char buf[32]; int n snprintf(buf, sizeof(buf), B%.1f,%.1f,%.1f,%.1f, ball.x(), ball.y(), ball.vx(), ball.vy()); if (n 0 n (int)sizeof(buf)) { mController-say(buf); } // 接收端按前缀分发解析失败直接丢弃不要 try/catch 到主循环 void Communication::onSay(const std::string msg) { if (msg.empty()) return; switch (msg[0]) { case B: mWorldModel-fuseBallFromTeammate(msg); break; case S: mWorldModel-fuseSelfFromTeammate(msg); break; default: break; // 未知前缀忽略保持向前兼容 } }snprintf的返回值一定要判返回负数说明编码失败返回大于等于缓冲区说明被截断两种情况都不能发。前缀字符的选择有讲究用一个字母区分消息类型比在固定位置放类型字段更省字节也更容易做向前兼容——以后加新消息类型老代码遇到不认识的前缀直接忽略不会崩。队友信息融合要谨慎别人报的球位置是他自己视角算出来的带有他的定位误差简单平均会把自己的精度也拉低。常见的做法是给自己的观测更高权重队友消息只在视野盲区时作为补充这条在防守回追时差别非常明显。5. 避坑与排查五类翻车场景和它们的解这套代码的报错信息普遍不友好连不上就是连不上不告诉你为什么。下面这五条是我在复现和改代码过程中反复遇到的每条都按现象、原因、解决的顺序写清楚照着排查能省不少时间。5.1 编译与依赖类问题第一条CMake 报找不到 oxygen / kerosin。现象是cmake ..直接失败提示Could NOT find OXYGEN (missing: OXYGEN_LIBRARY OXYGEN_INCLUDE_DIR)。原因基本是两个仿真服务器根本没装开发包或者装了但装在非标准前缀CMake 的默认搜索路径里没有。解决顺序是先ls /usr/local/lib | grep oxygen确认库存在再用-DCMAKE_PREFIX_PATH/usr/local显式指定。如果库确实不在那就先回去把仿真服务器编译安装一遍注意安装时别跳过make install只编译不安装等于没有开发包。第二条编译过了运行时报 so 找不到。现象是./bin/agentspark提示error while loading shared libraries: liboxygen.so。原因是编译期靠CMAKE_PREFIX_PATH找到了库运行期动态链接器不知道去哪儿找。解决要么把路径写进/etc/ld.so.conf.d/再ldconfig要么临时export LD_LIBRARY_PATH/usr/local/lib:$LD_LIBRARY_PATH。前者一劳永逸后者适合在容器里临时跑。排查时ldd ./bin/agentspark | grep not found一眼就能看出缺哪个。5.2 连接与对抗类问题第三条agent 一连上就被断开。现象是日志里出现连接成功后立刻 disconnect服务器那边显示 illegal connection。原因通常是队名或球衣号冲突同队两个 11 号后连的那个必被踢两队用了同一个队名服务器认为是同一支队在超员。解决是先用ps aux | grep agentspark看有没有残留进程再检查start_team.sh里传给--unum的循环变量是不是从 1 开始。用pkill -f teamname你的队名清干净再起。第四条球员原地转圈或者对着球疯狂抬腿但球不动。现象是监视器里看得很清楚球员围绕某个点不停旋转或者距离球只有半米却踢不到。原因分别是视觉解析时没有正确处理球不在视野锥内的情况定位飘了之后目标点算错走路技能就会不停修正朝向形成转圈踢球技能的触球窗口用世界坐标判定而没用自身坐标系或者球的高度算错。解决办法是先关掉决策层的复杂逻辑只留“lookAt 球然后走过去踢”这条最小链路能踢到再加回角色和协作。定位问题就打开--debug把粒子云打出来看粒子全糊成一团就是观测权重写反了。第五条比赛跑着跑着整体卡顿周期越拖越长。现象是刚开始流畅跑一两分钟后所有球员动作变慢日志写盘时间越来越长。原因是调试日志同步写文件每个周期都 flush磁盘 IO 拖垮了主循环。解决是把日志改成异步写或者只在特定球衣号上开日志比赛模式下mDebug直接关掉。另外检查一下有没有在think里做了粒子滤波这类重计算那个必须放在update里。注意调试期看到一个球员行为异常先看它那份独立日志不要一起看 11 份。日志里每帧打印的世界模型状态比监视器画面能说明的问题多得多。6. 二次开发换阵型、加技能、改决策层的稳妥路径改动从代价最小的地方开始。第一层是纯配置阵型文件和球员类型表都在conf/下换打法不用重编译。阵型文件定义每个球衣号在不同球状态下的目标位置格式大致是“名字 球衣号 坐标序列”改坐标就能把 4-3-3 变成 4-4-2。这一层的坑在于坐标是球场绝对坐标且服务器会按球员类型限制活动范围守门员的位置填到对方半场场上表现就是他站在原地不动。第二层是加技能。新技能继承技能基类实现execute即可但要遵守两条约定只下发指令不做决策以及返回布尔值表示是否完成。技能内部不要读全局状态所有需要的数据从世界模型传入这样单元测试能单独跑不用起服务器。我一般会先在无对抗场景里验证技能用一个固定的球位置反复调用看关节角度曲线是否收敛收敛了再放进对抗。第三层才是动决策层。原始的 if-else 风格行为选择在角色少的时候够用一旦要加“回防优先级”“协防补位”就会变成一大坨嵌套。换成行为树或者状态机都可以关键是把“角色分配”和“行为选择”拆开角色由阵型和球位置决定行为由角色和当前局面决定两层之间的接口只有几个字段。改造目标动哪里重编译验证方式换打法conf/formations/*否看站位是否符合预期调步态skills/Walk.cpp参数表是单技能无对抗回放加技能新增skills/xxx.cpp是固定球位置反复调用换决策agent/Behavior.cpp是整场对抗 日志统计验证这块我有一个固定流程改完先跑单队无对手 3 分钟确认没人摔倒、没人卡住再跑两队对抗 10 场用脚本统计进球数和控球时间。日志里把每帧的球位置和角色记下来一个简单的 Python 脚本就能算出控球率比肉眼看监视器靠谱得多。批量跑的时候把监视器关掉省下来的渲染开销能让仿真跑快不少。血泪经验是每次只改一个变量。步态系数和决策阈值一起改出了问题根本不知道该回滚哪个最后只能整个目录 git checkout。从那以后我每次动技能参数前都强制走一遍“单技能验证—无对抗整场—对抗十场”这条链路慢是慢一点但省下的排查时间远不止这些。这套 2012 年的冠军代码放到今天架构上依然站得住值得拿来当多智能体对抗的练手底子。希望帮到你。本文还有配套的精品资源点击获取
简介这份2012年RoboCup 3D仿真足球赛南京邮电大学冠军队伍的可执行代码包面向机器人仿真、多智能体协作与竞赛复盘的学习者可用于研究Apollo3D平台下的自主决策、团队配合和实时策略执行。压缩包为gz格式共175个文件、约29.13MB以76个rsg文件与69个svn-base版本库元数据为主辅以Ruby脚本、Shell启动脚本、动态库及apollo3d相关组件保留了较完整的工程组织、依赖关系与版本控制痕迹。已有899人学习适合作为竞赛代码阅读与实验环境搭建的参考。读者可从中观察冠军队伍如何划分策略模块、组织球员角色文件、通过脚本启动仿真并调用底层库进而理解多智能体协同、强化学习策略和实时通信在真实赛题代码中的落地方式也可为自动驾驶、无人机编队等群体智能研究提供借鉴对理解当年参赛工程的环境配置与调试流程亦有帮助。1. 一支仿真球队是怎么跑起来的11 个进程、一个仿真服务器和一堆 UDP 小包2012 年那届 3D 仿真机器人足球赛的冠军智能体解压出来既不是一个大工程也不是一个能双击运行的 exe而是一堆源码、一份 CMake 配置和几张阵型表。比赛的实际情况是仿真服务器里跑一块 20ms 步进的物理世界场上 11 个独立进程各自接收自己视角的视觉、听觉和本体感知各自建一份世界模型各自算决策再用 UDP 报文互相喊话。这份可执行代码包就是那支队伍的完整智能体实现从底层步态、起身、踢球技能到上层阵型、角色分配和多人协作。它适合两类人一类是课程设计或毕设要做多智能体对抗、想找一个能编译能跑的完整参考实现另一类是已经上手过单智能体控制想看多人协同里定位、通信、角色切换怎么写。下面按“能干什么—怎么跑—怎么改”的顺序拆开。2. 代码包结构与技术栈先看清 cmake 与三套依赖再动手拿到压缩包别急着make。这套代码的依赖关系和普通 C 项目不太一样它要和外部仿真服务器做二进制级的协议对接服务器版本、agent 端的解析逻辑、监视器的渲染库三者必须对得上否则编译能过、跑起来就是连不上或者连上就掉线。2.1 目录长什么样从 main.cpp 到 formations我把包解开后按职责重排了一下结构大致是这样各目录的职责边界很清楚看一遍就能知道改哪个文件apollo3d/ ├── CMakeLists.txt # 顶层构建负责找 simspark 三件套 ├── src/ │ ├── main.cpp # 解析命令行参数、建连接、进主循环 │ ├── agent/ │ │ ├── AgentController.* # 与服务器收发报文的封装 │ │ ├── WorldModel.* # 全局世界模型球、我、队友、对手 │ │ └── Behavior.* # 决策层按角色选当前行为 │ ├── perception/ │ │ ├── Vision.* # 视觉对象解析极坐标 斜视角 │ │ ├── Localization.* # 粒子滤波定位 │ │ └── Communication.* # say/listen 报文编解码 │ ├── skills/ │ │ ├── Walk.* Turn.* # 步态与转向 │ │ ├── Kick.* GetUp.* # 踢球与倒地起身 │ │ └── SkillBase.* # 技能基类统一 execute 接口 │ └── utils/ # 数学、日志、参数解析 ├── conf/ │ ├── formations/ # 4-3-3、4-4-2 等阵型表 │ ├── playerTypes.conf # 球员号到身高/速度/臂长的映射 │ └── agent.conf # 阈值、开关、调试输出等级 ├── scripts/ │ ├── start_server.sh # 起仿真服务器 │ ├── start_monitor.sh # 起三维监视器 │ ├── start_team.sh # 一次拉起 11 个 agent │ └── kill_all.sh # 清场调试时一天要跑几十次 └── build/ # 外部构建目录别往仓库里提交src下的分层是典型的“感知—建模—决策—执行”四段式skills和behavior拆开是有原因的技能层只关心关节怎么动决策层只关心现在该不该踢两层之间用世界坐标传参后面改行为树的时候不用碰底层步态。2.2 技术栈定死在三样东西上仿真服务器、三维渲染、C 智能体这套代码的技术栈没有什么花哨的东西但每一样都不能随便换版本层次组件作用备注仿真层3D 仿真服务器物理世界、裁判、比分必须先装agent 依赖它的开发库渲染层三维监视器可视化看球纯观察用不影响比赛结果基础库oxygen / kerosin / zeitgeist数学、渲染、场景图服务器和监视器的公共依赖智能体CC98/03 风格感知解析、决策、技能单进程单球员构建CMake找库、生成二进制需要手动指定依赖前缀协作UDP say 报文队友间共享球和位置有长度上限后面细说语言用 C 而不是脚本是因为 20ms 一个周期里要做粒子滤波更新、十几条腿关节的角度计算还要留出通信和日志的时间脚本语言在那个年代的机器上撑不住。代码里大量裸指针和定长数组看着不现代但延迟稳定这一点在对抗类仿真里比可读性重要。2.3 编译链路与依赖关系CMake 怎么找到那几个库编译顺序不能反先仿真服务器及其依赖再 agent。CMake 找库靠的是前缀路径我第一次编的时候就是库装在/usr/local下但没告诉 CMake报了一屏Could NOT find OXYGEN。# 1. 先确认仿真服务器的开发库装好了头文件和 so 都在 ls /usr/local/include/oxygen /usr/local/lib/liboxygen* # 2. 外部构建别在源码目录里 make避免污染 mkdir -p build cd build # 3. 把依赖前缀显式喂给 CMake这一步是新手最容易漏的 cmake .. \ -DCMAKE_BUILD_TYPERelease \ -DCMAKE_PREFIX_PATH/usr/local \ -DCMAKE_CXX_FLAGS-O2 -marchnative # 4. 并行编机器弱的话 -j2不然内存容易打满 make -j4 # 5. 产物检查应该出现一个 agentspark 之类的可执行文件 ls -lh bin/CMAKE_PREFIX_PATH指的是仿真服务器安装的根目录include和lib都在它下面CMAKE_BUILD_TYPERelease必须开Debug 版本在 20ms 周期里跑粒子滤波会掉帧掉帧就意味着这个周期你的球员什么都没做场上看起来就是“发呆”。-marchnative可加可不加同一台机器上编译和运行才有意义换机器部署要删掉。编完之后先别急着联机用--help确认参数解析正常很多连接问题其实是参数名拼错程序静默用了默认值./bin/agentspark --help提示如果make报链接错误但头文件都找到了八成是服务器装的是静态库、agent 按动态库找。看ldd ./bin/agentspark里有没有not found有就补LD_LIBRARY_PATH。3. 启动全链路从仿真服务器到 11 个智能体接入这套东西的运行方式和普通程序最大的差别是它没有“主程序”。仿真服务器是主agent 是客户端服务器不点头agent 就一直等在那儿。所以启动顺序、端口占用、队名和球衣号的唯一性任何一项出错都会表现为“程序起来了但场上没人”。3.1 先把仿真服务器和监视器跑起来服务器负责物理和裁判监视器负责让你看见发生了什么。调试期我建议始终开着监视器很多逻辑错误比如球员一直原地转圈看两眼就明白了光看日志能查一晚上。# 启动仿真服务器默认监听 agent 端口 3100、监视器端口 3200 # 前台运行日志直接打屏方便第一时间看到连接和判罚信息 rcssserver3d --port 3100 --monitorPort 3200 # 另开一个终端起三维监视器连上去 # 连不上就先确认 3200 没被占ss -lntp | grep 3200 ./scripts/start_monitor.sh --host 127.0.0.1 --port 3200服务器日志里有几个关键信息要盯accepted connection说明 agent 连上了player type说明球衣号绑定到了哪种异构球员kick off说明比赛真的开始了。如果日志里一直停在等待状态通常是场上人数不够或者两队没有都到齐仿真比赛要求两边都有人才会开球。监视器连上后是黑屏先别怀疑代码八成是 OpenGL 环境问题。服务器上跑没有显卡的机器监视器起不来很正常这时候用无头模式跑对抗靠日志和回放分析结果效率反而更高。3.2 智能体接入参数host、port、teamname、unum单个 agent 的启动参数是整套系统里最需要记牢的东西四个参数错一个就连不上或者连上去被踢参数含义常见取值出错表现--host服务器地址127.0.0.1一直重连日志刷屏--portagent 端口3100连上后立刻断开--teamname队名Apollo3D两队同名服务器拒绝--unum球衣号1到11同队重号后到的被踢--syncret同步模式开关0/1不匹配时步进错位启动一个前锋# 参数用等号形式某些解析实现不认空格分隔 ./bin/agentspark \ --host127.0.0.1 \ --port3100 \ --teamnameApollo3D \ --unum11unum不只是编号它同时决定了这个球员的异构类型1 号一般是守门员身高和臂长参数不同抓球判定也不一样2 到 11 号是场上球员速度、加速度、关节范围都在conf/playerTypes.conf里绑定。改球衣号等于换了一个身体步态参数要跟着调这一点后面二次开发会再说。3.3 一队人怎么一次性拉起来脚本与进程管理手动开 11 个终端不现实队里一般都有一份启动脚本。脚本的核心就是循环加后台运行再加一个清场逻辑因为调试期最烦的就是上一场的进程没死干净端口占着新的一队人全连不上。#!/usr/bin/env bash # start_team.sh拉起一整队参数 1 是队名参数 2 是球员数量 set -e TEAM${1:-Apollo3D} COUNT${2:-11} # 先清场把上一轮残留的 agent 全干掉 pkill -f agentspark --teamname${TEAM} || true sleep 1 for i in $(seq 1 ${COUNT}); do # 每个进程独立日志出问题只看对应球衣号那一份 ./bin/agentspark \ --host127.0.0.1 --port3100 \ --teamname${TEAM} --unum${i} \ log/${TEAM}_${i}.log 21 # 稍微错开启动避免 11 个进程同一毫秒抢连接 sleep 0.2 done echo team ${TEAM} started with ${COUNT} playerspkill -f的匹配串要写得足够具体只匹配队名不要匹配agentspark否则会把自己这条脚本之外的调试进程也杀掉。sleep 0.2这个错峰是我踩过坑之后加的11 个进程同时发起连接服务器那边偶发丢包表现就是某一号球员一直连不上重跑一次又好了典型的环境玄学问题加个延时最省事。两队对抗就再跑一遍脚本换个队名。跑起来之后先别改代码用监视器看满一整场观察三件事球员会不会自己站起来、拿到球会不会往对方半场走、丢球之后会不会回追。这三件事对应技能层、决策层、角色分配三个不同层次的问题先定位层次再改代码比上来就翻源码高效得多。4. 核心模块拆解一个感知周期里到底发生了什么20ms 一个周期从服务器推感知过来到 agent 把关节指令发回去中间要过四道手解析感知、更新世界模型、选行为、算技能。这四步任何一步超时这个周期就等于白送。拆代码的时候建议按这个顺序读main.cpp里就是这几行的循环。4.1 主循环step、update、think、execute 四段主循环写得非常朴素所有复杂度都在四个函数里面。这段是整个项目的骨架读懂它剩下的都是细节// main.cpp 核心循环去掉参数解析和异常处理后的主干 while (mController-isAlive()) { // 1. 阻塞等待服务器推来一帧感知内含视觉、听觉、本体感知 if (!mController-step()) break; // 2. 用这一帧感知更新世界模型球、队友、对手、自己的位姿 mWorldModel-update(mController-sensor()); // 3. 决策层根据当前角色和场上态势选一个行为 mBehavior-think(mWorldModel); // 4. 技能层把行为翻译成关节指令本周期内必须算完 mBehavior-currentSkill()-execute(mController); // 5. 心跳日志调试期开比赛期关写盘会拖慢周期 if (mDebug) mLogger-tick(mWorldModel); }step()是阻塞的它返回就意味着这一帧的感知已经到齐此时世界模型里的数据是自洽的不要在多线程里异步改模型。think只管选行为不允许在里面做耗时计算粒子滤波这类重活放在update里。execute只负责下发指令不负责判断该不该做这个边界一旦破坏行为层和技能层就会互相污染后期改一个步态会牵动半个决策树。这里有个隐性的时序约定本周期算出的指令服务器在下一个周期才生效。也就是说你的球员永远在“慢一拍”地响应世界做预测和提前量是必需的不是优化项是正确性的一部分。4.2 世界模型把极坐标视觉拼成球场坐标视觉输入不是笛卡尔坐标而是以头部为中心的极坐标加斜视角还带噪声而且一帧只给你视野锥内的东西。世界模型要干的事就是把这些碎片的观测结合自己的本体感知关节角度、陀螺仪和定位结果拼成一份全局视图。定位这块当年的主流做法是粒子滤波撒一批粒子每个粒子代表一个可能的位姿用观测到的地标球门柱、场地线交点去打分重采样。简化版用两根球门柱做三角解算够用但一旦被遮挡就飘。核心逻辑长这样// WorldModel::update本帧观测融合 void WorldModel::update(const SensorInput in) { // 本体感知始终可信先更新自身关节和朝向 mSelf.updateJoints(in.jointAngles); mSelf.updateGyro(in.gyro); // 视觉对象逐个转成球场坐标beamed 表示服务器直接给的精确值 for (const auto obj : in.visionObjects) { Vec3f pos mSelf.toWorldFrame(obj.polar, obj.azimuth); switch (obj.type) { case OBJ_BALL: // 球用卡尔曼滤波平滑速度比位置更容易被噪声带偏 mBall.update(pos, obj.beamed); break; case OBJ_FLAG: // 地标喂给粒子滤波权重在这里更新 mLocalization.observe(obj.type, pos); break; case OBJ_PLAYER: mPlayers.track(obj.unum, pos, obj.team); break; } } // 每 N 帧重采样一次太频繁会抖动太稀疏会跟丢 if (mFrame % 5 0) mLocalization.resample(); }toWorldFrame里的polar是距离azimuth是水平方位角垂直角度用来算高度三者加上自身位姿就得到世界坐标。beamed是个开关性质的字段服务器在某些情况下比如球进了自家禁区附近会给精确值这时候直接采信不要再过滤波器否则反而引入延迟。粒子滤波的重采样周期 5 帧是个经验值改小了定位抖改大了跟丢人不同球员类型守门员和前锋的运动特性差别很大可以分开配。4.3 技能层走路、转身、踢球的参数化实现技能层的接口很统一都是execute返回是否完成。走路是最基础也最难调的一块仿真里的双足行走本质上是关节角度序列的周期函数参数全靠手工调。以下是转向加前进的组合逻辑实际代码里还有侧移和抗扰// Walk::execute走向世界坐标下的目标点 bool Walk::execute(AgentController* agent, const Vec3f target, double speed) { // 1. 世界坐标转机器人自身坐标系只关心平面 Vec3f local mWorldModel-toRobotFrame(target); double dist local.length(); // 2. 球在侧后方时先转身再走硬走会绕大圈实测差半秒以上 double theta atan2(local.y(), local.x()); if (fabs(theta) DEG2RAD(30.0)) { return mTurn.execute(agent, theta); } // 3. 距离近就降速避免冲过头被球绊倒是的会绊倒 double v speed * clamp(dist / 1.5, 0.3, 1.0); // 4. 按步态表下发关节速度mGait 是离线调好的周期参数 for (int j 0; j mJointNum; j) { double phase mGaitPhase[j]; agent-setJointSpeed(j, mGait[j] * v * sin(phase)); } mGaitPhase mGaitStep; return dist 0.3; // 到点即视为完成 }DEG2RAD(30.0)是转身阈值超过就先转这个值是调出来的设小了走 Z 字设大了绕远路。clamp(dist / 1.5, 0.3, 1.0)是速度缩放1.5 米以内的减速区间下限 0.3 保证再近也在动不然会停在球前面“思考人生”。mGait每个关节一个系数mGaitStep决定步频这两个数组是整个项目里最需要耐心的地方改一个数整个步态就废了。踢球技能类似但它多一个“触球窗口”球必须在脚的可触及范围内且相对速度方向合适才真正发力否则就是空踢。这个窗口判定写错场上表现就是球员对着球疯狂抬腿但球纹丝不动。4.4 通信与协作say 消息怎么塞进有限字节里11 个人各看各的视角不通信就是 11 个近视眼各踢各的。仿真里的 say 是广播同队都能收到但有长度上限当年是 20 个字符左右卡得很死所以消息必须编码压缩不能发自然语言。// 广播球的位置和速度B 是类型前缀后面四个字段各保留两位小数 // 注意总长度必须控制在协议上限内超了会被截断甚至丢弃 char buf[32]; int n snprintf(buf, sizeof(buf), B%.1f,%.1f,%.1f,%.1f, ball.x(), ball.y(), ball.vx(), ball.vy()); if (n 0 n (int)sizeof(buf)) { mController-say(buf); } // 接收端按前缀分发解析失败直接丢弃不要 try/catch 到主循环 void Communication::onSay(const std::string msg) { if (msg.empty()) return; switch (msg[0]) { case B: mWorldModel-fuseBallFromTeammate(msg); break; case S: mWorldModel-fuseSelfFromTeammate(msg); break; default: break; // 未知前缀忽略保持向前兼容 } }snprintf的返回值一定要判返回负数说明编码失败返回大于等于缓冲区说明被截断两种情况都不能发。前缀字符的选择有讲究用一个字母区分消息类型比在固定位置放类型字段更省字节也更容易做向前兼容——以后加新消息类型老代码遇到不认识的前缀直接忽略不会崩。队友信息融合要谨慎别人报的球位置是他自己视角算出来的带有他的定位误差简单平均会把自己的精度也拉低。常见的做法是给自己的观测更高权重队友消息只在视野盲区时作为补充这条在防守回追时差别非常明显。5. 避坑与排查五类翻车场景和它们的解这套代码的报错信息普遍不友好连不上就是连不上不告诉你为什么。下面这五条是我在复现和改代码过程中反复遇到的每条都按现象、原因、解决的顺序写清楚照着排查能省不少时间。5.1 编译与依赖类问题第一条CMake 报找不到 oxygen / kerosin。现象是cmake ..直接失败提示Could NOT find OXYGEN (missing: OXYGEN_LIBRARY OXYGEN_INCLUDE_DIR)。原因基本是两个仿真服务器根本没装开发包或者装了但装在非标准前缀CMake 的默认搜索路径里没有。解决顺序是先ls /usr/local/lib | grep oxygen确认库存在再用-DCMAKE_PREFIX_PATH/usr/local显式指定。如果库确实不在那就先回去把仿真服务器编译安装一遍注意安装时别跳过make install只编译不安装等于没有开发包。第二条编译过了运行时报 so 找不到。现象是./bin/agentspark提示error while loading shared libraries: liboxygen.so。原因是编译期靠CMAKE_PREFIX_PATH找到了库运行期动态链接器不知道去哪儿找。解决要么把路径写进/etc/ld.so.conf.d/再ldconfig要么临时export LD_LIBRARY_PATH/usr/local/lib:$LD_LIBRARY_PATH。前者一劳永逸后者适合在容器里临时跑。排查时ldd ./bin/agentspark | grep not found一眼就能看出缺哪个。5.2 连接与对抗类问题第三条agent 一连上就被断开。现象是日志里出现连接成功后立刻 disconnect服务器那边显示 illegal connection。原因通常是队名或球衣号冲突同队两个 11 号后连的那个必被踢两队用了同一个队名服务器认为是同一支队在超员。解决是先用ps aux | grep agentspark看有没有残留进程再检查start_team.sh里传给--unum的循环变量是不是从 1 开始。用pkill -f teamname你的队名清干净再起。第四条球员原地转圈或者对着球疯狂抬腿但球不动。现象是监视器里看得很清楚球员围绕某个点不停旋转或者距离球只有半米却踢不到。原因分别是视觉解析时没有正确处理球不在视野锥内的情况定位飘了之后目标点算错走路技能就会不停修正朝向形成转圈踢球技能的触球窗口用世界坐标判定而没用自身坐标系或者球的高度算错。解决办法是先关掉决策层的复杂逻辑只留“lookAt 球然后走过去踢”这条最小链路能踢到再加回角色和协作。定位问题就打开--debug把粒子云打出来看粒子全糊成一团就是观测权重写反了。第五条比赛跑着跑着整体卡顿周期越拖越长。现象是刚开始流畅跑一两分钟后所有球员动作变慢日志写盘时间越来越长。原因是调试日志同步写文件每个周期都 flush磁盘 IO 拖垮了主循环。解决是把日志改成异步写或者只在特定球衣号上开日志比赛模式下mDebug直接关掉。另外检查一下有没有在think里做了粒子滤波这类重计算那个必须放在update里。注意调试期看到一个球员行为异常先看它那份独立日志不要一起看 11 份。日志里每帧打印的世界模型状态比监视器画面能说明的问题多得多。6. 二次开发换阵型、加技能、改决策层的稳妥路径改动从代价最小的地方开始。第一层是纯配置阵型文件和球员类型表都在conf/下换打法不用重编译。阵型文件定义每个球衣号在不同球状态下的目标位置格式大致是“名字 球衣号 坐标序列”改坐标就能把 4-3-3 变成 4-4-2。这一层的坑在于坐标是球场绝对坐标且服务器会按球员类型限制活动范围守门员的位置填到对方半场场上表现就是他站在原地不动。第二层是加技能。新技能继承技能基类实现execute即可但要遵守两条约定只下发指令不做决策以及返回布尔值表示是否完成。技能内部不要读全局状态所有需要的数据从世界模型传入这样单元测试能单独跑不用起服务器。我一般会先在无对抗场景里验证技能用一个固定的球位置反复调用看关节角度曲线是否收敛收敛了再放进对抗。第三层才是动决策层。原始的 if-else 风格行为选择在角色少的时候够用一旦要加“回防优先级”“协防补位”就会变成一大坨嵌套。换成行为树或者状态机都可以关键是把“角色分配”和“行为选择”拆开角色由阵型和球位置决定行为由角色和当前局面决定两层之间的接口只有几个字段。改造目标动哪里重编译验证方式换打法conf/formations/*否看站位是否符合预期调步态skills/Walk.cpp参数表是单技能无对抗回放加技能新增skills/xxx.cpp是固定球位置反复调用换决策agent/Behavior.cpp是整场对抗 日志统计验证这块我有一个固定流程改完先跑单队无对手 3 分钟确认没人摔倒、没人卡住再跑两队对抗 10 场用脚本统计进球数和控球时间。日志里把每帧的球位置和角色记下来一个简单的 Python 脚本就能算出控球率比肉眼看监视器靠谱得多。批量跑的时候把监视器关掉省下来的渲染开销能让仿真跑快不少。血泪经验是每次只改一个变量。步态系数和决策阈值一起改出了问题根本不知道该回滚哪个最后只能整个目录 git checkout。从那以后我每次动技能参数前都强制走一遍“单技能验证—无对抗整场—对抗十场”这条链路慢是慢一点但省下的排查时间远不止这些。这套 2012 年的冠军代码放到今天架构上依然站得住值得拿来当多智能体对抗的练手底子。希望帮到你。本文还有配套的精品资源点击获取
