Twilight

简体中文 | English

Twilight 是 Lumina 的 Visual Studio Code 开发辅助插件。它连接正在运行的 Lumina Client，把比赛遥测、进程与场地控制、REC2 回放、录像、Lua 代码导航、诊断和代码生成器集中到同一个工作区中。

插件界面、命令、设置、生成器和诊断均支持英文与简体中文。Twilight 会自动跟随 VS Code 的显示语言，其他语言环境默认使用英文。

功能

实时比赛控制台

Twilight 在活动栏中提供紧凑的 Pit Wall 视图，也可以打开完整比赛控制台，获得更大的操作界面和回放事件列表。

• 实时显示比分、比赛阶段、裁判指令、剩余时间、红黄牌、犯规和 FPS
• 启停蓝方 Medusa、黄方 Medusa 和 grSim，并控制是否显示 grSim 窗口
• 切换仿真与真实机器人模式
• 连接或断开 Vision、重新扫描网络接口、选择 Vision 与 grSim 接口
• 分别配置蓝方和黄方的测试模式、Test Play 与对手战术包
• 在 VS Code 状态栏查看连接状态，并可手动重连或刷新

回放与录像

• 在 Lumina Client 中打开 .rec2、.log 和 .gz 回放文件
• 播放、暂停、前后跳转 60 帧、跳转到检测出的事件，并在 0.25x 至 16x 之间循环切换速度
• 查看加载状态、当前帧、总时长和回放事件时间线
• 直接从控制台开始或停止比赛录像

Lumina 代码智能

Twilight 会按照 Lumina 的约定建立 Lua 5.1、tolua++ 与 C++ 工作区索引。

• 为 Lua 函数和模块式调用提供标准的“转到定义”支持
• Twilight: 跳转到定义 默认绑定 F10，可在 VS Code 的“键盘快捷方式”中自行修改；它可沿 Lua 包装函数调用链追踪到 C... 绑定、LuaModule.cpp、Factory.cpp 和 Skill 实现
• 从 Lua 接收者跳转到 tolua++ .pkg 声明，以及对应的 C++ 声明或定义
• Lua、.pkg、C++ 或头文件变化时自动刷新索引
• 在“问题”面板报告 Lua 5.1 解析错误、TacticList.lua 注册但文件缺失以及重复注册

代码生成器

Twilight: 新建 Play：

• 在 ZBin/lua_scripts/play 下创建安全的 Play 骨架
• 支持 Test、Nor 和已有的 Ref 子目录
• 自动注册到 TacticList.lua 中对应的表

Twilight: 新建 Skill：

• 同时创建 C++ 头文件、源文件和 Lua 包装文件
• 可选择 CPlayerTask 或 CStatedTask 骨架
• 自动注册到 Factory.h、Factory.cpp、LuaModule.cpp 和 TacticList.lua
• 初始实现使用安全停止指令，避免未完成的 Skill 意外驱动机器人

生成器会把所有修改作为一次 VS Code 工作区事务应用。名称必须是 PascalCase 格式的 C++/Lua 标识符；已有文件不会被覆盖；如果找不到任何一个 Skill 注册锚点，生成器会在不修改文件的情况下停止。

环境要求

• VS Code 1.96 或更高版本
• 本地 Lumina 工作区，包含 Client/、Medusa/src/ 和 ZBin/lua_scripts/Zeus.lua
• 使用实时遥测和控制功能时，需要兼容的 Lumina Client
• 仅开发或打包 Twilight 时需要 Node.js 20 或更高版本及 npm

代码智能和生成器无需运行 Client。比赛、进程、网络、回放和录像功能需要连接 Client。

安装

构建并安装本地 VSIX：

cd Twilight
npm ci
npm run package

随后在 VS Code 中运行“扩展: 从 VSIX 安装...”，选择生成的 twilight-lumina-*.vsix 文件。

如需开发插件，请用 VS Code 打开 Twilight/，运行 npm ci，然后按 F5 启动扩展开发宿主。

快速开始

1. 在 VS Code 中打开 Lumina 仓库，或仓库根目录下的任意文件夹。
2. 在 Lumina 仓库中启动 ZBin/Client。
3. 打开活动栏中的 Twilight 图标。Twilight 会读取 ZBin/.twilight/client.json 并自动连接。
4. 使用紧凑的“比赛控制”视图，或从命令面板运行 Twilight: 打开控制台。
5. 打开 Lua 文件，使用 VS Code 的“转到定义”，或运行 Twilight: 跳转到定义 进行跨语言导航。

如果 Client 晚于 VS Code 启动，Twilight 会每两秒自动重试。也可以手动运行 Twilight: 连接 Client。

命令

Lua 编辑器的右键菜单中也提供 Twilight: 跳转到定义。

设置

连接与安全

Lumina Client 只在 127.0.0.1 的临时端口上监听。启动时，它会写入一个仅文件所有者可读的端点文件，其中包含端口和每次启动随机生成的认证令牌。Twilight 必须先使用该令牌完成认证才能发送命令，并会在 Client 会话变化后重新连接。

运行时设置以 Client 为准。每次连接时，Twilight 都会采用 Client 返回的完整状态，不会把插件缓存的设置推送回 Client。用户在 Twilight 中点击切换仿真/实车时直接生效，不再额外审批。

自动化请求的危险实车操作仍需显式确认。Twilight 左侧栏底部确认卡和 Client 内嵌 InfoBar 可以同时显示同一个请求；任一端先完成审批后，另一端会自动收起。确认前请务必核对队伍颜色和场地方向。

JSON Lines 传输格式和支持的方法见 Client protocol v1。

常见问题

• Twilight 未激活： 请打开 Lumina 仓库或其下级目录。Twilight 通过 Client/CMakeLists.txt、Medusa/src 和 ZBin/lua_scripts/Zeus.lua 识别仓库根目录。
• Twilight 一直离线： 启动 ZBin/Client，检查 ZBin/.twilight/client.json 是否存在；如果端点文件位于其他位置，请设置 twilight.endpointPath。
• 无法修改网络接口： 请先断开 Vision。Vision 连接期间会禁用接口扫描和 Vision 接口选择。
• 测试设置在 Medusa 中没有立即变化： 队伍测试模式、Test Play 和战术包修改可能需要重启 Medusa；需要重启时 Twilight 会显示通知。
• 代码跳转结果过期： 运行 Twilight: 重建 Language Server 索引。Lua 解析失败和注册问题会显示在 VS Code 的“问题”面板中。
• 生成器拒绝执行： 检查是否已经存在同名文件或注册，并确保 Lumina 中预期的注册锚点仍然存在。

开发

cd Twilight
npm ci
npm run check
npm test

常用脚本：

• npm run build — 打包扩展与 Vue Webview
• npm run watch — 开发时持续重建扩展宿主代码
• npm run check — 对扩展与 Webview 代码执行类型检查
• npm test — 构建并运行 Node 测试套件
• npm run package — 校验、构建并生成 VSIX

项目结构

• src/extension.ts — 激活、命令、状态栏、本地化和真实机器人模式授权
• src/client.ts — 带认证的 JSON Lines 传输与重连逻辑
• src/webview/PitWall.vue — 紧凑视图与完整控制台共用的界面
• src/sidebar.ts 和 src/dashboard.ts — VS Code Webview 集成
• src/luaIndex.ts、src/luaCallGraph.ts、src/toluaIndex.ts 和 src/cppCallGraph.ts — 跨语言索引、跳转与诊断
• src/generators.ts — 事务式 Play 与 Skill 脚手架
• docs/protocol-v1.md — Client 协议约定

许可证

MIT