ceshi

2026-02-26 23:45:31 +08:00
parent aa599ea653
commit dd642c8585
79 changed files with 6044 additions and 0 deletions
--- a/Plugins/UnrealAgentLink/Resources/Docs/关卡工具接口文档.md
+++ b/Plugins/UnrealAgentLink/Resources/Docs/关卡工具接口文档.md
@@ -0,0 +1,174 @@
+# 关卡工具接口
+
+## 多维资产查询 `level.query_assets`
+对场景或项目中的资产进行多维度查询和性能分析，返回“罪证”与优化建议，便于技术美术排查。
+
+### 协议定义
+```json
+{
+  "method": "level.query_assets",
+  "description": "对场景或项目中的资产进行多维度查询和性能分析。",
+  "params": {
+    "scope": {                 // 范围
+      "type": "Level | ContentBrowser | Selection",
+      "path": "/Game/Props"    // 可选，限制文件夹
+    },
+    "conditions": {            // 查询条件（可组合）
+      "min_triangles": 50000,
+      "min_texture_size": 2048,
+      "max_texture_size": 0,
+      "shader_complexity_index": 0,
+      "missing_collision": true,
+      "nanite_enabled": false,
+      "shadow_casting": true,
+      "class_filter": "StaticMeshActor"
+    },
+    "sort_by": "TriangleCount | TextureMemory | DiskSize",
+    "limit": 20
+  }
+}
+```
+
+### 响应（带智能建议）
+```json
+{
+  "code": 200,
+  "result": {
+    "count": 5,
+    "assets": [
+      {
+        "name": "SM_CoffeeCup",
+        "path": "/Game/Props/SM_CoffeeCup.SM_CoffeeCup",
+        "type": "StaticMesh",
+        "stats": {
+          "triangles": 120000,
+          "texture_res": "4096 x 4096",
+          "nanite": false
+        },
+        "suggestion": "High poly count (120k) for a small object. Consider enabling Nanite or reducing LOD."
+      }
+    ]
+  }
+}
+```
+
+### 高级玩法示例
+- **垃圾资产猎人**：查高面数且未开启 Nanite 的静态网格  
+  ```json
+  {
+    "conditions": {
+      "min_triangles": 100000,
+      "nanite_enabled": false,
+      "class_filter": "StaticMeshActor"
+    }
+  }
+  ```
+- **显存杀手定位**：按纹理显存排序，取 Top N  
+  ```json
+  { "scope": { "type": "Level" }, "sort_by": "TextureMemory", "limit": 10 }
+  ```
+- **碰撞体检查**：查缺失碰撞的选中对象或特定命名物  
+  ```json
+  { "scope": { "type": "Selection" }, "conditions": { "missing_collision": true } }
+  ```
+- **光影优化**：筛大半径且投射阴影的灯光  
+  ```json
+  {
+    "conditions": {
+      "class_filter": "PointLight",
+      "shadow_casting": true,
+      "min_radius": 5000
+    }
+  }
+  ```
+
+### 前端可视化建议
+- Query Builder 拖拽式组合条件，生成 JSON 调用。
+- 结果卡片展示缩略图与“罪证”文本，支持一键修复（调用 `actor.set_property` 等）。
+
+### 提示
+- 这是接口契约文档，具体查询/统计逻辑需后端实现（如三角面数、贴图尺寸、Nanite 状态、碰撞体检测、材质复杂度等）。可分阶段支持：先实现核心指标，再逐步补齐高级字段。
+
+---
+
+## 批量组织Actor到文件夹 `level.organize_actors`
+批量将场景中的Actor归类到指定的世界大纲文件夹，支持按类名过滤。
+
+### 协议定义
+```json
+{
+  "method": "level.organize_actors",
+  "description": "批量将场景中的Actor归类到指定的世界大纲文件夹。",
+  "params": {
+    "folder_path": "Lighting/Indoor",    // 必需：目标文件夹路径
+    "filter": {                          // 可选：Actor过滤条件（与actor.get的filter格式相同）
+      "class_contains": "PointLight"      // 按类名过滤（包含匹配，忽略大小写）
+    }
+  }
+}
+```
+
+### 简化用法（直接传class参数）
+```json
+{
+  "method": "level.organize_actors",
+  "params": {
+    "folder_path": "Lighting/Indoor",
+    "class": "PointLight"                 // 简化用法：直接传类名
+  }
+}
+```
+
+### 响应
+```json
+{
+  "code": 200,
+  "result": {
+    "count": 5,                           // 成功设置的Actor数量
+    "total_found": 5,                     // 匹配到的Actor总数
+    "actors": [
+      {
+        "name": "PointLight_1",
+        "class": "PointLight",
+        "path": "/Game/Levels/MainLevel:PointLight_1",
+        "folder_path": "Lighting/Indoor"
+      }
+    ]
+  }
+}
+```
+
+### 使用示例
+- **将所有点光源归类到室内灯光文件夹**
+  ```json
+  {
+    "folder_path": "Lighting/Indoor",
+    "class": "PointLight"
+  }
+  ```
+- **将所有聚光灯归类到聚光灯文件夹**
+  ```json
+  {
+    "folder_path": "Lighting/SpotLights",
+    "filter": {
+      "class_contains": "SpotLight"
+    }
+  }
+  ```
+- **将所有静态网格Actor归类到道具文件夹**
+  ```json
+  {
+    "folder_path": "Props/StaticMeshes",
+    "filter": {
+      "class_contains": "StaticMeshActor"
+    }
+  }
+  ```
+
+### 注意事项
+- 此功能仅在编辑器模式下可用（`WITH_EDITOR`）
+- 文件夹路径使用斜杠分隔，如 `"Lighting/Indoor"`
+- 如果文件夹不存在，UE会自动创建
+- 操作支持撤销（Ctrl+Z）
+- filter参数支持与`actor.get`相同的所有过滤选项（class_contains, name_pattern, exclude_classes, property_match等）
+