HaloDebug · 模块总览与使用
了解通用调试工具的操作、远程连接与窗口扩展，再由各模块的排查说明定位具体问题。
本页内容7 节
子模块与功能
进入具体功能，查阅使用步骤、运行机制与扩展方法。
远程调试
- netImgui 远程面板
在独立桌面程序查看调试窗口，区分远程 UI、游戏视口绘制与玩法网络权限。
扩展开发
- 窗口扩展与属性绘制
复用窗口生命周期、反射 Inspector 和场景绘制，避免为每个调试页重做基础设施。
模块职责与功能入口
HaloDebug 提供调试窗口与菜单、ImGui 输入、属性检查和场景绘制基础；Starry 在此之上注册项目工具。这里说明工具怎样操作、连接与扩展；具体模块的状态含义、异常原因和排查步骤在所属模块中说明。
文档中的功能分区面向实际用途，插件的 C++ 模块分工见下文；一个功能可能使用多个底层模块，例如远程显示通过 ImGui 传输窗口，场景绘制仍在游戏进程完成。
从 F1 开始
在 PIE 或非 Shipping 游戏中按 F1，或执行 HaloDebug.ToggleInput，切换调试输入。打开菜单中的所需窗口，完成检查后再切回正常游戏操作。
Starry 由 UStarryDebugSubsystem 注册项目菜单。HaloDebug 提供窗口、输入、绘制与配置能力，项目决定打开哪些工具以及工具操作哪些领域。
常用工具在哪里
| 想做什么 | 当前菜单 |
|---|---|
| 选择 Actor、观察当前选择 | Engine → Selection |
| 查看 Actor 属性 | Engine → Actor → Inspector |
| 调整位置、旋转与缩放 | Engine → Actor → Transform |
| 查看骨架 | Engine → Actor → Skeleton |
| 执行 Cheat | Engine → Actor → Cheats |
| 碰撞查询与碰撞显示 | Engine → Scene → Collision Tester / Collision Viewer |
| 看日志、通知、曲线与指标 | Engine → Diagnostics |
| 时间倍率 | Engine → Time Scale |
| 网络模拟与画质 | Engine → Runtime → Net Emulation / Scalability |
| ImGui、Slate、快捷命令与远程连接 | Engine → Debug Tools |
| AI 决策与后端 | AI |
| 手柄与 Action 注入 | Input → Gamepad / Actions |
这些路径对应当前注册代码。查不到旧名称时，先核对项目菜单，不要据此新增同功能窗口。
操作对象与当前世界
选择决定 Inspector、Transform 等工具的目标。使用选取模式时在游戏视口左键选择、右键取消。拖动 Gizmo 需要游戏视口里的调试输入已经打开。
Cheats 默认作用于选中的 Actor；按住 Ctrl 点击时改用本地受控 Pawn。控制台形式是 HaloDebug.Cheat <CheatName> [-Controlled]。当前没有 Shift／Alt 的阵营批量操作，也没有调试 Possess 菜单。
面板操作发生在当前连接的游戏进程与世界。它不会自动把客户端的修改变成服务器 RPC；玩法权限与同步仍由对应领域处理。多人 PIE 中先确认正在操作哪个世界。
查看图表源码
flowchart LR
User(调试输入) --> UI(ImGui 窗口)
UI --> Domain(当前世界的领域接口)
Domain --> State(运行状态)
State --> UI
UI --> Draw(本进程场景绘制)
Draw --> Viewport(游戏视口)
UI --> Remote(netImgui 桌面显示)插件内部如何分工
| 模块 | 职责 |
|---|---|
HaloDebug | WorldSubsystem、窗口、菜单、布局与配置 |
HaloDebugCommon | 公共接口与构建宏 |
HaloDebugImgui | ImGui、输入、Slate 与 netImgui 接入 |
HaloDebugPaint | 本进程场景绘制、Gizmo、曲线与指标 |
HaloDebugEngine | 通用 Engine 工具与反射属性 Inspector |
HaloDebugInput | Gamepad 与 Actions 调试 |
ENABLE_HALODEBUG = !UE_BUILD_SHIPPING。面板和工具代码按构建条件使用；部分运行时反射类型仍需在 Shipping 中存在以便资产加载，不能把这一宏解释为整个插件完全不存在。
看不到面板时
先确认当前不是 Shipping、项目已启用插件且 Subsystem 注册了窗口，再检查 F1 调试输入、窗口可见性和当前世界。中文缺字还应检查非 Shipping 字体文件部署：字体由标准文件读取，只有 Cook 到 Pak 并不足以替代相应 NonUFS 文件。
远程桌面显示见netImgui 远程面板，新窗口与绘制复用见窗口扩展与属性绘制。
定位具体系统的问题时，从所属模块的排查章节进入：Input 调试与排查包含 Gamepad／Actions 操作、模拟范围与输入诊断路线，AI 问题见 AstraAI 调试与排查。
实现入口：Plugins/Toolkit/HaloDebug 与 Source/StarryGame/Framework/Development/StarryDebugSubsystem。插件来源为 Cog，保留 MIT 许可；具体来源与许可记录随项目维护。