# 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，[获取地址](https://open.bigmodel.cn) |

## 使用步骤

### 1. 扫描资产

```cmd
cd tools\asset-catalog
run_all.bat
```

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

> **自定义扫描范围：**
> ```cmd
> set AC_SCAN_ROOT=/Game/MyFolder
> set AC_STEPS=discover,mesh
> run_all.bat
> ```

### 2. 汇总数据库

```cmd
python build_database.py
```

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

### 3. AI 语义增强

```cmd
set GLM_API_KEY=你的密钥
python ai_inference.py
```

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

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

```cmd
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 语义增强 |