159 lines
8.2 KiB
Markdown
159 lines
8.2 KiB
Markdown
# 资源管理规范（目录与资产归属）
|
||
|
||
本文档规定：**自研运行时资源**在 `Assets/` 下的**摆放层次**。
|
||
**怎么加载**（`ResourceSystem`、Addressable Key/Group/Label）见 [资源加载最佳实践](ResourceLoadingBestPractices.md)。
|
||
|
||
---
|
||
|
||
## 1. 总结构：一棵「运行时内容」树 + 归档 + 例外
|
||
|
||
```
|
||
Assets/
|
||
├── GameContent/ ← 自研「运行时资源」统一入口
|
||
│ ├── Common/ ← 全局共用（跨场景、跨系统）
|
||
│ ├── UI/ ← 跨场景 UI 相关（通用控件、主题、共用界面等）
|
||
│ ├── Scene_{Name}/ ← 关卡/场景线独占资源（与 §1.1 前缀约定一致）
|
||
│ ├── Feature_{Name}/ ← 玩法/功能模块（可跨场景；与 Scene_ 同级，层级统一）
|
||
│ └── …
|
||
├── Narrative/ ← Yarn 与 Dialog 本地化（见 §6）
|
||
│ ├── Yarn/
|
||
│ └── Localization/
|
||
├── _Archive/ ← 归档（见 §5）
|
||
├── Scenes/ ← .unity 场景文件（勿与 GameContent/Scene_* 混淆）
|
||
├── Scripts/、Editor/ ← 代码
|
||
└── （其它见 §4「不并入 GameContent 的目录」）
|
||
```
|
||
|
||
**`GameContent/` 内两层规则：**
|
||
|
||
1. **第一层**：`Common`、`UI`、**`Scene_*` / `Feature_*`**（命名见 §1.1）。
|
||
2. **第二层**：再按 **资源类型** 分子文件夹（见 §2）。
|
||
|
||
### 1.1 场景与功能目录命名
|
||
|
||
与 `Common/`、`UI/` **同级摊平**，用 **`Scene_` / `Feature_` 前缀**区分关卡线与功能模块：
|
||
|
||
| 前缀 | 含义 | 示例 |
|
||
|------|------|------|
|
||
| `Scene_` | **关卡/场景线**独占（与 `.unity` 或章节强绑定） | `Scene_ClinicOut/`、`Scene_SubWay/`、`Scene_Dream/` |
|
||
| `Feature_` | **玩法/功能模块**（可跨多个场景加载） | `Feature_BlockPuzzle/`、`Feature_HuoShanFix/` |
|
||
|
||
- 与 `Common/`、`UI/` **同一层级**；`Scene_`、`Feature_` 之后为 **PascalCase** 代号（可含多个单词，如 `HuoShanFix`）。
|
||
- 前缀与代号之间用 **下划线** 分隔（与常见 Addressable Group 命名一致，如 `Scene_ClinicOut`）。
|
||
|
||
**与 `Assets/Scenes/`**：后者仅放 **`.unity` 场景文件**；`GameContent/Scene_*` 放该关**资源**。名称相似，沟通时区分清楚。
|
||
|
||
---
|
||
|
||
## 2. `GameContent/` 下的标准类型子目录
|
||
|
||
在 `Common/`、`UI/`、`Scene_*` / `Feature_*` 根目录下，按需建立下列 **类型** 子目录（不必全部存在）。
|
||
|
||
| 子目录 | 内容 |
|
||
|--------|------|
|
||
| `Art/` | Sprite、贴图、序列帧等；**可直接使用 `.psd`** 作为导入素材（Unity PSD 导入），无需为「规范」强行改成 PNG；大文件注意仓库体积与导入设置。 |
|
||
| `Prefab/` | Prefab |
|
||
| `Render/` | 该归属范围内的渲染相关：如 Volume Profile、场景专用 Renderer 设置、仅本关使用的渲染资源等；**全局 URP/Renderer 主配置**优先放 `Common/Render/`。 |
|
||
| `Animation/` | `.anim`、Animator Controller 等 |
|
||
| `Material/` | 材质（若与全局共用重复，优先放 `Common/Material/`） |
|
||
| `Shader/` | 项目自研 Shader（仅当该关/该模块专属；全局 Shader 放 `Common/Shader/`） |
|
||
| `Data/` | ScriptableObject、关卡 JSON 等数据资产 |
|
||
| `Timeline/` | Timeline / `.playable` 等（与 `Animation/` 分目录存放） |
|
||
|
||
**命名**：类型子目录统一 **PascalCase**（`Art`、`Prefab`、`Render`），不要混用 `art` / `Art`。
|
||
|
||
**音频**：项目运行时音频走 **FMOD**，不在 `GameContent/` 下另建 `Audio/`；银行与流式路径见 §4。
|
||
|
||
**禁止**：在 `Art/` 里长期放 Prefab、在 `Material/` 里放 Prefab；全局管线与业务材质混在同一个 `Render/` 根里不分类（应靠 `Common` 与 `Scene_*` / `Feature_*` 分清）。
|
||
|
||
---
|
||
|
||
## 3. 各第一层目录的职责
|
||
|
||
### 3.1 `GameContent/Common/`
|
||
|
||
- **全程或大范围共用**的资源：全局材质、通用 Shader、默认 UI 以外的共享特效、常驻角色/道具（若约定放此）、全局 `Render/` 等。
|
||
- 与 **Persistence / 常驻加载** 相关的资源，优先落在此处或与此目录并列的单独约定（与 Addressable `Core` 等组对齐即可）。
|
||
|
||
### 3.2 `GameContent/UI/`
|
||
|
||
- **跨多个场景出现的 UI**：通用面板、按钮样式、共享 HUD 预制体、UI 动效、UI 用图与材质等。
|
||
- **仅某一关专属的界面**：放在对应 **`Scene_*/Prefab/`** 或 **`Scene_*/Art/`**，不放在 `GameContent/UI/`。
|
||
|
||
### 3.3 `GameContent/Scene_*` 与 `GameContent/Feature_*`
|
||
|
||
- **`Scene_*`**：只服务**某一关卡/场景线**的资源（与 §1.1 一致）。
|
||
- **`Feature_*`**：**玩法或功能模块**（可跨场景），与单关独占资源分开。
|
||
- 新增场景线或功能模块时：新建 **`Scene_*` 或 `Feature_*`** 文件夹（命名见 §1.1），资源只进对应目录。
|
||
|
||
---
|
||
|
||
## 4. 不并入 `GameContent/` 的目录（例外）
|
||
|
||
以下目录因 Unity / 管线 / 第三方原因，**保留在既有路径**，不强行迁入 `GameContent/`；规范上视为「运行时相关但单独管理」。
|
||
|
||
| 路径 | 说明 |
|
||
|------|------|
|
||
| `Assets/Resources/` | Unity 特殊文件夹；仅保留约定用途，勿堆无关运行时资源。 |
|
||
| `Assets/StreamingAssets/` | 运行时原始文件读取。 |
|
||
| `Assets/Language/` | Unity Localization：**Locales、UIText、ActorName 等全局表**放此处。Dialog 字串表规范见 **§6**（`Narrative/Localization/`）。 |
|
||
| `Assets/FMOD Banks/`、`StreamingAssets` 下 FMOD | 音频工程输出，按音频管线。 |
|
||
| `Assets/Plugins/`、`Samples/`、`Shapes/` 等 | 第三方与示例，**不合并**进 `GameContent/`。 |
|
||
|
||
---
|
||
|
||
## 5. 归档资源（与运行时分离）
|
||
|
||
- **废弃或仅作参考** 的资源放在 **`Assets/_Archive/`**。
|
||
- **禁止**将归档目录内资源作为正式内容引用；若需使用，须先移入 `GameContent/` / `Narrative/` 等正式目录并纳入正常流程。
|
||
|
||
---
|
||
|
||
## 6. Yarn 与 Dialog 本地化（`Narrative/`）
|
||
|
||
Yarn 脚本与 Unity Localization **Dialog 字串表**统一放在 **`Assets/Narrative/`** 下，分两个类型目录，便于与 **`Assets/Language/`** 里全局表区分、也便于两边对照。
|
||
|
||
### 目录结构（当前）
|
||
|
||
```
|
||
Assets/Narrative/
|
||
├── Yarn/ ← .yarn、`.yarnproject`（Yarn 工程入口）
|
||
└── Localization/ ← Dialog 相关 String Table（含各语言、Shared Data 等）
|
||
```
|
||
|
||
**仍放在 `Assets/Language/` 的**：`Locales/`、`UIText/`、`ActorName/`、`Params/`、`Sprite/` 等**非按对话模块切分**的本地化内容。
|
||
|
||
**后续**：按剧情模块再分子目录（或迁入 `Narrative/{ModuleId}/…`）待 Yarn 与引用链统一后再做；当前阶段以**整包迁入 `Yarn/`、`Localization/`** 为准。
|
||
|
||
---
|
||
|
||
## 7. 与 Addressable 的对应关系
|
||
|
||
`GameContent/` 下每个 **`Scene_*` / `Feature_*`**（及 `Common`、`UI`）子树，在概念上对应 **一个或一组 Addressable Group**；`Narrative/` 内资源按项目分组策略与 Yarn / Localization 管线对齐。新增分组时应有对应磁盘路径。Addressable Key、条目维护见《资源加载最佳实践》。
|
||
|
||
---
|
||
|
||
## 8. 命名与自检
|
||
|
||
- **场景/功能**：与 `Common`、`UI` 同级，使用 **`Scene_` / `Feature_` 前缀** 文件夹（见 §1.1）。
|
||
- **`Assets/Scenes/`**（.unity）：建议区分正式关卡与测试场景（子文件夹或 `Test_` 前缀）；勿与 `GameContent/Scene_*` 混为一谈。
|
||
- **自检（提交前可扫）**
|
||
- [ ] 新 Yarn / Dialog 表落在 **`Narrative/Yarn/`**、**`Narrative/Localization/`**（§6）；全局本地化仍在 **`Language/`** 约定路径。
|
||
- [ ] 新资源落在 `GameContent/` 的正确位置（Common / UI / 对应 `Scene_*` 或 `Feature_*`）及类型子目录。
|
||
- [ ] Prefab 不在 `Art/`、`Material/` 等纯类型目录中长期混放。
|
||
- [ ] 归档目录无正式引用。
|
||
- [ ] 未把第三方示例打进正式 Addressable Group。
|
||
|
||
---
|
||
|
||
## 9. 与《资源加载最佳实践》的分工
|
||
|
||
| 文档 | 内容 |
|
||
|------|------|
|
||
| **本文** | `GameContent/`、`Narrative/`（Yarn+Dialog）、归档与例外目录。 |
|
||
| **资源加载最佳实践** | 加载 API、Key、Group、Label、生命周期与性能。 |
|
||
|
||
---
|
||
|
||
*文档版本: 3.8 — Yarn/Dialog 规范移至 §6。*
|