资产模块化架构

源文件 02-asset-architecture.txt ｜ 由 Markdown 渲染，内容与原文一致

本文解决的问题：怎么让"打磨刹车盘上一颗锈点"这件事，不需要重新打包整个游戏。

结论先行：靠三重隔离——目录隔离、资产引用隔离、数据与逻辑隔离。

---

一、目录结构（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，极致档全开

---

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

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

---

五、与站内的衔接

---

六、当前状态

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