8.4 KiB

Raw Blame History

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 前缀）

8.4 KiB Raw Blame History Unescape Escape