# 关卡工具接口

## 多维资产查询 `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等）