test-ue-project/Plugins/UnrealAgentLink/Resources/Docs/编辑器工具接口文档.md

编辑器工具接口

抓取当前视口截图 editor.screenshot

从当前 Editor 视口（优先使用 GEditor 活跃视口，否则 GameViewport）抓屏，编码为 PNG，并返回 Base64 与本地保存路径。已通过 UAL_VersionCompat 适配 UE5.0–5.7（内部封装了 IImageWrapper::GetCompressed 的 5.0/5.1+ 差异）。
兼容旧名 take_screenshot（未来可逐步下线）。

请求（JSON-RPC）

{"ver":"1.0","type":"req","id":"cap1","method":"editor.screenshot","params":{
  "filepath":"UAL_shot.png",      // 可选，文件名或路径，默认 Saved/Screenshots/UAL/ 下按时间戳命名
  "resolution":[1280,720],        // 可选，[width,height]，不填则按视口原分辨率；内部使用最近邻缩放
  "show_ui":false                 // 可选，是否包含 UI（当前逻辑不剔除 UI，预留字段）
}}

响应

{"ver":"1.0","type":"res","id":"cap1","code":200,"result":{
  "path":"I:/UnrealAgent/UALinkDev/Saved/Screenshots/UAL/UAL_shot.png",
  "filename":"UAL_shot.png",
  "width":1280,
  "height":720,
  "saved":true,
  "show_ui":false,
  "base64":"iVBORw0KGgoAAA...",      // PNG 数据的 base64
  "save_error":"Failed to write screenshot to disk" // 仅在写盘失败时出现
}}

说明

• 默认保存目录：Saved/Screenshots/UAL/，会自动创建。
• resolution 不填则按视口当前分辨率；如填写，使用最近邻缩放。
• 失败时返回 code 500，error.message 描述原因（如无可用视口、像素读取/编码失败、写盘失败）。带 base64 即可直接传输给服务端。
• 版本兼容：后续若有新增 API 差异，请统一追加到 UAL_VersionCompat，业务层无需再写版本宏。

---

读取配置项 project.get_config

读取项目配置文件（如 DefaultEngine.ini、DefaultGame.ini 等）中的配置项值。

请求（JSON-RPC）

{"ver":"1.0","type":"req","id":"cfg1","method":"project.get_config","params":{
  "config_name":"Engine",                              // 必填，配置文件名称：Engine, Game, Editor, EditorPerProjectUserSettings
  "section":"/Script/Engine.RendererSettings",        // 必填，配置节名称
  "key":"r.DynamicGlobalIlluminationMethod"           // 必填，配置项键名
}}

响应

{"ver":"1.0","type":"res","id":"cfg1","code":200,"result":{
  "config_name":"Engine",
  "section":"/Script/Engine.RendererSettings",
  "key":"r.DynamicGlobalIlluminationMethod",
  "value":"Lumen",
  "file_path":"I:/UnrealAgent/UALinkDev/Config/DefaultEngine.ini"
}}

说明

• config_name 支持的取值：
  • Engine → DefaultEngine.ini
  • Game → DefaultGame.ini
  • Editor → DefaultEditor.ini
  • EditorPerProjectUserSettings → DefaultEditorPerProjectUserSettings.ini
• 如果配置项不存在，value 字段返回空字符串（不是错误）。
• 失败时返回 code 400，error.message 描述原因（如缺少参数、不支持的 config_name）。

---

设置配置项 project.set_config

修改项目配置文件中的配置项值，并立即刷新到磁盘。

请求（JSON-RPC）

{"ver":"1.0","type":"req","id":"cfg2","method":"project.set_config","params":{
  "config_name":"Engine",
  "section":"/Script/UnrealEd.ProjectPackagingSettings",
  "key":"bShareMaterialShaderCode",
  "value":"True"                                      // 必填，统一传字符串，C++端解析
}}

响应

{"ver":"1.0","type":"res","id":"cfg2","code":200,"result":{
  "config_name":"Engine",
  "section":"/Script/UnrealEd.ProjectPackagingSettings",
  "key":"bShareMaterialShaderCode",
  "value":"True",
  "file_path":"I:/UnrealAgent/UALinkDev/Config/DefaultEngine.ini"
}}

说明

• config_name 支持的取值同 project.get_config。
• value 必须为字符串格式，支持布尔值（True/False）、整数、浮点数、字符串等。
• 设置后会自动调用 GConfig->Flush() 将更改写入磁盘。
• 失败时返回 code 400，error.message 描述原因。

---

分析项目文件 project.analyze_uproject

解析 .uproject 文件，返回项目的模块、插件、目标平台等信息。

请求（JSON-RPC）

{"ver":"1.0","type":"req","id":"uproj1","method":"project.analyze_uproject","params":{}}

响应

{"ver":"1.0","type":"res","id":"uproj1","code":200,"result":{
  "engine_association":"5.0",
  "target_platforms":["Windows","Linux"],
  "modules":[
    {"Name":"UALinkDev","Type":"Runtime","LoadingPhase":"Default"}
  ],
  "plugins":[
    {
      "name":"GLTFImporter",
      "enabled":true,
      "category":"Importers",
      "version_name":"1.0",
      "friendly_name":"glTF Importer",
      "description":"Import glTF 2.0 files",
      "base_dir":"I:/UnrealAgent/UALinkDev/Plugins/GLTFImporter"
    },
    {
      "name":"Paper2D",
      "enabled":false,
      "category":"BuiltIn",
      "version_name":"",
      "friendly_name":"Paper2D",
      "description":"",
      "base_dir":""
    }
  ]
}}

说明

• 无需参数，自动读取当前项目的 .uproject 文件。
• modules 数组包含完整的模块对象（Name、Type、LoadingPhase 等字段）。
• plugins 数组包含插件详细信息，已启用的插件标记 enabled: true。
• 如果插件在当前环境中可解析，会补全版本、分类、描述等信息；否则字段为空字符串。
• 失败时返回 code 500，error.message 描述原因（如文件读取失败、JSON 解析失败）。

---