ceshi

Plugins/UnrealAgentLink/Resources/Docs/系统工具接口文档.md

@@ -0,0 +1,87 @@
+# 系统接口
+
+## 执行控制台指令 `system.run_console_command`
+在当前 World 上执行任意控制台指令（与 `cmd.exec_console` 等价，推荐使用该命名）。
+
+### 请求（JSON-RPC）
+```json
+{"ver":"1.0","type":"req","id":"cmd1","method":"system.run_console_command","params":{
+  "command":"stat fps"
+}}
+```
+
+### 响应
+```json
+{"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 等需要插件支持的场景。
+
+### 请求
+```json
+{"ver":"1.0","type":"req","id":"plugin1","method":"system.manage_plugin","params":{
+  "plugin_name":"GLTFImporter",
+  "action":"Query"
+}}
+```
+- `action` 取值：`Query`（查询状态）、`Enable`（启用）、`Disable`（禁用）。默认 `Query`。
+
+### 响应
+```json
+{"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 的耗时（毫秒）。
+
+### 请求
+```json
+{"ver":"1.0","type":"req","id":"perf1","method":"system.get_performance_stats","params":{}}
+```
+
+### 响应
+```json
+{"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` - 显示游戏线程统计 
+