# 01 · 项目结构与规范

> **作用**：定义文件夹布局、Assembly Definition 清单、命名规范、ScriptableObject 资产路径、代码风格约束。  
> **所有程序员必读**，开始任何模块开发前先阅读本文档。

---

## 目录

1. [文件夹布局](#1-文件夹布局)
2. [Assembly Definitions（asmdef）](#2-assembly-definitions)
3. [命名规范](#3-命名规范)
4. [ScriptableObject 资产组织](#4-scriptableobject-资产组织)
5. [Addressables 资产组织](#5-addressables-资产组织)
6. [代码风格约束](#6-代码风格约束)
7. [Prefab 组织规范](#7-prefab-组织规范)
8. [场景组织规范](#8-场景组织规范)

---

## 1. 文件夹布局

```
Assets/
├── Scripts/                    ← 所有游戏代码（按模块分文件夹）
│   ├── Core/                   BaseGames.Core + BaseGames.Core.Events
│   │   ├── Events/             SO 事件频道类型
│   │   └── Save/               SaveManager + ISaveStorage + SaveData
│   ├── Input/                  BaseGames.Input
│   ├── Camera/                 BaseGames.Camera
│   ├── Player/                 BaseGames.Player
│   │   └── States/             BaseGames.Player.States
│   ├── Combat/                 BaseGames.Combat
│   │   └── StatusEffects/      BaseGames.Combat.StatusEffects
│   ├── Parry/                  BaseGames.Parry
│   ├── Enemies/                BaseGames.Enemies
│   │   ├── AI/                 BaseGames.Enemies.AI（Behavior Designer Tasks）
│   │   ├── Boss/
│   │   │   └── Patterns/       BaseGames.Enemies.Boss.Patterns
│   │   └── Navigation/         BaseGames.Enemies.Navigation
│   ├── Feedback/               BaseGames.Feedback
│   ├── World/                  BaseGames.World
│   │   ├── Map/                BaseGames.World.Map
│   │   └── Shop/               BaseGames.World.Shop
│   ├── UI/                     BaseGames.UI
│   ├── Audio/                  BaseGames.Audio
│   ├── Progression/            BaseGames.Progression
│   ├── Dialogue/               BaseGames.Dialogue
│   ├── Equipment/              BaseGames.Equipment
│   ├── Cutscene/               BaseGames.Cutscene
│   ├── Animation/              BaseGames.Animation
│   ├── Spells/                 BaseGames.Spells
│   ├── Localization/           BaseGames.Localization
│   ├── Tutorial/               BaseGames.Tutorial
│   ├── Platform/               BaseGames.Platform
│   └── Editor/                 BaseGames.Editor（Editor Only）
│
├── Data/                       ← ScriptableObject 资产（按模块分文件夹）
│   ├── Events/                 所有事件频道 SO
│   ├── Player/                 PlayerStatsSO、PlayerMovementConfigSO 等
│   ├── Combat/                 WeaponSO、ProjectileConfigSO 等
│   ├── Enemies/                EnemyStatsSO、AttackPatternSO 等
│   ├── Progression/            SkillSO、CharmSO、AbilityConfigSO 等
│   ├── Audio/                  AudioCueSO、BGMPlaylistSO 等
│   ├── World/                  MapRoomDataSO、ShopInventorySO 等
│   ├── UI/                     UIConfigSO 等
│   └── Settings/               GlobalSettingsSO
│
├── Prefabs/                    ← 预制体
│   ├── Player/
│   ├── Enemies/
│   ├── World/
│   ├── UI/
│   ├── Combat/                 HitBox、HurtBox、Projectile 等
│   ├── Effects/                VFX Prefabs
│   └── Persistent/             Persistent 场景专用 Prefabs
│
├── Scenes/
│   ├── Persistent.unity        常驻场景
│   ├── MainMenu.unity
│   ├── Room_*/                 各关卡房间场景
│   └── Boss_*/                 Boss 战场景
│
├── Art/                        美术资源（不在此文档范围）
├── Audio/                      音频资源（FMOD 项目）
└── StreamingAssets/            FMOD 音频包等
```

---

## 2. Assembly Definitions

所有 asmdef 均位于对应的 `Scripts/` 子文件夹下，文件名与程序集名称一致。

### 依赖层次（底层 → 上层）

```
BaseGames.Core.Events
    └─→ BaseGames.Core
            ├─→ BaseGames.Input
            ├─→ BaseGames.Camera
            ├─→ BaseGames.Audio
            ├─→ BaseGames.Localization
            ├─→ BaseGames.Platform
            ├─→ BaseGames.World
            │       └─→ BaseGames.World.Map
            │       └─→ BaseGames.World.Shop
            └─→ BaseGames.Combat
                    ├─→ BaseGames.Parry
                    ├─→ BaseGames.Combat.StatusEffects
                    └─→ BaseGames.Player
                            ├─→ BaseGames.Player.States
                            ├─→ BaseGames.Progression
                            ├─→ BaseGames.Equipment
                            ├─→ BaseGames.Spells
                            └─→ BaseGames.Enemies
                                    ├─→ BaseGames.Enemies.AI
                                    ├─→ BaseGames.Enemies.Navigation
                                    └─→ BaseGames.Enemies.Boss.Patterns

BaseGames.Feedback（依赖：Core.Events、Player、Enemies）
BaseGames.Animation（依赖：Core.Events、Player）
BaseGames.UI（依赖：Core.Events、Core、Progression）
BaseGames.Dialogue（依赖：Core.Events、UI）
BaseGames.Cutscene（依赖：Core.Events、UI、Dialogue）
BaseGames.Tutorial（依赖：Core.Events、Progression）
BaseGames.Editor（Editor Only，依赖全部运行时程序集）
```

### asmdef 文件清单

| 文件名 | 程序集名称 | 编辑器 | 关键外部引用 |
|--------|----------|--------|------------|
| `BaseGames.Core.Events.asmdef` | `BaseGames.Core.Events` | ✗ | — |
| `BaseGames.Core.asmdef` | `BaseGames.Core` | ✗ | `Newtonsoft.Json` |
| `BaseGames.Input.asmdef` | `BaseGames.Input` | ✗ | `Unity.InputSystem` |
| `BaseGames.Camera.asmdef` | `BaseGames.Camera` | ✗ | `Cinemachine` |
| `BaseGames.Audio.asmdef` | `BaseGames.Audio` | ✗ | `FMODUnity`（可选） |
| `BaseGames.Localization.asmdef` | `BaseGames.Localization` | ✗ | `Unity.Localization` |
| `BaseGames.Platform.asmdef` | `BaseGames.Platform` | ✗ | `Steamworks.NET`（条件编译） |
| `BaseGames.Combat.asmdef` | `BaseGames.Combat` | ✗ | — |
| `BaseGames.Combat.StatusEffects.asmdef` | `BaseGames.Combat.StatusEffects` | ✗ | — |
| `BaseGames.Parry.asmdef` | `BaseGames.Parry` | ✗ | — |
| `BaseGames.World.asmdef` | `BaseGames.World` | ✗ | — |
| `BaseGames.World.Map.asmdef` | `BaseGames.World.Map` | ✗ | — |
| `BaseGames.World.Shop.asmdef` | `BaseGames.World.Shop` | ✗ | — |
| `BaseGames.Player.asmdef` | `BaseGames.Player` | ✗ | `Kybernetik.Animancer` |
| `BaseGames.Player.States.asmdef` | `BaseGames.Player.States` | ✗ | `Kybernetik.Animancer` |
| `BaseGames.Progression.asmdef` | `BaseGames.Progression` | ✗ | — |
| `BaseGames.Equipment.asmdef` | `BaseGames.Equipment` | ✗ | — |
| `BaseGames.Spells.asmdef` | `BaseGames.Spells` | ✗ | — |
| `BaseGames.Enemies.asmdef` | `BaseGames.Enemies` | ✗ | `Kybernetik.Animancer` |
| `BaseGames.Enemies.AI.asmdef` | `BaseGames.Enemies.AI` | ✗ | `BehaviorDesigner.Runtime` |
| `BaseGames.Enemies.Navigation.asmdef` | `BaseGames.Enemies.Navigation` | ✗ | `PathBerserker2d` |
| `BaseGames.Enemies.Boss.Patterns.asmdef` | `BaseGames.Enemies.Boss.Patterns` | ✗ | — |
| `BaseGames.Feedback.asmdef` | `BaseGames.Feedback` | ✗ | `MoreMountains.Tools`, `MoreMountains.Feedbacks` |
| `BaseGames.Animation.asmdef` | `BaseGames.Animation` | ✗ | `Kybernetik.Animancer` |
| `BaseGames.UI.asmdef` | `BaseGames.UI` | ✗ | — |
| `BaseGames.Dialogue.asmdef` | `BaseGames.Dialogue` | ✗ | `Unity.Localization` |
| `BaseGames.Cutscene.asmdef` | `BaseGames.Cutscene` | ✗ | `Unity.Timeline` |
| `BaseGames.Tutorial.asmdef` | `BaseGames.Tutorial` | ✗ | — |
| `BaseGames.Editor.asmdef` | `BaseGames.Editor` | ✓ | 所有运行时程序集 |

---

## 3. 命名规范

### 类型名称

| 类型 | 后缀 / 规则 | 示例 |
|------|-----------|------|
| MonoBehaviour 组件 | 无后缀 | `PlayerController`、`EnemyBase` |
| ScriptableObject | `SO` 后缀 | `PlayerStatsSO`、`ShopItemSO` |
| 事件频道 SO | `EventChannelSO` 后缀 | `VoidEventChannelSO`、`IntEventChannelSO` |
| 接口 | `I` 前缀 | `ISaveable`、`IInteractable`、`ICharmEffect` |
| 枚举 | PascalCase 无后缀 | `GameState`、`AbilityType`、`DamageType` |
| 泛型基类 | `Base` 后缀 | `PlayerStateBase`、`EnemyStateBase` |
| Editor 扩展 | `Editor` 后缀 | `PlayerControllerEditor`、`EnemyBaseEditor` |
| 协程方法 | `Coroutine` 后缀 | `LoadSceneCoroutine()`、`DeathSequenceCoroutine()` |

### 字段命名

```csharp
// 私有序列化字段：_camelCase（下划线前缀）
[SerializeField] private PlayerMovementConfigSO _movementConfig;

// 私有非序列化字段：_camelCase
private float _currentSpeed;

// 属性：PascalCase
public float CurrentSpeed => _currentSpeed;

// 常量：ALL_CAPS
private const float MAX_SPEED = 10f;

// 局部变量：camelCase
float deltaSpeed = targetSpeed - _currentSpeed;
```

### 文件命名

| 类型 | 规则 | 示例 |
|------|------|------|
| C# 脚本 | 与类名完全一致 | `PlayerController.cs` |
| SO 资产 | `[SystemPrefix]_[Name]` | `PLY_Stats_Default.asset`、`EVT_PlayerDied.asset` |
| Prefab | `[SystemPrefix]_[Name]` | `PLY_Player.prefab`、`ENM_GruntWarrior.prefab` |
| 场景 | `Room_{Region}_{Index:D2}` | `Room_Forest_01.unity` |
| asmdef | 与程序集名称一致 | `BaseGames.Player.asmdef` |

### SO 资产前缀表

| 前缀 | 系统 |
|------|------|
| `EVT_` | 事件频道 |
| `PLY_` | 玩家配置 |
| `CMB_` | 战斗配置 |
| `ENM_` | 敌人配置 |
| `WPN_` | 武器配置 |
| `SKL_` | 技能 / 法术 |
| `CHM_` | 护身符 |
| `SHP_` | 商店 |
| `MAP_` | 地图 |
| `AUD_` | 音频 |
| `UI_` | UI 配置 |
| `SET_` | 设置 |

---

## 4. ScriptableObject 资产组织

### 目录结构（`Assets/Data/`）

```
Assets/Data/
├── Events/
│   ├── Core/        EVT_GameStateChanged.asset, EVT_SceneLoadRequest.asset …
│   ├── Player/      EVT_PlayerDied.asset, EVT_HPChanged.asset …
│   ├── Combat/      EVT_DamageDealt.asset …
│   ├── World/       EVT_RoomTransition.asset …
│   └── UI/          EVT_ShowPanel.asset …
├── Player/
│   ├── PLY_Stats_Default.asset
│   ├── PLY_MovementConfig.asset
│   ├── PLY_AnimConfig.asset
│   └── PLY_FormConfig.asset
├── Combat/
│   ├── CMB_WeaponBase.asset
│   └── CMB_ProjectileConfig_*.asset
├── Enemies/
│   ├── ENM_Stats_*.asset
│   └── ENM_AttackPattern_*.asset
├── Progression/
│   ├── SKL_SoulSpell_*.asset
│   ├── CHM_Charm_*.asset
│   └── ABL_AbilityConfig_*.asset
├── Audio/
│   ├── AUD_BGMPlaylist_*.asset
│   └── AUD_SFXCue_*.asset
├── World/
│   ├── MAP_RoomData_*.asset
│   └── SHP_ShopInventory_*.asset
└── Settings/
    └── SET_GlobalSettings.asset
```

---

## 5. Addressables 资产组织

### AddressKeys 静态类（路径：`Scripts/Core/AddressKeys.cs`）

```csharp
// 路径: Assets/Scripts/Core/Assets/AddressKeys.cs
// ⚠️ 命名规范：驼峰式，无下划线分隔（`PrefabPlayer` 不是 `Pfx_Player_Main`）
// 地址值与 Addressables Groups 窗口 Address 列保持完全一致
namespace BaseGames.Core
{
    public static class AddressKeys
    {
        // ── Scenes ──────────────────────────────────────────────
        public const string ScenePersistent    = "Scene_Persistent";
        public const string SceneMainMenu      = "Scene_MainMenu";
        public const string SceneRoomPrefix    = "Room_";
        public const string SceneBossPrefix    = "Boss_";

        // ── Player ──────────────────────────────────────────────
        public const string PrefabPlayer        = "PLY_Player";

        // ── UI ──────────────────────────────────────────────────
        public const string PrefabUIHUD          = "UI_HUD";
        public const string PrefabUIPauseMenu    = "UI_PauseMenu";
        public const string PrefabUIDeathScreen  = "UI_DeathScreen";
        public const string PrefabUILoadingScreen = "UI_LoadingScreen";

        // ── VFX ─────────────────────────────────────────────────
        public const string PrefabVFXHitSpark    = "VFX_HitSpark";
        public const string PrefabVFXDeathBurst  = "VFX_DeathBurst";
        public const string PrefabVFXParryFlash  = "VFX_ParryFlash";

        // ── Audio ────────────────────────────────────────────────
        public const string PrefabAudioMasterMixer = "MasterMixer";

        // ── Labels（用于 Addressables.LoadAssetsAsync 批量加载）───
        public const string LabelEnemy    = "Enemy";
        public const string LabelPoolable = "Poolable";
        public const string LabelBGM      = "BGM";
        public const string LabelCharms   = "Charms";
    }
}
```

> **完整 `AddressKeys` 定义见 `13_AssetPoolModule.md §2`**，本节仅展示命名约定示例。

### Addressables 分组策略

| 组名 | 内容 | 加载时机 |
|------|------|---------|
| `DefaultLocalGroup` | 常驻资源（GameManager Prefab、HUD 等） | 启动时预加载 |
| `Room_{Region}` | 各区域房间所有资产 | 进入区域时加载 |
| `Boss_{Name}` | Boss 战专属资产 | Boss 战开始前加载 |
| `UI` | 所有 UI Prefab | 启动时预加载 |
| `VFX_Common` | 通用特效 | 启动时预加载 |
| `Audio_Music` | BGM（FMOD 包） | 按需加载 |

---

## 6. 代码风格约束

### 禁止模式

```csharp
// ❌ 禁止：FindObjectOfType
var player = FindObjectOfType<PlayerController>();

// ❌ 禁止：跨 GameObject GetComponent（组件不在同一 Prefab 内）
var stats = otherGO.GetComponent<PlayerStats>();

// ❌ 禁止：静态单例暴露子系统
public static AudioManager Instance { get; private set; }  // 禁止全局访问

// ❌ 禁止：Resources.Load
var sprite = Resources.Load<Sprite>("Enemies/goblin");

// ❌ 禁止：跨系统 Inspector 序列化引用
[SerializeField] private PlayerController _player;  // 在 EnemyBase 中引用玩家 ❌

// ❌ 禁止：硬编码 Addressable 字符串
var handle = Addressables.LoadAsset<GameObject>("PLY_Player");  // ❌ 用 AddressKeys 常量
```

### 推荐模式

```csharp
// ✅ SO 事件频道（跨模块通信）
[SerializeField] private VoidEventChannelSO _onPlayerDied;
private void OnEnable()  => _onPlayerDied.OnEventRaised += HandlePlayerDied;
private void OnDisable() => _onPlayerDied.OnEventRaised -= HandlePlayerDied;

// ✅ Inspector 序列化（同 Prefab 内）
[SerializeField] private PlayerMovement _movement;   // 在 PlayerController 中 ✅

// ✅ Addressables 加载
Addressables.InstantiateAsync(AddressKeys.PrefabPlayer).Completed += OnPlayerLoaded;

// ✅ 对象池
GlobalObjectPool.Instance.Spawn<HitEffect>(AddressKeys.PrefabVFXHitSpark, position, rotation);
```

### OnEnable / OnDisable 规则

每个订阅 SO 事件频道的组件**必须**在 `OnDisable` 中取消订阅，防止内存泄漏：

```csharp
private void OnEnable()
{
    _channel.OnEventRaised += HandleEvent;
}

private void OnDisable()
{
    _channel.OnEventRaised -= HandleEvent;
}
```

---

## 7. Prefab 组织规范

### Player Prefab 层级

```
[PLY_Player]                    ← PlayerController（协调器）
├── PlayerMovement              ← Rigidbody2D 封装
├── PlayerStats                 ← 属性容器
├── PlayerCombat                ← 攻击逻辑
├── FormController              ← 形态管理
├── WeaponManager               ← 武器切换
├── SkillManager                ← 技能执行
├── SpringSystem                ← 灵泉管理
├── ParrySystem                 ← 弹反逻辑
├── AnimancerComponent          ← Animancer 入口
├── PlayerFeedback              ← MMF_Player
├── HurtBox                     ← Composite Collider 受击区域
├── HitBox_Ground               ← BoxCollider2D 地面攻击判定
├── HitBox_Up                   ← BoxCollider2D 上劈判定
├── HitBox_Down                 ← BoxCollider2D 下劈判定
├── HitBox_Air                  ← BoxCollider2D 空中判定
└── SpriteRenderer
```

### Enemy Prefab 通用层级

```
[ENM_{EnemyName}]               ← EnemyBase（协调器）+ BehaviorTree
├── EnemyMovement               ← PathBerserker2d EnemyNavAgent 封装
├── EnemyStats                  ← HP/攻击等属性
├── EnemyCombat                 ← HitBox 管理
├── AnimancerComponent          ← 动画
├── EnemyFeedback               ← MMF_Player
├── HurtBox                     ← 受击区域
└── HitBox_{N}                  ← 各攻击 HitBox
```

---

## 8. 场景组织规范

### 场景文件命名

```
Persistent                   ← 常驻场景（GameManager、AudioManager 等单例）
MainMenu                     ← 主菜单
Room_{Region}_{Index:D2}     ← 关卡房间  例: Room_Forest_01
Boss_{Region}                ← Boss 战  例: Boss_Forest
Hub_Town                     ← 区域枢纽  例: Hub_RestCamp
```

### 房间场景层级结构

```
Scene: Room_{Region}_{Index}
├── [Level]
│   ├── Tilemap_Ground
│   ├── Tilemap_Background
│   ├── Tilemap_Foreground
│   ├── Tilemap_OneWay
│   └── Tilemap_Destructible
├── [NavMesh]
│   ├── NavSurface
│   └── NavLink_{N}
├── [Enemies]
│   └── Enemy_*（Prefab 实例）
├── [World]
│   ├── RoomTransition_{Direction}
│   ├── SavePoint（可选）
│   └── Collectible_*
├── [Camera]
│   ├── CinemachineVirtualCamera
│   └── CameraConfiner（PolygonCollider2D）
└── [Lighting]
    └── GlobalLight2D
```

### Persistent 场景组织

```
Scene: Persistent
├── GameManager              ← DontDestroyOnLoad 协调器
├── AudioManager             ← FMOD 封装
├── ObjectPoolManager        ← 对象池
├── SettingsManager          ← 设置管理
└── InputReader              ← InputReaderSO（持久化）
```