# 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