tinbird/aibis-dream

Fork 0

Files

T

dingyuntian 0ec85e0cda chore: 资源组织规范

2026-03-27 22:25:15 +08:00

8.2 KiB

Raw Blame History

资源管理规范（目录与资产归属）

本文档规定：自研运行时资源在 Assets/ 下的摆放层次。
怎么加载（ResourceSystem、Addressable Key/Group/Label）见资源加载最佳实践。

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/ 内两层规则：

第一层：Common、UI、Scene_* / Feature_*（命名见 §1.1）。
第二层：再按 资源类型 分子文件夹（见 §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。

8.2 KiB Raw Blame History Unescape Escape