175 lines
4.7 KiB
Markdown
175 lines
4.7 KiB
Markdown
# 关卡工具接口
|
||
|
||
## 多维资产查询 `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等）
|
||
|