chore: 资源组织规范

2026-03-27 22:25:15 +08:00
parent 209a795141
commit 0ec85e0cda
2 changed files with 167 additions and 6 deletions
@@ -1,4 +1,4 @@
-# CLAUDE.md
+# CLAUDE.md

 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

@@ -21,7 +21,7 @@ The project uses a custom modular framework with these key systems:
 - **EventSystemKit**: Decoupled event system for inter-system communication
 - **PoolKit**: Object pooling for performance optimization
 - **ResourceKit**: Asset loading and resource management
-  - **Note**: New code should use `ResourceSystem` (via Addressables), see [Resource Loading Best Practices Guide](Docs/ResourceLoadingBestPractices.md) for details
+  - **Note**: New code should use `ResourceSystem` (via Addressables), see [Resource Loading Best Practices Guide](Docs/ResourceLoadingBestPractices.md) for details. **Where assets live on disk** (e.g. `GameContent/`, `Narrative/`) is defined in [Resource Management Spec](Docs/ResourceManagementSpec.md).
 - **SingletonKit**: Singleton base classes for managers
 - **StateMachineKit**: Game state management
 - **TimelineKit**: Timeline-based event sequencing
@@ -97,9 +97,11 @@ Assets\Open C# Project.regenerate-sln.bat

 ### Yarn Dialogue Files

-Located in `Assets/Resources/Yarn/`, organized by character and day:
- Each character has their own folder
- Files follow pattern: `{Character}_{Stage}.yarn`
+Target layout and co-location with Dialog localization tables: [Resource Management Spec](Docs/ResourceManagementSpec.md) (`Assets/Narrative/Yarn/`, `Assets/Narrative/Localization/`). Legacy paths may still include `Assets/Resources/Yarn/` during migration.
+
+Convention for file naming and UTF-8:
+- Organize by narrative module / character and day as the project requires
+- Files often follow pattern: `{Character}_{Stage}.yarn`
 - Use UTF-8 encoding for Chinese text support

 ### Asset Naming Conventions
@@ -182,7 +184,8 @@ For testing mechanics before Unity implementation:

 ## Reference Documents

- [Resource Loading Best Practices Guide](Docs/ResourceLoadingBestPractices.md) - Addressables resource loading specifications, naming conventions, and performance optimization
+- [Resource Loading Best Practices Guide](Docs/ResourceLoadingBestPractices.md) - How to load assets: `ResourceSystem`, Addressables Key/Group/Label, lifecycle and performance
+- [Resource Management Spec](Docs/ResourceManagementSpec.md) - Where to place assets: `GameContent/`, `Narrative/` (Yarn + Dialog tables), `_Archive/`, and exceptions (distinct from loading mechanics above)
 - [Commit Convention](COMMIT_CONVENTION.md) - Git commit message format and branch naming rules

 ---
@@ -0,0 +1,158 @@
+# 资源管理规范（目录与资产归属）
+
+本文档规定：**自研运行时资源**在 `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。*