在线调试（GUIConsole）

GUIConsole 是面向 KBEngine Nex 的独立桌面管理与诊断工具。它不再随引擎源码内置发布，拥有独立的版本与发布周期，并支持 Windows、Linux 和 macOS。

GUIConsole 通过管理协议直接连接 KBEngine Nex，可用于查看组件状态、执行 Python 命令、检索日志、读取 Watcher、采集 Profiler 数据，以及观察 Space、NavMesh 和 Entity。当前版本使用 C#、.NET 10 和 Avalonia UI 开发，支持 KBEngine Nex 3.x 版本线。本文界面和操作截图基于 GUIConsole v1.1。

适用场景

GUIConsole 适合开发和受控运维环境中的在线诊断。使用控制台、组件操作等能力前，应确认目标进程和运行环境，避免影响在线业务。

下载与启动

在下载页面切换到 GUIConsole，选择与操作系统及 CPU 架构匹配的软件包。发布包已经包含运行所需文件，解压后即可启动：

• Windows：运行 KBEngineNex.GuiConsole.exe。
• Linux AppImage：添加执行权限后运行，例如 chmod +x KBEngineNex.GuiConsole-*.AppImage。
• Linux 压缩包：解压后运行目录中的 GUIConsole 可执行文件。
• macOS：解压后启动应用；若系统阻止运行，请按下载页面中的发布说明移除隔离属性。

GUIConsole 与引擎独立发布，升级其中一方时应先确认协议兼容性。Space Viewer 依赖 KBEngine Nex 3.x 中匹配的 Space 协议扩展。

连接引擎

启动 KBEngine Nex 服务端后，打开 GUIConsole 的连接设置并填写：

配置项	说明
配置名称	用于区分本地、测试服、生产服等连接，可自行命名。
环境	标记当前配置属于开发、测试还是生产环境。
Machine 地址	运行 machine 组件的 IPv4 地址或可解析的主机名。本机开发通常使用 127.0.0.1。
Machine 端口	machine 接收 UDP 发现请求的端口，默认值为 20086。
UID	用于筛选指定 UID 的服务端组件；-1 表示发现全部 UID。
管理 Token	必须与引擎配置中的 management.adminToken 完全一致。

项目应在自己的服务端配置中覆盖管理 Token，例如：

<root>
    <management>
        <adminToken>replace-with-a-long-random-token</adminToken>
    </management>
</root>

配置方式详见引擎配置。连接成功后，GUIConsole 会通过 Machine 发现同一环境中的服务端组件。跨主机连接时，可通过远程端点和地址映射处理内外网地址不一致的情况。

管理权限

管理 Token 可授权执行 Python 命令和组件控制等高权限操作。生产环境必须使用足够长的随机 Token，限制 Machine 与组件管理端口的访问来源，并将管理网络与公网入口隔离。不要把 Token 写入公开仓库、截图或日志。

界面总览

左侧是 Machine 与服务端组件列表，可查看组件类型、进程 ID、CPU、内存和运行状态。选择组件后，右侧会显示对应的操作与诊断功能：

• 操作中心：查看操作记录，并对支持的组件执行生命周期管理。
• 控制台：在目标组件进程内执行 Python 语句。
• 日志：订阅实时日志或按条件查询历史日志。
• Watcher：浏览和监视引擎及脚本公开的运行时指标。
• Profiler：采集 Python、C++、事件与网络性能数据。
• Space Viewer：观察 CellApp 上的 Space、NavMesh 和 Entity 分布。
• 服务布局：保存和管理多组件部署布局。

组件列表会随 Machine 上报自动更新。开始操作前应先核对当前选中的组件，因为不同组件支持的命令、Watcher 和 Profiler 类型并不相同。

Python 在线调试

选择运行脚本逻辑的组件，例如 BaseApp 或 CellApp，然后打开 控制台。命令会直接在所选服务端进程中执行，返回值和异常会显示在控制台输出区。

查看当前进程中的 Entity

KBEngine.entities.items()

for entityID, entity in KBEngine.entities.items():
    print(f"entityID={entityID}, entity={entity}")

查看 Entity 坐标

KBEngine.entities[entityID].position

修改 Entity 朝向

import math
KBEngine.entities[entityID].direction.z = math.pi

调用 Entity 方法

KBEngine.entities[entityID].funcXXX()

在 CellApp 中创建 Entity

entity = KBEngine.createEntity(
    "Monster",
    spaceID,
    (10.0, 0.0, 10.0),
    (0.0, 0.0, 0.0),
    {}
)

调用 Entity 的远程方法

KBEngine.entities[entityID].base.func()
KBEngine.entities[entityID].client.func()

在线修改风险

Python 控制台不是隔离的沙箱。修改属性、创建 Entity、调用方法或执行耗时逻辑都会直接影响目标进程；错误命令还可能阻塞 Tick、产生大量日志或破坏业务数据。生产环境优先执行只读查询，并在执行修改类命令前确认目标组件、Entity ID 和回滚方案。

实时与历史日志

打开 日志 页面并选择日志来源后，可以启动实时订阅，也可以按组件、级别、时间和关键字查询历史日志。实时日志适合跟踪当前调用链，历史查询适合复盘已经发生的问题。

使用日志功能前需要启动 Logger 组件。高流量环境中应尽量缩小组件和日志级别范围，避免宽泛订阅带来额外网络流量、GUI 内存占用和日志处理压力。日志文件及 Logger 的工作方式详见运行时日志。

Watcher 运行时监控

Watcher 用于读取引擎或脚本注册的运行时指标。选择目标组件，在 Watcher 页面输入路径并查询；可以展开树结构、搜索结果、收藏常用路径，也可以设置自动刷新间隔。

根路径可使用 root。自动刷新会持续向目标组件发送请求，刷新间隔应根据指标变化速度和服务压力设置，不建议为了界面实时感使用过短间隔。脚本层自定义指标可通过 KBEngine.addWatcher 注册，参见调试章节中的监视器说明。

Profiler 性能分析

选择目标组件后，在 Profiler 页面选择采样类型和持续时间，再开始采集：

类型	用途
Python Profiler	分析脚本函数调用及耗时。
PythonTick Profiler	按 Tick 持续采集 Python 执行耗时。
C++ Profiler	分析引擎内部执行路径及耗时。
Event Profiler	统计采样期间发生的事件。
Network Profiler	分析消息数量、方向与网络数据量。

Profiler 会给目标进程增加采样和数据汇总开销。应先使用较短采样窗口定位热点，再根据需要延长；生产环境采样前要确认当前负载，并同时观察 Tick、CPU、内存、消息量和网络包量，避免只依据单个耗时指标判断问题。

Space Viewer

选择 CellApp 后打开 Space Viewer，再选择要观察的 Space。该页面可以显示空间边界、NavMesh、Entity 类型和位置，用于排查场景加载、Entity 分布、移动和空间状态问题。

Space 数据会随 Entity 数量和刷新频率增加。大型场景或高 Entity 密度环境中，应按需开启图层并控制刷新频率，以减少目标 CellApp 的序列化开销、网络流量以及 GUIConsole 的绘制压力。

排查连接问题

无法发现组件或功能请求失败时，按以下顺序检查：

1. 确认 machine 和目标服务端组件已经启动。
2. 确认 Machine 的 UDP 发现端口可达，防火墙没有拦截发现请求和组件上报的 TCP 管理端点。
3. 确认 GUIConsole 的管理 Token 与当前环境的 management.adminToken 一致。
4. 确认 GUIConsole 与 KBEngine Nex 版本兼容；Space Viewer 还需要匹配的 3.x 协议扩展。
5. 跨主机或多网卡部署时，检查组件上报地址，并在 GUIConsole 中配置正确的地址映射。
6. 查看 GUIConsole 状态信息以及 Machine、Logger 和目标组件日志，定位认证、连接或协议错误。