226 lines
8.4 KiB
Markdown
226 lines
8.4 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## 项目概述
|
||
|
||
几何塔防 (Geometry TD) - 塔防肉鸽游戏。使用 Unity 引擎，基于 GameFramework 游戏框架构建。
|
||
|
||
## 构建与开发
|
||
|
||
- **打开项目**: 使用 Unity Hub 加载 `GeometryTD` 目录
|
||
- **运行**: Unity Editor 中点击 Play 按钮（无 CLI 方式）
|
||
- **构建**: `File > Build Settings` 选择目标平台
|
||
- **IDE**: 打开 `GeometryTD.sln` 或 `Assembly-CSharp.csproj` 进行 C# 开发
|
||
|
||
## 启动流程
|
||
|
||
`GameEntry` 是游戏主 bootstrap 类。流程切换通过 `ChangeState<T>` 驱动，数据传递使用 `procedureOwner.SetData`。
|
||
|
||
游戏启动路径：`Assets/Launcher.unity` → `ProcedureMenu` → `Menu.unity` → `Main.unity`
|
||
|
||
## 架构概览
|
||
|
||
### 目录结构
|
||
```
|
||
Assets/
|
||
├── GameFramework/ # 游戏框架（来自 gameframework.cn）
|
||
├── GameMain/
|
||
│ ├── Scripts/ # 游戏逻辑代码
|
||
│ │ ├── Base/ # GameEntry 等基础组件
|
||
│ │ ├── Components/ # 组件（InputComponent, TowerController 等）
|
||
│ │ ├── CustomComponent/# 自定义组件（UIRouterComponent 等）
|
||
│ │ ├── DataTable/ # 数据表（DR* 前缀，如 DREnemy, DRTag）
|
||
│ │ ├── Definition/ # 枚举、Struct 定义
|
||
│ │ ├── Entity/ # 实体系统（EntityBase, EntityData, EntityLogic）
|
||
│ │ ├── Event/ # 事件定义
|
||
│ │ ├── Factory/ # 工厂类
|
||
│ │ ├── Procedure/ # 流程状态机（FSM）
|
||
│ │ ├── Scene/ # 场景相关
|
||
│ │ ├── UI/ # UI 系统
|
||
│ │ └── Utility/ # 工具类
|
||
│ ├── Scenes/ # Unity 场景（Menu.unity, Main.unity）
|
||
│ ├── DataTables/ # 数据表资源
|
||
│ └── Configs/ # 配置文件
|
||
└── Tests/ # 编辑器模式测试
|
||
```
|
||
|
||
### UI 架构 (MV* + UseCase 模式)
|
||
|
||
UI 采用 Context/Controller/UseCase/View 分层：
|
||
|
||
```
|
||
UIFormController (接口)
|
||
└── UIFormControllerBase<TContext> (泛型基类)
|
||
└── SpecificController (如 ShopFormController)
|
||
|
||
IUIUseCase (用例接口)
|
||
└── SpecificUseCase (如 ShopFormUseCase)
|
||
|
||
UIContext (UI 状态)
|
||
└── SpecificContext (如 ShopFormContext)
|
||
|
||
View (MonoBehaviour)
|
||
└── SpecificView (如 ShopForm)
|
||
```
|
||
|
||
- **Controller**: 处理 UI 交互逻辑，实现 `IUIFormController`
|
||
- **UseCase**: 封装业务逻辑，实现 `IUIUseCase`
|
||
- **Context**: UI 状态数据，传递给 Controller
|
||
- **View**: Unity MonoBehaviour，处理 UI 表现
|
||
|
||
### 实体系统 (Entity System)
|
||
|
||
基于 GameFramework 的实体系统：
|
||
|
||
```
|
||
EntityLogic (GameFramework)
|
||
└── EntityBase
|
||
├── Player
|
||
├── EnemyEntity
|
||
├── TowerEntity
|
||
└── BulletEntity
|
||
|
||
EntityData (数据对象)
|
||
└── EntityDataBase
|
||
├── PlayerData
|
||
├── EnemyData
|
||
└── TowerData
|
||
```
|
||
|
||
### 流程系统 (Procedure/FSM)
|
||
|
||
游戏流程使用状态机管理：
|
||
|
||
```
|
||
ProcedureBase
|
||
├── ProcedureMenu # 菜单流程
|
||
├── ProcedureChangeScene # 场景切换
|
||
└── ProcedureMain # 主游戏流程（可能存在）
|
||
```
|
||
|
||
状态转换通过 `ChangeState<T>` 触发，数据传递使用 `procedureOwner.SetData`。
|
||
|
||
### 组件系统 (Components)
|
||
|
||
塔防组件系统用于组装防御塔：
|
||
|
||
```
|
||
BasicBaseComp # 底座组件
|
||
BasicBearingComp # 轴承组件
|
||
BasicMuzzleComp # 枪口组件
|
||
ShooterMuzzleComp
|
||
ShooterBullet
|
||
MovementComponent
|
||
InputComponent
|
||
```
|
||
|
||
### 数据表 (DataTable)
|
||
|
||
数据驱动的设计，数据表类以 `DR` 前缀：
|
||
|
||
```
|
||
DREnemy, DRTag, DRLevel, DRScene, DRShopPrice,
|
||
DROutGameDropPool, DRTagConfig, DRRarityTagBudget
|
||
```
|
||
|
||
数据表资源在 `Assets/GameMain/DataTables/`，代码在 `Assets/GameMain/Scripts/DataTable/`。开发时编辑 `数据表/` 目录下的数据表，导出后同步到 `Assets/GameMain/DataTables/`。
|
||
|
||
### 标签系统 (Tag System)
|
||
|
||
组件产出（Tag 生成/掉落/奖励候选）由 `InventoryGenerationComponent` 统一运行时入口，编排 `DropPoolRoller`、`RewardCandidateBuilder`、`OutGameDropRuleService`。
|
||
|
||
**正式首发 7 Tag：** `Fire`、`Ice`、`Crit`、`Execution`、`Shatter`、`Inferno`、`AbsoluteZero`
|
||
|
||
**明确后移 5 Tag（仅占位配置，未生效）：** `BurnSpread`、`IgniteBurst`、`FreezeMask`、`Pierce`、`Overpenetrate`
|
||
|
||
**运行时规则：**
|
||
- Tag 在组件实例创建时随机；组塔阶段只汇总，不重新随机
|
||
- 重复 Tag 不丢弃，组塔时转为塔级 `Stack`
|
||
- 战斗载荷保存塔级 `TagRuntimeData[]`
|
||
|
||
详见 `docs/TagSystemDesign.md`。
|
||
|
||
### 商店与 RepoForm
|
||
|
||
`ShopNode` 只承载玩家购买组件的逻辑；`RepoForm` 负责出售功能（commit `2e54acb`）。两者职责分离，不得交叉。
|
||
|
||
### 战斗节点系统 (CombatNode)
|
||
|
||
`CombatNodeComponent` 是战斗域的入口门面（Facade），不持有战斗内资源真值。核心架构：
|
||
|
||
```
|
||
CombatNodeComponent（入口）
|
||
└── CombatScheduler（状态机管理器）
|
||
├── CombatLoadingState
|
||
├── CombatRunningPhaseState
|
||
├── CombatWaitingForPhaseEndState
|
||
├── CombatSettlementState
|
||
├── CombatRewardSelectionState
|
||
├── CombatFinishFormState
|
||
├── CombatWaitingForReturnState
|
||
└── CombatFailedState
|
||
|
||
CombatScheduler 持有：
|
||
├── CombatRunResourceStore # Coin/Gold/BaseHp/背包快照 唯一真值来源
|
||
├── EnemyManager # 敌人域 Facade
|
||
├── PhaseLoopRuntime # Phase 运行时与结束标记
|
||
└── InventoryGenerationComponent # 组件产出统一入口
|
||
```
|
||
|
||
**核心不变量（必须保持）：**
|
||
- `CombatScheduler` 只做状态机管理与共享运行时收口，不继续吸收具体业务细节
|
||
- 状态切换只能通过 `CombatScheduler.ChangeState(...)` 完成
|
||
- 敌人事件处理入口不直接切状态，状态只能在自己的 `OnUpdate` 中决定迁移
|
||
- `MapEntity` 通过 `MapData + Event` 获取战斗上下文，不反查 Combat 域内部运行时
|
||
- 组件产出规则以 `InventoryGenerationComponent` 为统一运行时入口
|
||
|
||
详见 `docs/CombatNodeArchitecture.md`。
|
||
|
||
## 测试
|
||
|
||
测试位于 `Assets/Tests/EditMode/` 目录下，使用 Unity Test Framework 运行。在 Unity Editor 中通过 `Window > General > Test Runner` 执行。运行单个测试：选中目标测试，点击 `Run Selected`。
|
||
|
||
## 编码规范
|
||
|
||
- **缩进**: 4 空格 + Allman 大括号风格
|
||
- **命名**: 类型/方法/公开成员 `PascalCase`，局部变量/参数 `camelCase`
|
||
- **命名空间**: `GeometryTD.*` 按功能区域划分
|
||
- **断言优先**: 使用 `Debug.Assert` 而非静默忽略错误
|
||
|
||
详见 `AGENTS.md` 中的完整编码原则。
|
||
|
||
## 关键设计文档
|
||
|
||
- `docs/CombatNodeArchitecture.md` - CombatNode 战斗系统架构规范（含命名后缀词典）
|
||
- `docs/TagSystemDesign.md` - 标签系统设计
|
||
- `docs/MapEntityArchitecture.md` - 地图实体架构
|
||
- `design/gdd/systems-index.md` - 核心系统索引与优先级
|
||
|
||
## 命名后缀规范
|
||
|
||
命名后缀具有严格语义约束：
|
||
|
||
| 后缀 | 用途 | 示例 |
|
||
|------|------|------|
|
||
| `Scheduler` | 状态机边界/阶段推进总控 | `CombatScheduler` |
|
||
| `Manager` | 子域 Facade/聚合入口 | `EnemyManager` |
|
||
| `Coordinator` | 跨状态/跨服务的流程编排 | `CombatSchedulerCoordinator` |
|
||
| `Service` | 聚焦业务行为 | `OutGameDropRuleService` |
|
||
| `Calculator` | 纯计算与结果组装 | `CombatSettlementCalculator` |
|
||
| `Session` | 一次生命周期对象 | `CombatLoadSession` |
|
||
| `Bridge` | 框架边界适配器 | `CombatEventBridge` |
|
||
| `Runtime` | 运行时可变状态承载 | `PhaseLoopRuntime` |
|
||
| `Context` | 被动数据包/共享上下文 | `CombatSettlementContext` |
|
||
| `Result` | 动作输出/结算产出 | `DropResult` |
|
||
| `Flags` | 布尔控制项聚合 | `CombatFlowFlags` |
|
||
| `Resolver` | 映射/查找/判定/解析 | `EnemySpawnPathResolver` |
|
||
| `Tracker` | 跟踪运行中实体或事实真值 | `EnemyLifecycleTracker` |
|
||
| `Port` | 受限宿主接口 | `ICombatNodePort` |
|
||
|
||
## 数据工作流
|
||
|
||
- 开发时编辑 `数据表/` 目录下的数据表
|
||
- 导出后同步到 `Assets/GameMain/DataTables/`
|
||
- 数据表代码在 `Assets/GameMain/Scripts/DataTable/`（`DR` 前缀）
|