AutoRef 自动裁判
约 3107 字
前面的内部裁判盒和 GC 教程中,我们主要通过按钮告诉机器人“现在暂停”“准备开球”。这一篇要加入自动检测:当球出界或场上发生某些犯规时,让软件检测事件并交给 GC 处理。
AutoReferee(简称 AutoRef)就是负责检测这些事件的自动裁判软件。 Lumina 使用基于 TIGERs AutoReferee 修改的版本。Client 为它提供球、机器人和比赛状态;它检测事件后提交给 GC,GC 再向队伍发布相应裁判信息。还不清楚各部分职责时,先阅读 裁判系统如何协作。
本篇先带你连接 AutoRef,再观察检测结果与 GC 状态。第一次操作建议使用本机仿真,先弄清每一步看什么,再尝试跨机连接。
打开 Settings Panel → Referee → AutoReferee。GC Control Center 的 运行诊断 中也有同一面板;经常使用时可以点击右上角 添加到 Tab 栏。

AutoReferee 页面入口
设置面板中的独立页面,包含启动配置、CI 连接和进程日志
选择执裁模式
| 模式 | 检测事件 | 向 GC 提交事件 | 使用场景 |
|---|---|---|---|
| Off | 否 | 否 | 验证进程与 CI 数据通道 |
| Passive | 是 | 否 | 先观察检测结果,核对场地与规则配置 |
| Active | 是 | 是 | 联调自动事件到 GC 的完整处理流程 |
Off 是停用检测,不是停止进程。 进程可以在 Off 模式下保持运行并连接 CI。需要结束进程时点击 停止进程。
模式、发行包目录与 GUI 选项在进程运行时不可修改。先停止进程,修改后重新启动。当前 Client 面板尚未提供运行中切换执裁模式、逐项检测器管理和独立检测事件列表;需要观察 AutoRef 检测日志时,可启动时开启 GUI,查看它自身的 Game Log。三个模式的基本语义见 AutoReferee 上游说明。
第一次使用:先连接,再观察事件
1. 准备 GC、视觉和测试场景
先按 GC 实例配置与连接 启动本机 GC,等待 CI、API 均已连接且就绪,再完成比赛准备。
接着启动仿真器并连接视觉。你应该能在 Client 场地上看到位置合理的球和机器人,视觉帧持续更新。保持普通 SSL 场地坐标,即参数 saoAction = 0,让 AutoRef 与 GC 看到同一套场地坐标。若画面本身就不正确,先处理视觉问题,再继续本教程。
2. 选择 Passive,启动 AutoRef
在 AutoReferee 页选择 Passive。这样即使检测到了事件,也不会把它提交给 GC,便于先观察检测情况。第一次需要查看检测结果时,将 显示 GUI 设为开启;这里的 GUI 就是 AutoRef 自己的图形界面。
发行包目录保持默认 ZBin/autoReferee,本机 CI 地址保持 127.0.0.1:10013,点击 启动 AutoReferee。这里 127.0.0.1 代表当前电脑;Client 会在进程启动后自动尝试连接它。
若提示缺少发行包,先按本页 首次准备发行包 安装。发行包是已经构建好的可运行程序,包含启动脚本、依赖库和配置;仅有 AutoRef 源码并不足以从这里启动。
3. 确认视觉确实送到了 AutoRef
先看启动区域是否变为 运行中,再看 CI 区域是否显示 已连接。前者表示软件进程启动,后者表示 Client 与它的数据通道接通。
保持视觉运行,观察 视觉帧 和 回传 Tracker 是否持续增加。视觉帧表示 Client 正在向 AutoRef 送数据,回传计数表示 AutoRef 已经产生回包。它们变化后,才能继续观察“AutoRef 对这些数据做出了什么判断”。

连接后观察数据是否持续变化
先确认运行中和已连接,再观察视觉帧与回传 Tracker 计数
截图中虽然有回包,进程日志仍包含连接 GC 的异常堆栈。因为 Client 到 AutoRef 的数据连接,与 AutoRef 到 GC 的事件连接是两条通路,后续还要单独检查事件提交。
4. 在 Passive 模式下观察一次检测
在 AutoRef 自身界面找到 Game Log,也就是它的比赛事件日志。在启用边线出界检测的仿真场景中,让球从场内运动到边线外,观察是否出现相应检测事件。应让场景处于该事件适用的比赛状态;仅把球放在场外,或在 Halt 状态中拖动球,不一定能构成有效的检测测试。
这一步需要分别看两个地方:AutoRef 的 Game Log 用来观察它检测了什么,GC 的当前指令与比赛历史用来观察比赛有没有发生变更。Passive 不提交自动事件,因此不能期待 GC 仅因 AutoRef 检测到了出界就自动判罚。期间若操作人员手动改变 GC,GC 状态仍会变化。
若没有检测记录,先确认当前模式、视觉、比赛状态及对应检测器。某些国内赛制采用不同边界规则;选用出界作为例子前,应确认当前规则确实启用了这项检测。事件检测方式见 AutoReferee 上游使用说明。
5. 切换 Active,观察事件怎样影响 GC
点击 停止进程,改为 Active,再重新启动。当前面板的模式是在启动时设置的,因此需要先停止后修改。
打开 GC 的 规则与数据源,确认有对应的 AutoRef 来源,并检查连接和事件处理策略。再重复同一个测试场景,依次观察:
- AutoRef 是否检测到事件。
- GC 的 事件与提议 是否收到相应事件或待确认提议;如需人工接受,按当前流程处理。
- GC 的 比赛历史 和当前指令是否发生了相应变更。
- Client 顶栏和 Medusa 是否显示、响应了新的裁判指令。
初次观察可先关闭 GC 自动继续,便于逐步查看状态。确认流程后,再按测试目标开启自动继续,观察放球与恢复比赛。Active 表示 AutoRef 会提交事件,实际如何判罚仍由 GC 当前策略与比赛状态决定。
6. 结束测试
先通过 GC 发送 Halt,结束本轮机器人动作,再停止 AutoRef,最后按需停止托管 GC。AutoRef 页会保留部分旧计数和日志,需要留存时先导出。
做完这一轮,你验证的是从检测到 GC 处理再到策略响应的过程。AutoRef 单独连接也可以接收视觉,但要验证自动事件如何影响比赛,就需要这几个部分一起运行。
控件说明

AutoReferee 控件标注
按编号设置模式、启动进程并检查数据流
| 编号 | 控件 | 操作说明 |
|---|---|---|
| 1 | 添加到 Tab 栏 | 将本页加入主界面 Tab 栏,方便切换 |
| 2 | Off / Passive / Active | 设置下次启动时的执裁模式 |
| 3 | 发行包目录 | 默认使用 ZBin/autoReferee;自备发行包时选择完整目录 |
| 4 | 显示 GUI | 决定启动时是否打开 AutoRef 自身界面;关闭时仍可检测和提交事件 |
| 5 | 启动 AutoReferee / 停止进程 | 启停 Client 托管的 AutoRef 进程,右上角显示进程状态 |
| 6 | CI 主机与端口 | Client 连接 AutoRef 的数据入口,默认 127.0.0.1:10013 |
| 7 | 数据计数 | 分别显示发送包、发送视觉帧和收到的 Tracker 数 |
| 8 | 进程日志 | 查看托管进程最近的标准输出和错误输出 |
| 9 | 导出 TXT | 保存当前面板保留的进程日志 |
首次准备发行包
普通 Client 构建不要求安装 AutoRef。若默认目录缺失,可以在 Lumina 源码目录执行安装目标,获取项目固定版本的完整发行包:
cmake --build build --target install_autorefereeWindows 首次配置还可以使用项目提供的安装脚本,准备配套的 Java 25 和 AutoRef 发行包:
powershell -ExecutionPolicy Bypass -File scripts/setup-autoref-windows.ps1脚本将 Java 放在 ZBin/java,AutoRef 放在 ZBin/autoReferee。新版 Client 在 Windows 托管启动时优先使用这份 Java;从终端手动启动则需自行设置正确的 Java 环境。已有 Java 21 不代表能运行当前固定发行包。
自备发行包应包含 bin、lib、config,并具备 config/moduli/autoreferee-ci.xml。不要只选择源码目录或单个 JAR;普通上游发行包也需确认支持本教程的 CI 配置。下载受限时可使用本地压缩包,具体安装参数见 Lumina 项目的构建与验证说明(需仓库访问权限)。
连接外部 AutoRef
先在目标电脑启动具备 CI 支持的 AutoRef,在本页填写该电脑的地址与 CI 端口,点击 连接。外部进程的模式、GUI 和发行包由它的启动者配置;本页的启动配置用于 Client 托管启动,不会远程修改现有进程。
使用其他电脑时,还要在 AutoRef 配置中确认 GC 的实际地址与事件端口。这里只修改 CI 主机,并不会同时改写 AutoRef 到 GC 的连接。断开 CI 不等于停止外部 AutoRef,外部进程需在其运行电脑上结束。
判断数据是否正常
| 指标 | 能说明什么 | 还需要核对什么 |
|---|---|---|
| 运行中 | 托管进程已经启动 | Java、配置错误及 GC 注册仍需看日志 |
| CI 已连接 | Client 到 AutoRef 的 TCP 已连接 | 不代表 AutoRef 已连接 GC |
| 发送包增加 | Client 正发送 CI 输入,可能含裁判消息、几何或视觉 | 不能只凭总包数判断视觉正常 |
| 视觉帧增加 | Client 正向 AutoRef 发送 Tracker 视觉 | 核对坐标、场地和数据新鲜度 |
| 回传 Tracker 增加 | AutoRef 正返回跟踪包 | 不代表检测到事件或 GC 已接受判罚 |
计数是累计值,断开后可能仍保留旧数字,应看一段时间内是否继续变化。AutoRef 回传 Tracker 仅用于统计,Client 不会将它作为 GC 的视觉输入。
日志与常见问题

停止后的页面
已停止、未连接时仍可能保留之前的数据计数与日志
进程日志保留最近一段输出;重新启动会清空旧输出,需要留存时先 导出 TXT。该日志与 AutoRef Game Log、GC 比赛历史各有用途:分别用于进程排错、检查检测事件和确认实际比赛状态变更。
| 现象 | 检查顺序 |
|---|---|
| 提示发行包缺失 | 检查目录中的 bin、lib 和 CI 配置;运行安装目标或重新选择完整发行包 |
| Java 版本或类加载报错 | 检查当前发行包配套 Java;Windows 核对 ZBin/java 是否完整及 Client 是否为支持托管 Java 的版本 |
| 运行中但 CI 未连接 | 确认进程已完成启动、CI 模式和端口正确、端口未被占用;查看进程日志与连接错误 |
| CI 已连接但视觉帧不增加 | 检查 Client 视觉连接、融合输出和 saoAction = 0 |
| 视觉帧增加但没有回传 | 检查 AutoRef 日志、CI 协议兼容性及输入几何;不能用旧累计值判断当前状态 |
| 日志持续提示无法连接 GC | 检查 GC 是否运行、AutoRef 的 GC 地址、GC 10007 监听及跨机网络连通性 |
| 有检测但 GC 没有判罚 | 确认 Active 模式、AutoRef 注册、来源策略和事件策略;检查是否只形成待接受提议 |
| 切换模式或 GUI 没生效 | 停止托管进程后修改,再重新启动 |
当前接入已验证进程启停、CI 数据交换及 AutoRef 注册;这些检查不能替代具体进球、出界、碰撞等事件的场景验收。调规则或更换发行包后,应重新验证目标事件。
贡献者
更新日志
46b5b-裁判系统教程更新于