diff --git a/CLAUDE.md b/CLAUDE.md index e994ff824..59a1a5017 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 --- diff --git a/Docs/ResourceManagementSpec.md b/Docs/ResourceManagementSpec.md new file mode 100644 index 000000000..5e77b91f0 --- /dev/null +++ b/Docs/ResourceManagementSpec.md @@ -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。*