ChildHood/tools/asset-catalog

Asset Catalog — UE5 资产扫描与语义增强工具

扫描 UE5 项目中的 StaticMesh / Material / Blueprint 资产，提取几何与材质数据，再通过 GLM API 批量推断语义信息（朝向、功能、交互属性等），生成一份可直接用于关卡搭建的资产数据库。

Pipeline 流程

┌─────────────────────────────────────────────────────────────────────┐
│  阶段 1：UE5 扫描（需要 UE5 编辑器）                                │
│                                                                     │
│  run_all.bat                                                        │
│    └─ 启动 UE5 无头模式，执行 run_all.py                            │
│         ├─ discover   → outputs/index.json        （资产清单）      │
│         ├─ mesh       → outputs/meshes/*.json      （几何数据）     │
│         ├─ material   → outputs/materials/*.json   （材质参数）     │
│         └─ blueprint  → outputs/blueprints/*.json  （蓝图结构）     │
└──────────────────────────┬──────────────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────────────┐
│  阶段 2：离线汇总（不需要 UE5）                                     │
│                                                                     │
│  python build_database.py                                           │
│    └─ 合并 meshes/*.json → outputs/asset_database.json              │
└──────────────────────────┬──────────────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────────────┐
│  阶段 3：AI 语义增强（离线，需要 GLM_API_KEY）                      │
│                                                                     │
│  python ai_inference.py                                             │
│    └─ 调用 GLM API，为每个资产推断：                                │
│         facing_direction / surface_height_cm / function_description │
│         placement_notes / interaction_hints / plausible_substitutes │
│    └─ 就地更新 outputs/asset_database.json                          │
└─────────────────────────────────────────────────────────────────────┘

前置条件

依赖	说明
Unreal Engine 5.7	阶段 1 需要，阶段 2/3 纯离线
Python 3.10+	脚本运行环境
openai 包	pip install openai（ai_inference.py 依赖）
GLM API Key	智谱开放平台 API Key，获取地址

使用步骤

1. 扫描资产

cd tools\asset-catalog
run_all.bat

启动 UE5 无头模式，自动执行 discover → mesh → material → blueprint 四步扫描。 完成后编辑器自动关闭，结果写入 outputs/ 目录。

自定义扫描范围：

set AC_SCAN_ROOT=/Game/MyFolder
set AC_STEPS=discover,mesh
run_all.bat

2. 汇总数据库

python build_database.py

将所有 outputs/meshes/*.json 合并为单一的 outputs/asset_database.json。

3. AI 语义增强

set GLM_API_KEY=你的密钥
python ai_inference.py

按类别分批调用 GLM API，为每个资产推断语义字段。支持断点续跑——中断后重新执行只会处理未完成的资产。

先预览批次划分（不调用 API）：

python ai_inference.py --dry-run

环境变量

UE5 扫描阶段

变量	默认值	说明
AC_SCAN_ROOT	/Game/BlockingStarterPack	要扫描的 UE5 Content 路径
AC_OUTPUT_DIR	<工具目录>/outputs	JSON 输出目录
AC_STEPS	discover,mesh,material,blueprint	要执行的步骤（逗号分隔）
AC_NO_QUIT	0	设为 1 扫描完成后不关闭编辑器
UE5_ROOT	自动检测	UE5 安装根目录（如 C:\Program Files\Epic Games\UE_5.7）

AI 推理阶段

变量	默认值	说明
GLM_API_KEY	—	（必填） 智谱 API Key
GLM_API_BASE	https://open.bigmodel.cn/api/coding/paas/v4	API 地址
GLM_MODEL	glm-5.1	使用的模型名称

输出目录结构

outputs/
├── index.json              # 资产清单（644 个资产的分类索引）
├── catalog_log.json        # 扫描运行日志（耗时、状态）
├── asset_database.json     # ⭐ 最终产物：425 个 Mesh 的完整数据库
├── meshes/                 # 每个子文件夹一个 JSON
│   ├── Architecture_Walls.json
│   ├── Furniture.json
│   └── ...
├── materials/              # 每个子文件夹一个 JSON
│   ├── MI_Architecture.json
│   └── ...
└── blueprints/             # 每个子文件夹一个 JSON
    ├── BP_Doors.json
    └── ...

CLI 参数

build_database.py

python build_database.py [--input DIR] [--output FILE]

  --input   扫描输出目录，默认 tools/asset-catalog/outputs
  --output  输出文件路径，默认 <input>/asset_database.json

ai_inference.py

python ai_inference.py [--input FILE] [--output FILE] [--batch-size N] [--dry-run]

  --input       输入 asset_database.json 路径，默认 outputs/asset_database.json
  --output      输出路径，默认就地更新
  --batch-size  每批资产数量，默认 5
  --dry-run     只打印批次信息，不调用 API

文件清单

文件	用途
run_all.bat	入口：启动 UE5 无头模式
run_all.py	UE5 内编排器：依次调用各分析脚本
_common.py	共享模块：环境变量、JSON I/O、工具函数
discover_assets.py	步骤 discover：资产发现与分类
analyze_meshes.py	步骤 mesh：StaticMesh 几何分析
analyze_materials.py	步骤 material：材质参数提取
analyze_blueprints.py	步骤 blueprint：蓝图结构分析
build_database.py	离线汇总：合并为 asset_database.json
ai_inference.py	离线推理：GLM API 语义增强