# 资产模块化架构 · 可独立分离与无限迭代

> 本文解决的问题：**怎么让"打磨刹车盘上一颗锈点"这件事，不需要重新打包整个游戏。**
> 结论先行：靠三重隔离——目录隔离、资产引用隔离、数据与逻辑隔离。

---

## 一、目录结构（UE5 Content）

一个模块 = 一个顶层目录 = 一个可独立打包的 Asset Bundle。
新增车型或赛道时，只加目录，**不修改任何既有文件**。

```
Content/
├─ SR3/
│  ├─ Core/                        ← 全局唯一，改动需全量回归
│  │  ├─ BP_GameMode
│  │  ├─ BP_PlayerController
│  │  ├─ Subsystems/               ← 登录、积分、排行、存档
│  │  └─ UI/Common/                ← 通用控件、加载态、转场
│  │
│  ├─ Vehicles/                    ← 每台车一个目录，互不引用
│  │  └─ SU7UltraConv/
│  │     ├─ Mesh/
│  │     │  ├─ Body/               ← 覆盖件
│  │     │  ├─ Lights/             ← 灯组（三层分离）
│  │     │  ├─ Wheels/             ← 轮组 + 刹车
│  │     │  ├─ Aero/               ← 空力套件
│  │     │  ├─ Glass/              ← 玻璃
│  │     │  └─ Interior/           ← 内饰（敞篷版必做）
│  │     ├─ Materials/
│  │     │  ├─ MI_Paint_RacingYellow
│  │     │  ├─ MI_Carbon_Twill
│  │     │  ├─ MI_Glass_Windshield
│  │     │  ├─ MI_Light_Housing
│  │     │  └─ MI_Leather_YellowBlack
│  │     ├─ Decals/                ← 全部细节贴花集中于此（见 §四）
│  │     ├─ Physics/
│  │     │  ├─ DA_VehicleSpec       ← 尺寸/质量/重心（数据资产）
│  │     │  ├─ DA_Suspension
│  │     │  ├─ DA_TireModel         ← Pacejka 曲线系数
│  │     │  └─ DA_Aero
│  │     ├─ Anim/
│  │     │  ├─ SK_VehicleRig        ← 骨骼
│  │     │  └─ AS_Door / AS_Roof    ← 动画序列
│  │     └─ DA_VehicleDefinition    ← 唯一入口，外部只引用它
│  │
│  ├─ Tracks/                      ← 每条赛道一个目录，五层分离
│  │  └─ JiangmenPengjiang/
│  │     ├─ Route/                 ← 路线样条 + 检查点（可单独替换）
│  │     ├─ Surface/               ← 路面材质与分层贴花
│  │     ├─ Props/                 ← 道具、护栏、标识
│  │     ├─ Landmarks/             ← 地标建筑（骑楼/广场/桥）
│  │     ├─ Lighting/              ← 光照预设与天气曲线
│  │     └─ DA_TrackDefinition
│  │
│  ├─ Shared/                      ← 跨模块共享，改动影响面最大，需评审
│  │  ├─ Materials/Master/         ← 母材质（车漆/碳纤/玻璃/金属）
│  │  ├─ Textures/Noise/           ← 通用噪声（橘皮/划痕/灰尘遮罩）
│  │  └─ DecalPresets/
│  │
│  └─ UI/
│     ├─ Menu/                     ← 主菜单、车库、设置
│     ├─ HUD/
│     └─ Flow/                     ← 加载、转场、登录
```

**硬规则**

1. `Vehicles/*` 之间**禁止互相引用**。共用材质必须下沉到 `Shared/`。
2. `Core/` 与 `UI/` **禁止引用具体车型目录**，只通过 `DA_VehicleDefinition` 的软引用（Soft Object Reference）取用。
3. 任何跨模块引用一律用 **软引用 + 异步加载**，禁止硬引用——硬引用会导致改一个车模就要重编整个链路。

---

## 二、三重隔离

### 1. 目录隔离
模块边界 = 目录边界。打包时按目录生成 Asset Bundle，客户端增量下发以目录为单位。

### 2. 引用隔离
```
Core  ──软引用──▶  DA_VehicleDefinition  ──硬引用──▶  该车的所有资产
                       ▲
                       └── 新增车辆只需注册一个新的 Definition，Core 不动
```
改车模细节 → 只影响该车目录 → `Core` 的编译产物哈希不变 → 不需要重新打包主程序。

### 3. 数据与逻辑隔离
物理参数、尺寸、材质参数**全部外置**为 DataAsset / 材质实例参数。
调手感 = 改数值；改漆色 = 改材质实例。**都不触发 C++ 或蓝图编译。**

---

## 三、细节资产的挂载方式

细节不写在模型里，而是**按清单挂载**。清单见 `03-detail-manifest.json`。

```
DA_VehicleDefinition
 └─ DetailProfile (DataAsset)
     └─ Entries[]
         ├─ DetailId: "D-001"          刹车盘锈迹
         ├─ TargetPart: SM_Brake_Disc  ← 挂到哪个部件
         ├─ Impl: Decal / MaterialLayer / Mesh / Niagara
         ├─ Params: {...}              ← 强度、密度、尺度
         └─ Condition: 静置>20min / 雨天 / 里程>500km
```

**收益**：
- 加一条新细节 = 往清单加一项 + 放一个资产，**不改代码**
- 关掉一条细节 = 把 `state` 改 `dropped`，或运行时按画质档位禁用
- 画质分级天然实现：低画质只跑 `P0`，极致档全开

---

## 四、迭代工作流（这是"无限打磨"的实际路径）

| 你想改的东西 | 需要动什么 | 需要重新打包什么 |
|---|---|---|
| 某个细节的强度/密度 | 改 `DetailProfile` 里一个数值 | 无，热更配置 |
| 换一套车漆颜色 | 改材质实例参数 / 新增实例 | 一个材质实例资产 |
| 换拉花图案 | 换一张贴花贴图 | 一张贴图 |
| 重做刹车盘模型 | 替换 `Mesh/Wheels` 下单个网格 | 该模块资产包（几十 MB 级） |
| 改驾驶手感 | 改 `DA_Suspension` / `DA_TireModel` 数值 | 无 |
| 重做整台车 | 替换 `Vehicles/SU7UltraConv/` 整个目录 | 该车资产包 |
| 换整条赛道 | 替换 `Tracks/JiangmenPengjiang/` | 该赛道资产包 |
| 改主菜单交互 | 改 `UI/Menu` | 主程序（不可避免，但 UI 变更频率低） |

**版本号策略**：资产包与主程序分开编号。
客户端启动时向 `/game/speed-rush-ai-v3/version.json` 取 `assetManifest`，
逐个模块比对哈希，只下载变化的部分。

---

## 五、与站内的衔接

| 站内位置 | 作用 |
|---|---|
| `version.json` | 主程序版本、安装包、SHA-1（单一事实源） |
| `docs/01-vehicle-su7ultra-spec.md` | 建模/材质依据 |
| `docs/03-detail-manifest.json` | 细节条目索引，也是迭代看板 |
| `brand/app.ico` | 打包图标 |

---

## 六、当前状态

- [x] 目录结构定义
- [x] 引用规则与三重隔离
- [x] 细节挂载清单（62 项：车辆 17 + 赛道环境 45，其中 P0 19 项）
- [x] 车辆 1:1 规格书 v0.1
- [ ] UE5 工程实体化（待引擎安装完成）
- [ ] 资产包分发与增量更新通道