docs: audit and fix standards docs inconsistencies (v1.2)

AssetFolderSpec.md:
- §8.1: Enemies_{Region} → Enemies (match AddressableRules.cs single group)
- §8.4: fix old menu paths (Tools/Verification → Addressables)
- §10.3: fix Skill SO path (Data/Player/Skills → Data/Progression/Skills)
- §10.4: Charm workflow — remove 'bypass editor tools' recommendation
- §3.2: add SPL_ prefix for SpellSO
- Bump to v1.2

AddressablesLabelSpec.md:
- §6 step 7: fix old Verification menu path
- §7.2/7.3/7.4: unify menu notation (→ to /) and fix old Tools/Verification paths
- Bump to v1.2

AddressKeys.cs:
- Remove duplicate <summary> XML doc comment in Labels class

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
2026-05-20 13:32:26 +08:00
parent 82ce9ff09a
commit b5c852f5e4
5 changed files with 87 additions and 25 deletions

View File

@@ -922,14 +922,14 @@ MonoBehaviour:
DefaultMode: 2 DefaultMode: 2
DefaultBlend: DefaultBlend:
Style: 1 Style: 1
Time: 2 Time: 1
CustomCurve: CustomCurve:
serializedVersion: 2 serializedVersion: 2
m_Curve: [] m_Curve: []
m_PreInfinity: 2 m_PreInfinity: 2
m_PostInfinity: 2 m_PostInfinity: 2
m_RotationOrder: 4 m_RotationOrder: 4
CustomBlends: {fileID: 0} CustomBlends: {fileID: 11400000, guid: 9906ca91115b34d498a040782ef36e92, type: 2}
--- !u!81 &464414703 --- !u!81 &464414703
AudioListener: AudioListener:
m_ObjectHideFlags: 0 m_ObjectHideFlags: 0
@@ -971,7 +971,7 @@ Camera:
height: 1 height: 1
near clip plane: 0.1 near clip plane: 0.1
far clip plane: 5000 far clip plane: 5000
field of view: 40 field of view: 10
orthographic: 0 orthographic: 0
orthographic size: 10 orthographic size: 10
m_Depth: 0 m_Depth: 0
@@ -998,7 +998,7 @@ Transform:
m_GameObject: {fileID: 464414701} m_GameObject: {fileID: 464414701}
serializedVersion: 2 serializedVersion: 2
m_LocalRotation: {x: 0, y: 0, z: 0, w: 1} m_LocalRotation: {x: 0, y: 0, z: 0, w: 1}
m_LocalPosition: {x: 0, y: 0, z: 0} m_LocalPosition: {x: -18.954266, y: 5.5, z: -64}
m_LocalScale: {x: 1, y: 1, z: 1} m_LocalScale: {x: 1, y: 1, z: 1}
m_ConstrainProportionsScale: 0 m_ConstrainProportionsScale: 0
m_Children: [] m_Children: []

View File

@@ -4304,6 +4304,7 @@ Transform:
m_Children: m_Children:
- {fileID: 1351863799} - {fileID: 1351863799}
- {fileID: 1484423199} - {fileID: 1484423199}
- {fileID: 2035265042}
m_Father: {fileID: 783576435} m_Father: {fileID: 783576435}
m_LocalEulerAnglesHint: {x: 0, y: 0, z: 0} m_LocalEulerAnglesHint: {x: 0, y: 0, z: 0}
--- !u!1 &200829413 --- !u!1 &200829413
@@ -21980,7 +21981,7 @@ GameObject:
m_Icon: {fileID: 0} m_Icon: {fileID: 0}
m_NavMeshLayer: 0 m_NavMeshLayer: 0
m_StaticEditorFlags: 0 m_StaticEditorFlags: 0
m_IsActive: 1 m_IsActive: 0
--- !u!61 &1354690326 --- !u!61 &1354690326
BoxCollider2D: BoxCollider2D:
m_ObjectHideFlags: 0 m_ObjectHideFlags: 0
@@ -26723,6 +26724,63 @@ Transform:
- {fileID: 67436266} - {fileID: 67436266}
m_Father: {fileID: 1076068180} m_Father: {fileID: 1076068180}
m_LocalEulerAnglesHint: {x: 0, y: 0, z: 0} m_LocalEulerAnglesHint: {x: 0, y: 0, z: 0}
--- !u!1001 &1627895894
PrefabInstance:
m_ObjectHideFlags: 0
serializedVersion: 2
m_Modification:
serializedVersion: 3
m_TransformParent: {fileID: 199785320}
m_Modifications:
- target: {fileID: 5652501251207193424, guid: e9d9216d17e7b684096c94e8c347d46f, type: 3}
propertyPath: m_Name
value: Sprite01
objectReference: {fileID: 0}
- target: {fileID: 7501110767542530711, guid: e9d9216d17e7b684096c94e8c347d46f, type: 3}
propertyPath: m_LocalPosition.x
value: 0
objectReference: {fileID: 0}
- target: {fileID: 7501110767542530711, guid: e9d9216d17e7b684096c94e8c347d46f, type: 3}
propertyPath: m_LocalPosition.y
value: 0
objectReference: {fileID: 0}
- target: {fileID: 7501110767542530711, guid: e9d9216d17e7b684096c94e8c347d46f, type: 3}
propertyPath: m_LocalPosition.z
value: 0
objectReference: {fileID: 0}
- target: {fileID: 7501110767542530711, guid: e9d9216d17e7b684096c94e8c347d46f, type: 3}
propertyPath: m_LocalRotation.w
value: 1
objectReference: {fileID: 0}
- target: {fileID: 7501110767542530711, guid: e9d9216d17e7b684096c94e8c347d46f, type: 3}
propertyPath: m_LocalRotation.x
value: 0
objectReference: {fileID: 0}
- target: {fileID: 7501110767542530711, guid: e9d9216d17e7b684096c94e8c347d46f, type: 3}
propertyPath: m_LocalRotation.y
value: 0
objectReference: {fileID: 0}
- target: {fileID: 7501110767542530711, guid: e9d9216d17e7b684096c94e8c347d46f, type: 3}
propertyPath: m_LocalRotation.z
value: 0
objectReference: {fileID: 0}
- target: {fileID: 7501110767542530711, guid: e9d9216d17e7b684096c94e8c347d46f, type: 3}
propertyPath: m_LocalEulerAnglesHint.x
value: 0
objectReference: {fileID: 0}
- target: {fileID: 7501110767542530711, guid: e9d9216d17e7b684096c94e8c347d46f, type: 3}
propertyPath: m_LocalEulerAnglesHint.y
value: 0
objectReference: {fileID: 0}
- target: {fileID: 7501110767542530711, guid: e9d9216d17e7b684096c94e8c347d46f, type: 3}
propertyPath: m_LocalEulerAnglesHint.z
value: 0
objectReference: {fileID: 0}
m_RemovedComponents: []
m_RemovedGameObjects: []
m_AddedGameObjects: []
m_AddedComponents: []
m_SourcePrefab: {fileID: 100100000, guid: e9d9216d17e7b684096c94e8c347d46f, type: 3}
--- !u!1 &1628373459 --- !u!1 &1628373459
GameObject: GameObject:
m_ObjectHideFlags: 0 m_ObjectHideFlags: 0
@@ -29564,8 +29622,8 @@ PolygonCollider2D:
- {x: -8, y: -2} - {x: -8, y: -2}
- {x: -11.5, y: -7} - {x: -11.5, y: -7}
- {x: 14, y: -7} - {x: 14, y: -7}
- {x: 24.5, y: 5}
- {x: 14, y: 5} - {x: 14, y: 5}
- {x: 24.5, y: 5}
- {x: 24.5, y: 10} - {x: 24.5, y: 10}
- {x: -8, y: 10} - {x: -8, y: 10}
m_UseDelaunayMesh: 0 m_UseDelaunayMesh: 0
@@ -29925,7 +29983,7 @@ GameObject:
m_Icon: {fileID: 0} m_Icon: {fileID: 0}
m_NavMeshLayer: 0 m_NavMeshLayer: 0
m_StaticEditorFlags: 0 m_StaticEditorFlags: 0
m_IsActive: 1 m_IsActive: 0
--- !u!61 &1865796629 --- !u!61 &1865796629
BoxCollider2D: BoxCollider2D:
m_ObjectHideFlags: 0 m_ObjectHideFlags: 0
@@ -33076,6 +33134,11 @@ Transform:
m_Children: [] m_Children: []
m_Father: {fileID: 2018245865} m_Father: {fileID: 2018245865}
m_LocalEulerAnglesHint: {x: 0, y: 0, z: 0} m_LocalEulerAnglesHint: {x: 0, y: 0, z: 0}
--- !u!4 &2035265042 stripped
Transform:
m_CorrespondingSourceObject: {fileID: 7501110767542530711, guid: e9d9216d17e7b684096c94e8c347d46f, type: 3}
m_PrefabInstance: {fileID: 1627895894}
m_PrefabAsset: {fileID: 0}
--- !u!1 &2043241451 --- !u!1 &2043241451
GameObject: GameObject:
m_ObjectHideFlags: 0 m_ObjectHideFlags: 0

View File

@@ -53,13 +53,10 @@ namespace BaseGames.Core.Assets
// ── Config ScriptableObjects ───────────────────────────────────── // ── Config ScriptableObjects ─────────────────────────────────────
public const string DataFootstepCatalog = "Config/FootstepCatalog"; public const string DataFootstepCatalog = "Config/FootstepCatalog";
/// <summary>
/// Addressable 标签常量(用于批量加载)。
/// 注意:这里是标签名称而非资产地址,不会被 AddressKeyValidator 校验。
/// </summary>
/// <summary> /// <summary>
/// Addressable Label 常量(用于批量加载与预热)。 /// Addressable Label 常量(用于批量加载与预热)。
/// 代码中引用 Label 时必须使用此处的常量,禁止硬编码字符串。 /// 代码中引用 Label 时必须使用此处的常量,禁止硬编码字符串。
/// 注意:这里是标签名称而非资产地址,不会被 AddressKeyValidator 校验。
/// 完整说明见 Docs/Standards/AddressablesLabelSpec.md。 /// 完整说明见 Docs/Standards/AddressablesLabelSpec.md。
/// </summary> /// </summary>
public static class Labels public static class Labels

View File

@@ -1,6 +1,6 @@
# Addressables Label标签命名与使用规范 # Addressables Label标签命名与使用规范
> **版本**1.1 > **版本**1.2
> **创建日期**2026-05 > **创建日期**2026-05
> **适用范围**`Assets/_Game/` 目录下所有注册到 Addressables 的资产 > **适用范围**`Assets/_Game/` 目录下所有注册到 Addressables 的资产
> **关联文档**`Standards/AssetFolderSpec.md §8`、`Scripts/Core/Assets/AddressKeys.cs`、`Scripts/Editor/Addressables/AddressableRules.cs` > **关联文档**`Standards/AssetFolderSpec.md §8`、`Scripts/Core/Assets/AddressKeys.cs`、`Scripts/Editor/Addressables/AddressableRules.cs`
@@ -261,7 +261,7 @@ await Addressables.DownloadDependenciesAsync("Preload", false);
4. 在本文档 §2 Label 清单中追加说明行 4. 在本文档 §2 Label 清单中追加说明行
5. 在本文档 §3 对应资产类型的表格中标注 5. 在本文档 §3 对应资产类型的表格中标注
6. 运行 Rule Sync菜单 BaseGames → Addressables → Rule SyncScan 验证无遗漏 6. 运行 Rule Sync菜单 BaseGames → Addressables → Rule SyncScan 验证无遗漏
7. 运行 AddressKeyValidator菜单 BaseGames → Verification → Validate Address Keys确认 7. 运行 AddressKeyValidator菜单 `BaseGames/Addressables/Validate Address Keys`)确认
``` ```
--- ---
@@ -286,7 +286,7 @@ Assets/_Game/Scripts/Editor/Addressables/AddressableRules.cs
``` ```
新建/更新资产后: 新建/更新资产后:
1. 打开 Rule Sync 窗口(菜单 BaseGamesAddressablesRule Sync 1. 打开 Rule Sync 窗口(菜单 `BaseGames/Addressables/Rule Sync`
2. 点击 [Scan All] — 扫描所有 Addressable 条目与期望规则的差异 2. 点击 [Scan All] — 扫描所有 Addressable 条目与期望规则的差异
3. 查看报告: 3. 查看报告:
- Group Mismatch — 资产在错误的分组 - Group Mismatch — 资产在错误的分组
@@ -301,7 +301,7 @@ Assets/_Game/Scripts/Editor/Addressables/AddressableRules.cs
``` ```
1. 将资产按命名前缀放置到正确目录(见 AssetFolderSpec.md §2§4 1. 将资产按命名前缀放置到正确目录(见 AssetFolderSpec.md §2§4
2. 打开 Addressable Batch Tool菜单 BaseGames → Tools → Addressable Batch Tool 2. 打开 Addressable Batch Tool菜单 `BaseGames/Addressables/Addressable Batch Tool`
3. 切换到 "② 文件夹批量" 标签,选择目标文件夹,点击 [Register Folder] 3. 切换到 "② 文件夹批量" 标签,选择目标文件夹,点击 [Register Folder]
4. 切换到 "① 同步 AddressKeys" 标签,点击 [Scan],为新注册的资产补充 AddressKeys.cs 常量 4. 切换到 "① 同步 AddressKeys" 标签,点击 [Scan],为新注册的资产补充 AddressKeys.cs 常量
5. 返回 Rule Sync 窗口执行 Scan → Fix All 统一校正 Group / Label 5. 返回 Rule Sync 窗口执行 Scan → Fix All 统一校正 Group / Label
@@ -312,6 +312,6 @@ Assets/_Game/Scripts/Editor/Addressables/AddressableRules.cs
| 工具 | 菜单路径 | 核心功能 | | 工具 | 菜单路径 | 核心功能 |
|------|---------|---------| |------|---------|---------|
| **Rule Sync** | `BaseGamesAddressablesRule Sync` | 扫描 + 修复分组/标签不合规条目;导出 CSV | | **Rule Sync** | `BaseGames/Addressables/Rule Sync` | 扫描 + 修复分组/标签不合规条目;导出 CSV |
| **Addressable Batch Tool** | `BaseGames → Tools → Addressable Batch Tool` | 三标签AddressKeys 同步 / 文件夹批量注册 / Selection 注册 | | **Addressable Batch Tool** | `BaseGames/Addressables/Addressable Batch Tool` | 三标签AddressKeys 同步 / 文件夹批量注册 / Selection 注册 |
| **Validate Address Keys** | `BaseGames → Verification → Validate Address Keys` | 验证 AddressKeys.cs 所有常量均已在 Addressables 注册,构建前自动触发 | | **Validate Address Keys** | `BaseGames/Addressables/Validate Address Keys` | 验证 AddressKeys.cs 所有常量均已在 Addressables 注册,构建前自动触发 |

View File

@@ -1,6 +1,6 @@
# 资源文件夹目录规划与管理规范 # 资源文件夹目录规划与管理规范
> **版本**1.1 > **版本**1.2
> **创建日期**2026-05 > **创建日期**2026-05
> **适用范围**`Assets/` 目录下所有非代码资源(美术、数据、预制体、场景等) > **适用范围**`Assets/` 目录下所有非代码资源(美术、数据、预制体、场景等)
> **资源管理系统**Unity Addressables禁止使用 `Resources.Load` > **资源管理系统**Unity Addressables禁止使用 `Resources.Load`
@@ -274,6 +274,7 @@ Data/
| `ENM_` | 敌人 | `ENM_E001_Stats.asset` | | `ENM_` | 敌人 | `ENM_E001_Stats.asset` |
| `WPN_` | 武器 | `WPN_SkyBlade.asset` | | `WPN_` | 武器 | `WPN_SkyBlade.asset` |
| `SKL_` | 技能/法术 | `SKL_SoulBlade.asset` | | `SKL_` | 技能/法术 | `SKL_SoulBlade.asset` |
| `SPL_` | 法术Spell | `SPL_Fireball.asset` |
| `CHM_` | 护身符 | `CHM_GhostMantis.asset` | | `CHM_` | 护身符 | `CHM_GhostMantis.asset` |
| `SHP_` | 商店 | `SHP_Inventory_Forest.asset` | | `SHP_` | 商店 | `SHP_Inventory_Forest.asset` |
| `MAP_` | 地图 | `MAP_RoomData_Forest_01.asset` | | `MAP_` | 地图 | `MAP_RoomData_Forest_01.asset` |
@@ -472,7 +473,7 @@ UI Toolkit/
| `VFX_Common` | 通用高频特效HitSpark、BloodSplat 等) | Local | 启动时预加载 | | `VFX_Common` | 通用高频特效HitSpark、BloodSplat 等) | Local | 启动时预加载 |
| `Collectibles` | 收集物 PrefabGeo、Item、HPOrb | Local | 启动时预加载 | | `Collectibles` | 收集物 PrefabGeo、Item、HPOrb | Local | 启动时预加载 |
| `Projectiles` | 抛射物 Prefab | Local | 启动时预加载 | | `Projectiles` | 抛射物 Prefab | Local | 启动时预加载 |
| `Enemies_{Region}` | 该区域的敌人 Prefab | Local | 进入区域时加载 | | `Enemies` | 所有敌人 Prefab`ENM_*` | Local | 进入区域时加载 |
| `Room_{Region}` | 该区域的关卡场景 + 区域专属资产 | Local | 进入区域时加载 | | `Room_{Region}` | 该区域的关卡场景 + 区域专属资产 | Local | 进入区域时加载 |
| `Boss_{Name}` | Boss 专属 Prefab + 场景 | Local | Boss 战开始前加载 | | `Boss_{Name}` | Boss 专属 Prefab + 场景 | Local | Boss 战开始前加载 |
| `Audio_Music` | BGM 音频FMOD bank 引用) | Remote可选| 按需流式加载 | | `Audio_Music` | BGM 音频FMOD bank 引用) | Remote可选| 按需流式加载 |
@@ -538,11 +539,11 @@ Config/DifficultyEasy
``` ```
1. 在 Project 中创建/导入资产 1. 在 Project 中创建/导入资产
2. 在 AddressKeys.cs 中添加对应 const 字符串 2. 在 AddressKeys.cs 中添加对应 const 字符串
3. 在 AddressableBatchTool菜单 BaseGames → Tools → Addressable Batch Tool 3. 在 AddressableBatchTool菜单 `BaseGames/Addressables/Addressable Batch Tool`)中:
a. 切换到 "① 同步 AddressKeys" 标签 a. 切换到 "① 同步 AddressKeys" 标签
b. 点击 "Scan" 找到未注册的 Key b. 点击 "Scan" 找到未注册的 Key
c. 选择目标 Group点击 "Register" 完成注册 c. 选择目标 Group点击 "Register" 完成注册
4. 运行 AddressKeyValidator菜单 BaseGames → Verification → Validate Address Keys 4. 运行 AddressKeyValidator菜单 `BaseGames/Addressables/Validate Address Keys`
确认无 Missing / Mismatch 警告 确认无 Missing / Mismatch 警告
5. 提交 AddressKeys.cs 和 AddressableAssetSettings.asset 的修改 5. 提交 AddressKeys.cs 和 AddressableAssetSettings.asset 的修改
``` ```
@@ -683,7 +684,7 @@ var (prefab, _) = await AssetLoader.LoadAsync<GameObject>(AddressKeys.PrefabPlay
``` ```
1. 在 _Game/Art/Characters/Player/{FormID}/Animations/ 下创建技能动画片段(.anim 1. 在 _Game/Art/Characters/Player/{FormID}/Animations/ 下创建技能动画片段(.anim
2. 在 Skill Editor菜单 BaseGames/Data/Skill Editor左栏 [New] 创建 SKL_{SkillID}_Data.asset 2. 在 Skill Editor菜单 BaseGames/Data/Skill Editor左栏 [New] 创建 SKL_{SkillID}_Data.asset
- 路径_Game/Data/Player/Skills/SKL_{SkillID}_Data.asset - 路径:`_Game/Data/Progression/Skills/SKL_{SkillID}_Data.asset`
- 命名SKL_{SkillID}示例SKL_DashSlash、SKL_SpiritWave - 命名SKL_{SkillID}示例SKL_DashSlash、SKL_SpiritWave
3. 使用 Skill HitBox Wizard菜单 BaseGames/Create/Skill HitBox Prefab生成 3. 使用 Skill HitBox Wizard菜单 BaseGames/Create/Skill HitBox Prefab生成
_Game/Prefabs/Skills/SKL_{SkillID}_HitBox.prefab支持多段伤害配置 _Game/Prefabs/Skills/SKL_{SkillID}_HitBox.prefab支持多段伤害配置
@@ -693,10 +694,11 @@ var (prefab, _) = await AssetLoader.LoadAsync<GameObject>(AddressKeys.PrefabPlay
### 10.4 新增护身符Charm ### 10.4 新增护身符Charm
> **推荐工具**:直接在 Project 窗口 Create → 对应 CharmSO然后通过 CharmSOEditorCustom Inspector配置效果类型与参数 > **推荐工具**`BaseGames → Data → Character Wizard`(切换到 Charm 标签)或直接在 Project 窗口 右键 → Create,使用 `CharmSOEditor`Custom Inspector配置**必须确保路径为 `_Game/Data/Progression/Charms/`,命名为 `CHM_{Name}.asset`**;若护身符类型较多,建议在 §12 中增加专属 Charm Editor 入口以强制规范
``` ```
1. 在 _Game/Data/Progression/Charms/ 下创建 CHM_{Name}.assetCharmSO 1. 使用 Character Wizard菜单 BaseGames/Data/Character Wizard → Charm 标签)创建 CHM_{Name}.asset
- 路径_Game/Data/Progression/Charms/CHM_{Name}.asset
- 命名CHM_{Name}示例CHM_SoulReaper、CHM_IronSkin - 命名CHM_{Name}示例CHM_SoulReaper、CHM_IronSkin
2. 在 Inspector 中通过 CharmSOEditor 下拉选择效果类型并配置参数 2. 在 Inspector 中通过 CharmSOEditor 下拉选择效果类型并配置参数
3. 在 AddressKeys.cs 中添加 DataCharm{Name} 常量 3. 在 AddressKeys.cs 中添加 DataCharm{Name} 常量