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

关卡工具接口

多维资产查询 level.query_assets

对场景或项目中的资产进行多维度查询和性能分析，返回“罪证”与优化建议，便于技术美术排查。

协议定义

{
  "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
  }
}

响应（带智能建议）

{
  "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 的静态网格

  {
    "conditions": {
      "min_triangles": 100000,
      "nanite_enabled": false,
      "class_filter": "StaticMeshActor"
    }
  }
  

• 显存杀手定位：按纹理显存排序，取 Top N

  { "scope": { "type": "Level" }, "sort_by": "TextureMemory", "limit": 10 }
  

• 碰撞体检查：查缺失碰撞的选中对象或特定命名物

  { "scope": { "type": "Selection" }, "conditions": { "missing_collision": true } }
  

• 光影优化：筛大半径且投射阴影的灯光

  {
    "conditions": {
      "class_filter": "PointLight",
      "shadow_casting": true,
      "min_radius": 5000
    }
  }
  

前端可视化建议

• Query Builder 拖拽式组合条件，生成 JSON 调用。
• 结果卡片展示缩略图与“罪证”文本，支持一键修复（调用 actor.set_property 等）。

提示

• 这是接口契约文档，具体查询/统计逻辑需后端实现（如三角面数、贴图尺寸、Nanite 状态、碰撞体检测、材质复杂度等）。可分阶段支持：先实现核心指标，再逐步补齐高级字段。

---

批量组织Actor到文件夹 level.organize_actors

批量将场景中的Actor归类到指定的世界大纲文件夹，支持按类名过滤。

协议定义

{
  "method": "level.organize_actors",
  "description": "批量将场景中的Actor归类到指定的世界大纲文件夹。",
  "params": {
    "folder_path": "Lighting/Indoor",    // 必需：目标文件夹路径
    "filter": {                          // 可选：Actor过滤条件（与actor.get的filter格式相同）
      "class_contains": "PointLight"      // 按类名过滤（包含匹配，忽略大小写）
    }
  }
}

简化用法（直接传class参数）

{
  "method": "level.organize_actors",
  "params": {
    "folder_path": "Lighting/Indoor",
    "class": "PointLight"                 // 简化用法：直接传类名
  }
}

响应

{
  "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"
      }
    ]
  }
}

使用示例

• 将所有点光源归类到室内灯光文件夹

  {
    "folder_path": "Lighting/Indoor",
    "class": "PointLight"
  }
  

• 将所有聚光灯归类到聚光灯文件夹

  {
    "folder_path": "Lighting/SpotLights",
    "filter": {
      "class_contains": "SpotLight"
    }
  }
  

• 将所有静态网格Actor归类到道具文件夹

  {
    "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等）