geometry-tower-defense-base/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build Commands

This is a Unity project that cannot build standalone outside of Unity Editor. The .sln references UnityEngine and UnityGameFramework which are only available in the Unity Editor environment. Use Unity's build system instead.

Architecture

Three-Layer Structure (per docs/LayeredArchitectureDesign.md)

• L0 (Domain): Pure C# business logic. References GameFramework.dll (pure C#, no Unity dependency). Contains enums, constants, data structures, CombatNode domain, PlayerInventory, InventoryGeneration, UI use cases.
• L1 (Infrastructure): Glue layer bridging L0 and Unity. Implements GameFramework Unity adapters (Resource/Scene/Entity/UI/Sound), implements L0 interfaces, holds L0 service instances, manages Unity lifecycle.
• L2 (Presentation): Unity MonoBehaviour classes, UGuiForm implementations, Entity Logic (Player, Enemy, Tower).

GameFramework.dll Modules Usable in L0

GameFramework.dll is pure C# and provides infrastructure usable directly in L0:

Module	L0 Usage
Event	GameFramework.Event.EventManager - custom args inherit GameEventArgs
ObjectPool	ObjectPoolManager - entities inherit ObjectBase
Fsm	FsmManager - states inherit FsmState<T>
ReferencePool	ReferencePool.Acquire<T>() / Release()
DataNode	Tree data structure, use directly
DataTable	DataRow classes implement IDataRow in L0

Modules requiring L1 Unity adapters: Resource, Scene, Entity, UI, Sound.

Key Domain Boundaries

Domain	Key Files	Responsibility
CombatScheduler	CombatScheduler.cs, CombatStates/*	State machine managing combat phases
EnemyManager	EnemyManager.cs, EnemySpawnDirector.cs, EnemyLifecycleTracker.cs	Enemy spawning and lifecycle
PlayerInventory	PlayerInventoryComponent.cs, PlayerInventoryTowerAssemblyService.cs	Backpack, trading, tower assembly
InventoryGeneration	InventoryGenerationComponent.cs, DropPoolRoller.cs, ShopGoodsBuilder.cs	Drops, shop goods, rewards
MapEntity	MapEntity.cs, MapTopologyService.cs, TowerPlacementService.cs	Map orchestration, grid/path, tower placement
TagSystem	TagGenerationRuleRegistry.cs, RarityTagBudgetRuleRegistry.cs, TagDefinitionRegistry.cs	Tag generation rules and definitions

Combat State Machine Flow

Loading → RunningPhase → WaitingForPhaseEnd → Settlement → RewardSelection(可选) → FinishForm → WaitingForReturn

Dual-Currency System

• Coin: Single-combat internal currency (CombatRunResourceStore.CurrentCoin). Used for build/upgrade/destroy in combat. Reset per combat from DRLevel.StartCoin.
• Gold: Cross-combat persistent currency (PlayerInventoryComponent.Gold). Used for shop buy/sell. Persists across nodes.

Tag System

Three-table configuration: Tag.txt, RarityTagBudget.txt, TagConfig.txt.

Active Tags (7): Fire, Ice, Crit, Execution, Shatter, Inferno, AbsoluteZero.

Deferred Tags (5): BurnSpread, IgniteBurst, FreezeMask, Pierce, Overpenetrate (metadata only, not combat-active).

Tag Runtime Structure:

• Component instances hold TagType[]
• Tower instances hold TagRuntimeData[] (grouped by TagType with Stack count)
• TagGenerationRuleRegistry and RarityTagBudgetRuleRegistry load from TagRow / RarityTagBudgetRow (IDataRow implementations)

Tag Generation Uses InventoryGenerationRandomContext for reproducibility (RunSeed + SourceType + ItemInstanceId + ConfigId).

Service Naming Conventions

• Scheduler: State machine boundary only
• Manager: Facade/aggregate entry for subdomain
• Coordinator: Cross-state orchestration
• Calculator: Pure computation
• Session: Single lifecycle object
• Bridge: Framework boundary adapter
• Runtime: Mutable state carrier
• Resolver: Mapping/lookup/resolution
• Tracker: Tracks running entities or factual truth values
• Port: Restricted host interface for internal state/use cases

Key Invariants

1. All combat state transitions go through CombatScheduler.ChangeState(...)
2. EnemyManager only reports events, never directly calls state transitions
3. CombatRunResourceStore is sole source of truth for in-combat Coin/Gold/BaseHp
4. EnemyLifecycleTracker is sole source for AliveEnemyCount and HasAliveBoss
5. MapEntity accesses combat context via MapData + Events only
6. Tag generation uses InventoryGenerationRandomContext for reproducibility
7. TowerPlacementService is sole write entry for tower mapping state
8. MapTopologyService is sole source for Path/Foundation data

Project Structure

src/
├── GeometryTD.Domain/           # L0 - Pure C#, references GameFramework.dll
│   ├── Definition/
│   │   ├── Enum/               # All enums (TagType, RarityType, etc.)
│   │   ├── Constant/           # Constants
│   │   ├── DataStruct/         # POCOs (AttackPayload, HitContext, TowerStatsData)
│   │   └── Tag/                # Tag definitions, generation rules, combat effects
│   ├── Event/                   # GameEventArgs subclasses by domain
│   ├── UI/                     # UI contexts and use case interfaces
│   ├── DataTable/              # IDataRow implementations (TagRow, RarityTagBudgetRow)
│   └── CustomComponent/        # L0 services (CombatScheduler, EnemyManager, etc.)
│
├── GeometryTD.Infrastructure/   # L1 - Unity adapter layer
│   ├── Entity/                 # EntityLogic, EntityData DTOs
│   ├── Scene/Map/             # MapTopologyService, TowerPlacementService
│   ├── UI/                    # UGuiForm base, controllers
│   ├── DataTable/             # L1 DataRowBase wrappers over L0 rows
│   └── CustomComponent/       # Unity Components holding L0 services
│
└── GeometryTD.Presentation/     # L2 - Unity MonoBehaviours, Views
    ├── Entity/Logic/          # Player, Enemy, Tower, Bullet entities
    └── Components/            # MovementComponent, ShooterBullet, etc.

Documentation

• docs/LayeredArchitectureDesign.md - Three-layer architecture, GameFramework integration, migration phases
• docs/CombatNodeArchitecture.md - Combat scheduler, state machine, EnemyManager, resource store
• docs/MapEntityArchitecture.md - Map orchestration, tower placement, topology services
• docs/TagSystemDesign.md - Tag system rules, generation, three-table config, combat effects
• docs/GameDesign.md - High-level game design
• docs/MVP-Scope.md - Current MVP scope