Debug Mode zh CN

调试模式

GuideNH 包含了一个综合性的调试模式系统，供开发者和内容创作者实时检查和调试指南页面。

激活方式

调试模式可以通过两种方式激活：

1. 配置文件：在模组配置中启用"GUI 调试覆盖层"（ModConfig.Debug.guiDebugMode）
2. 快捷键：在任何 GuideNH 界面按下 C + CTRL + SHIFT + ALT 切换调试模式开关

功能特性

左下角信息面板

当调试模式激活时，左下角会显示综合信息：

• 鼠标位置：当前光标坐标
• FPS 计数器：每秒帧数性能指标
• 内存使用：JVM 堆内存使用情况（已用/最大 MB 和百分比）
• 悬停元素：光标下元素的详细信息：
  • 类名
  • 位置（X, Y 坐标）
  • 尺寸（宽度 × 高度）
  • 元素特定的额外信息（因元素类型而异）
• 父元素：父容器的信息（启用时）

中间底部控制面板

点击底部中心的"调试选项"面板可访问下拉菜单，包含以下选项：

打印文档树

将完整的文档层级结构以可视化树形结构输出到控制台。

悬停元素信息

切换悬停元素显示选项的子菜单：

• 显示任意（主开关）
• 显示位置
• 显示尺寸
• 显示主题
• 显示额外信息
• 显示轮廓

父元素信息

切换父元素显示选项的子菜单：

• 显示任意（主开关）
• 显示位置
• 显示尺寸
• 显示主题
• 显示轮廓

显示选项

常规显示开关：

• 显示 FPS
• 显示内存
• 显示鼠标位置

重新编译当前页面

强制重新编译当前显示的指南页面。

导出调试数据

将当前调试信息导出到控制台（对问题报告很有用）。

视觉反馈

动画虚线边框

当启用轮廓显示并悬停在元素上时，GuideNH 会绘制动画白色虚线边框：

• 悬停元素（完全不透明）
• 父元素（30% 不透明度，启用时）

动画流畅流动，便于识别元素边界。

类名标签

一个小黑色标签框显示悬停元素的简化类名，位置在元素左上角附近。

光标点

绿色点标记精确的鼠标光标位置，用于精确坐标参考。

元素特定信息

调试模式为不同元素类型提供定制信息：

文档块

• 段落：文本预览
• 标题：级别和文本预览
• 物品显示：物品信息
• 交互槽位：槽位详情

图表和图示

• 条形图/柱状图/饼图：图表数据信息
• Mermaid 思维导图：节点数量

3D 场景

• 指南场景：元素数量、场景结构

交互元素

• 链接：目标地址
• 锚点：锚点名称
• 按钮：按钮状态

配置

所有调试选项可通过模组配置 GUI 或 guidenh.cfg 配置：

视觉设置

• debugTextColor：调试文本的 ARGB 颜色（默认：0xB4287BDC）
• debugOutlineColor：元素轮廓的 ARGB 颜色（0 表示镜像文本颜色）
• debugCursorColor：光标点的 ARGB 颜色（默认：0xCC00FF00）
• debugTextScale：调试文本的缩放因子（0.5-2.0，默认：0.8）
• debugOutlineThickness：轮廓边框厚度（0.5-5.0px，默认：1.0）

动画设置

• debugDashAnimationCycleMs：动画循环周期（500-10000ms，默认：2000）
• debugDashWidth：虚线宽度（0.5-5.0px，默认：1.0）
• debugDashOnLength：可见虚线段长度（1-20px，默认：4.0）
• debugDashOffLength：间隙段长度（1-20px，默认：4.0）

显示开关

每种信息类型的独立开关（悬停元素、父元素、FPS、内存、鼠标位置等）

性能

当调试模式禁用时（guiDebugMode = false），系统优化为零性能开销：

• 无帧计时计算
• 无内存监控
• 无元素检测
• 无渲染

所有调试相关的代码路径使用早期退出检查，确保对正常游戏的影响最小。

使用场景

内容创作

• 验证元素定位和尺寸
• 调试布局问题
• 检查场景元素结构
• 测试交互元素行为

开发

• 追踪文档树层级
• 检查编译后的页面结构
• 监控页面渲染期间的性能
• 调试自定义元素实现

问题报告

• 为问题报告导出文档树
• 捕获元素信息用于重现
• 在问题发生时监控性能指标

注意事项

• 调试模式在指南页面导航时持久保留
• 设置保存到配置文件
• 树输出记录到 Minecraft 控制台/日志文件
• 调试覆盖层渲染在所有 GUI 元素之上

可扩展性

自定义元素信息提取器

调试系统使用基于注册表的架构进行元素信息提取。开发者可以为mod特定的元素类型注册自定义提取器：

// 实现 DebugInfoExtractor 接口
public class MyCustomExtractor implements DebugInfoExtractor {
    @Override
    public boolean canHandle(LytNode node) {
        return node instanceof MyCustomElement;
    }
    
    @Override
    public void extract(LytNode node, HoveredElementInfo info) {
        MyCustomElement element = (MyCustomElement) node;
        info.addExtraInfo("自定义属性: " + element.getProperty());
    }
    
    @Override
    public int getPriority() {
        return 50; // 优先级越高，检查越早
    }
}

// 在mod初始化时注册
DebugInfoExtractorRegistry.register(new MyCustomExtractor());

内置提取器会自动注册，并处理：

• 文档结构（文档、段落、标题）
• 交互元素（槽位、按钮、链接）
• 图表（条形图、柱状图、饼图、折线图、散点图）
• 图示（Mermaid 思维导图）
• 媒体（图像、代码块、Latex）
• 容器（列表、表格、盒子）
• 3D 场景（指南场景）
• 通用块（回退）