304 lines
9.8 KiB
Markdown
304 lines
9.8 KiB
Markdown
# 内容浏览器接口
|
||
|
||
> **UEContentBrowserAgent** - 管理 UE 编辑器内的文件与文件夹结构
|
||
>
|
||
> 遵循 **奥卡姆剃刀** 原则，仅保留 **CRUD（增删改查）** 对应的 4 个原子工具。
|
||
|
||
## 工具矩阵
|
||
|
||
| 动词 | 工具名称 | 核心职责 | 说明 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| **查 (Read)** | `content.search` | 搜索资产路径、类名 | 获取操作目标的唯一途径 |
|
||
| **增 (Create)** | `content.import` | 导入外部文件 (FBX/PNG/WAV) | 外部资源进入 UE 的唯一入口 |
|
||
| **改 (Update)** | `content.move` | 移动 / 重命名 | **合并了 Move 和 Rename**，移动到原目录+新名字=重命名 |
|
||
| **删 (Delete)** | `content.delete` | 删除资产 / 文件夹 | 必要的清理能力 |
|
||
|
||
---
|
||
|
||
## 搜索资产 `content.search`
|
||
|
||
在 Content Browser 中查找匹配的资产路径。支持模糊匹配和类型过滤。
|
||
|
||
### 请求（JSON-RPC）
|
||
```json
|
||
{"ver":"1.0","type":"req","id":"cb1","method":"content.search","params":{
|
||
"query":"Red", // 必填，模糊匹配关键词
|
||
"filter_class":"Material", // 可选，类型过滤（如 Material, Texture2D, StaticMesh, Blueprint）
|
||
"limit":10 // 可选，返回数量限制（默认 50，最大 200）
|
||
}}
|
||
```
|
||
|
||
### 响应
|
||
```json
|
||
{"ver":"1.0","type":"res","id":"cb1","code":200,"result":{
|
||
"ok":true,
|
||
"count":3,
|
||
"results":[
|
||
{"name":"M_Red","path":"/Game/Materials/M_Red","class":"Material"},
|
||
{"name":"M_RedBrick","path":"/Game/Materials/M_RedBrick","class":"MaterialInstanceConstant"},
|
||
{"name":"T_RedTexture","path":"/Game/Textures/T_RedTexture","class":"Texture2D"}
|
||
]
|
||
}}
|
||
```
|
||
|
||
### 说明
|
||
- `query` 会同时匹配资产名称和路径，大小写不敏感。
|
||
- `filter_class` 支持常见类名：`Material`、`Texture2D`、`StaticMesh`、`SkeletalMesh`、`Blueprint`、`SoundWave` 等。
|
||
- 搜索范围固定为 `/Game/` 目录下所有资产。
|
||
- 返回结果按匹配顺序排列，达到 `limit` 后截止。
|
||
|
||
---
|
||
|
||
## 导入外部文件 `content.import`
|
||
|
||
将磁盘上的文件导入到 UE 项目中。UE 会自动识别文件类型并调用对应的导入器。
|
||
|
||
### 请求（JSON-RPC）
|
||
```json
|
||
{"ver":"1.0","type":"req","id":"cb2","method":"content.import","params":{
|
||
"files":[ // 必填，外部文件绝对路径列表
|
||
"C:/Downloads/Texture_01.png",
|
||
"C:/Downloads/Hero.fbx"
|
||
],
|
||
"destination_path":"/Game/Imported/Textures", // 可选，目标目录（默认 /Game/Imported）
|
||
"overwrite":true // 可选，是否覆盖同名文件（默认 false）
|
||
}}
|
||
```
|
||
|
||
### 响应
|
||
```json
|
||
{"ver":"1.0","type":"res","id":"cb2","code":200,"result":{
|
||
"ok":true,
|
||
"imported_count":2,
|
||
"requested_count":2,
|
||
"imported":[
|
||
{"name":"Texture_01","path":"/Game/Imported/Textures/Texture_01.Texture_01","class":"Texture2D"},
|
||
{"name":"Hero","path":"/Game/Imported/Textures/Hero.Hero","class":"SkeletalMesh"}
|
||
]
|
||
}}
|
||
```
|
||
|
||
### 说明
|
||
- `files` 中的路径必须是**绝对路径**，支持 Windows 和 Unix 风格。
|
||
- 不存在的文件会被跳过，并在日志中输出警告。
|
||
- `destination_path` 不存在时会自动创建。
|
||
- 支持的文件格式取决于 UE 内置导入器：
|
||
- 贴图：PNG, JPG, TGA, PSD, BMP, EXR
|
||
- 模型：FBX, OBJ, glTF (UE 5.0+)
|
||
- 音频：WAV, MP3, OGG, FLAC
|
||
- 其他：HDRI, Alembic 等
|
||
|
||
---
|
||
|
||
## 移动/重命名资产 `content.move`
|
||
|
||
移动资产到新目录，或通过修改目标路径名称实现重命名。两种操作合二为一。
|
||
|
||
### 请求（JSON-RPC）
|
||
```json
|
||
{"ver":"1.0","type":"req","id":"cb3","method":"content.move","params":{
|
||
"source_path":"/Game/OldFolder/MyAsset", // 必填，资产当前路径
|
||
"destination_path":"/Game/NewFolder/MyAsset_Renamed" // 必填，目标路径（包含新名字）
|
||
}}
|
||
```
|
||
|
||
### 响应
|
||
```json
|
||
{"ver":"1.0","type":"res","id":"cb3","code":200,"result":{
|
||
"ok":true,
|
||
"source_path":"/Game/OldFolder/MyAsset",
|
||
"destination_path":"/Game/NewFolder/MyAsset_Renamed",
|
||
"message":"Asset moved/renamed successfully"
|
||
}}
|
||
```
|
||
|
||
### 逻辑说明
|
||
| source | destination | 效果 |
|
||
| :--- | :--- | :--- |
|
||
| `/Game/A` | `/Game/Folder/A` | **移动**到新目录 |
|
||
| `/Game/A` | `/Game/B` | **重命名**（同目录） |
|
||
| `/Game/A` | `/Game/Folder/B` | **移动并重命名** |
|
||
|
||
### 说明
|
||
- 内部使用 `IAssetTools::RenameAssets`，会自动处理引用更新（Redirectors）。
|
||
- 若源资产不存在返回 `code: 404`。
|
||
- 若目标路径已存在同名资产，操作可能失败。
|
||
- 移动后建议执行 `FixupRedirectors` 清理重定向器（可通过编辑器手动操作）。
|
||
|
||
---
|
||
|
||
## 删除资产 `content.delete`
|
||
|
||
彻底删除指定的资产。支持批量删除。
|
||
|
||
### 请求（JSON-RPC）
|
||
```json
|
||
{"ver":"1.0","type":"req","id":"cb4","method":"content.delete","params":{
|
||
"paths":[ // 必填，要删除的资产路径列表
|
||
"/Game/Temp/TestActor",
|
||
"/Game/OldFolder/UnusedMaterial"
|
||
]
|
||
}}
|
||
```
|
||
|
||
### 响应
|
||
```json
|
||
{"ver":"1.0","type":"res","id":"cb4","code":200,"result":{
|
||
"ok":true,
|
||
"deleted_count":2,
|
||
"requested_count":2,
|
||
"deleted":[
|
||
"/Game/Temp/TestActor",
|
||
"/Game/OldFolder/UnusedMaterial"
|
||
],
|
||
"failed":[]
|
||
}}
|
||
```
|
||
|
||
### 部分失败响应
|
||
```json
|
||
{"ver":"1.0","type":"res","id":"cb4","code":200,"result":{
|
||
"ok":true,
|
||
"deleted_count":1,
|
||
"requested_count":2,
|
||
"deleted":["/Game/Temp/TestActor"],
|
||
"failed":["/Game/Referenced/InUseMaterial"]
|
||
}}
|
||
```
|
||
|
||
### 说明
|
||
- 删除操作**不可逆**，请确认后再执行。
|
||
- 被其他资产引用的资产可能无法删除（UE 会阻止以保护引用完整性）。
|
||
- 路径不存在的资产会被记入 `failed` 列表。
|
||
- 暂不支持删除文件夹（仅支持资产路径）。
|
||
|
||
---
|
||
|
||
## 错误码
|
||
|
||
| Code | 含义 | 说明 |
|
||
| :--- | :--- | :--- |
|
||
| `200` | 成功 | 操作全部完成 |
|
||
| `400` | 参数错误 | 缺少必填参数或参数格式错误 |
|
||
| `404` | 未找到 | 资产或路径不存在 |
|
||
| `500` | 内部错误 | UE 操作失败 |
|
||
|
||
---
|
||
|
||
## 与 AssetManagerAgent 的区别
|
||
|
||
| UEContentBrowserAgent | AssetManagerAgent |
|
||
| :--- | :--- |
|
||
| 管理 **Project Content**（项目内容） | 管理 **Asset Library**（资产库） |
|
||
| 操作硬盘上的 `.uasset` 文件 | 操作云端资产、标签、备注 |
|
||
| 路径以 `/Game/` 开头 | 使用资产库 ID |
|
||
| 功能：搜索、导入、移动、删除 | 功能：下载、标签、备注、收藏 |
|
||
|
||
**路由规则**：
|
||
- 用户提到 "导入贴图"、"移动资产"、"删除蓝图" → `ue_content_browser`
|
||
- 用户提到 "资产库"、"打标签"、"写备注" → `asset_manager`
|
||
|
||
---
|
||
|
||
## 使用示例
|
||
|
||
### 场景1：导入并整理资产
|
||
```
|
||
用户：把 C:/Downloads 下的 hero.fbx 导入到 /Game/Characters/Hero 目录
|
||
|
||
步骤：
|
||
1. content.import { files: ["C:/Downloads/hero.fbx"], destination_path: "/Game/Characters/Hero" }
|
||
```
|
||
|
||
### 场景2：搜索并重命名
|
||
```
|
||
用户：找到所有包含 Test 的材质，把第一个重命名为 M_Final
|
||
|
||
步骤：
|
||
1. content.search { query: "Test", filter_class: "Material" }
|
||
→ 返回 [{ path: "/Game/Materials/M_TestRed" }, ...]
|
||
2. content.move { source_path: "/Game/Materials/M_TestRed", destination_path: "/Game/Materials/M_Final" }
|
||
```
|
||
|
||
### 场景3：清理临时资产
|
||
```
|
||
用户：删除 /Game/Temp 下的所有测试资产
|
||
|
||
步骤：
|
||
1. content.search { query: "Temp" }
|
||
→ 返回 [{ path: "/Game/Temp/TestActor" }, { path: "/Game/Temp/TestMaterial" }]
|
||
2. content.delete { paths: ["/Game/Temp/TestActor", "/Game/Temp/TestMaterial"] }
|
||
```
|
||
|
||
---
|
||
|
||
## 资产优化审计 `content.audit_optimization`
|
||
|
||
检测项目中 Nanite、Lumen 等功能的使用情况，提供优化建议。用于构建优化和包体大小分析。
|
||
|
||
### 请求（JSON-RPC）
|
||
```json
|
||
{"ver":"1.0","type":"req","id":"audit1","method":"content.audit_optimization","params":{
|
||
"check_type":"NaniteUsage" // 可选，检查类型：NaniteUsage, LumenMaterials, TextureSize, All（默认 All）
|
||
}}
|
||
```
|
||
|
||
### 响应
|
||
```json
|
||
{"ver":"1.0","type":"res","id":"audit1","code":200,"result":{
|
||
"nanite_usage":{
|
||
"enabled_in_config":true,
|
||
"mesh_count":150,
|
||
"meshes_with_nanite":0,
|
||
"suggestion":"检测到您开启了 Nanite 支持，但场景中没有任何模型使用了 Nanite。建议在 Project Settings 中关闭 Nanite 以剔除相关着色器变体，可显著提升构建速度。"
|
||
},
|
||
"lumen_usage":{
|
||
"enabled_in_config":true,
|
||
"using_lumen_gi":true,
|
||
"materials_with_emissive":5,
|
||
"suggestion":"检测到 5 个材质使用了自发光，Lumen 功能正在被使用。"
|
||
},
|
||
"texture_analysis":{
|
||
"total_textures":120,
|
||
"large_textures_4k":15,
|
||
"estimated_memory_bytes":2147483648,
|
||
"estimated_memory_mb":2048,
|
||
"suggestion":"发现 15 个 4K 或更大的纹理，考虑压缩或降低分辨率以减少包体大小。"
|
||
}
|
||
}}
|
||
```
|
||
|
||
### 说明
|
||
|
||
#### 检查类型说明
|
||
|
||
- **NaniteUsage**：检测 Nanite 的使用情况
|
||
- 检查 `r.Nanite.ProjectEnabled` 配置
|
||
- 扫描所有 StaticMesh 资产，统计启用 Nanite 的网格数量
|
||
- 如果配置启用但未使用，提供优化建议
|
||
|
||
- **LumenMaterials**：检测 Lumen 的使用情况
|
||
- 检查 `r.Lumen.Enabled` 和 `r.DynamicGlobalIlluminationMethod` 配置
|
||
- 扫描材质资产，统计使用自发光的材质数量（Lumen 特征）
|
||
- 提供基于实际使用情况的建议
|
||
|
||
- **TextureSize**：分析纹理大小
|
||
- 统计所有纹理的数量和大小
|
||
- 识别 4K 或更大的纹理
|
||
- 估算总纹理内存使用
|
||
|
||
- **All**：执行所有检查（默认）
|
||
|
||
#### 优化建议示例
|
||
|
||
- Nanite 未使用：建议关闭以减小包体和提升构建速度
|
||
- Lumen 已启用但材质较少使用自发光：可以考虑禁用 Lumen
|
||
- 大纹理过多：建议压缩或降低分辨率
|
||
|
||
#### 注意事项
|
||
|
||
- 资产扫描操作可能需要较长时间，建议在项目资产加载完成后执行
|
||
- 仅在 UE 5.0+ 支持 Nanite 和 Lumen 检测
|
||
- 材质自发光检测使用简化方法，可能不完全准确
|
||
|
||
--- |