test-ue-project/Plugins/UnrealAgentLink/Resources/Docs/系统工具接口文档.md

系统接口

执行控制台指令 system.run_console_command

在当前 World 上执行任意控制台指令（与 cmd.exec_console 等价，推荐使用该命名）。

请求（JSON-RPC）

{"ver":"1.0","type":"req","id":"cmd1","method":"system.run_console_command","params":{
  "command":"stat fps"
}}

响应

{"ver":"1.0","type":"res","id":"cmd1","code":200,"result":{
  "result":"OK"
}}

• 若执行失败，code 为 500，result.result 为 "Failed"。

说明

• 支持 Editor/PIE/Standalone（内部会根据是否有 GEditor 选择世界）。
• 指令需确保在当前模式下有效；部分只读指令（如 stat 类）可直接使用，修改型指令需谨慎。

---

插件管理 system.manage_plugin

查询或修改虚幻插件的启用状态，适配 GLB/GLTF/USD/Python 等需要插件支持的场景。

请求

{"ver":"1.0","type":"req","id":"plugin1","method":"system.manage_plugin","params":{
  "plugin_name":"GLTFImporter",
  "action":"Query"
}}

• action 取值：Query（查询状态）、Enable（启用）、Disable（禁用）。默认 Query。

响应

{"ver":"1.0","type":"res","id":"plugin1","code":200,"result":{
  "plugin_name":"GLTFImporter",
  "is_enabled":true,
  "requires_restart":false,
  "friendly_name":"glTF Importer",
  "message":"Plugin enabled. Restart required."
}}

说明

• 找不到插件时返回 code 404。
• 状态发生变化时 requires_restart 为 true，需提示用户重启编辑器。
• 典型插件：GLTFImporter、DatasmithGLTFImporter、USDImporter、PythonScriptPlugin。

---

获取性能统计 system.get_performance_stats

返回当前采样周期的平均 FPS 以及各线程/GPU 的耗时（毫秒）。

请求

{"ver":"1.0","type":"req","id":"perf1","method":"system.get_performance_stats","params":{}}

响应

{"ver":"1.0","type":"res","id":"perf1","code":200,"result":{
  "fps": 118.3,
  "frame_ms": 8.45,
  "game_thread_ms": 3.12,
  "render_thread_ms": 2.76,
  "rhi_thread_ms": 0.80,
  "gpu_ms": 5.10
}}

说明

• 数据来源：引擎统计全局均值（GAverageFPS/GAverageMS/GAverageGameTime/GAverageDrawTime/GAverageRHITTime/GAverageGPUTime），需引擎已运行一段时间以形成均值。
• 各字段单位均为毫秒；fps 为帧率。若统计尚未有效（刚启动），数值可能为 0。
• UE 5.0 限制：在 UE 5.0 中，render_thread_ms、rhi_thread_ms 和 gpu_ms 将始终返回 0，因为这些统计变量未通过 ENGINE_API 导出，插件无法直接访问。这是引擎版本的限制，不是插件的问题。
  • 在 UE 5.1+ 中，这些值可以正常获取。
  • 如需在 UE 5.0 中查看这些统计信息，请使用控制台命令：
    • stat unit - 显示所有线程和GPU时间
    • stat scenerendering - 显示场景渲染统计
    • stat rhi - 显示RHI线程统计
    • stat game - 显示游戏线程统计