# 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# 开发

## 启动流程

游戏启动路径：`Assets/Launcher.unity` → `ProcedureMenu` → `Menu.unity` → `Main.unity`。流程切换通过 `ChangeState<T>` 驱动。

## 架构概览

### 目录结构
```
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`。详见 `docs/TagSystemDesign.md` 和 `docs/TagSystemRoadmap.md`。

### 商店与 RepoForm

`ShopNode` 只承载玩家购买组件的逻辑；`RepoForm` 负责出售功能（commit `2e54acb`）。两者职责分离，不得交叉。

## 测试

测试位于 `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` 前缀）