# 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 with no Unity dependencies. Contains enums, constants, data structures, CombatNode domain, PlayerInventory, InventoryGeneration, UI use cases.
- **L1 (Infrastructure)**: Glue layer bridging L0 and Unity. Implements L0 interfaces, holds L0 service instances, manages Unity lifecycle.
- **L2 (Presentation)**: Unity MonoBehaviour classes, UGuiForm implementations, Entity Logic (Player, Enemy, Tower).

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

### Combat State Machine Flow

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

### Dual-Currency System

- **Coin**: Single-combat internal currency (`CombatRunResourceStore.CurrentCoin`)
- **Gold**: Cross-combat persistent currency (`PlayerInventoryComponent.Gold`)

### Tag System

Three-table configuration: `Tag.txt`, `RarityTagBudget.txt`, `TagConfig.txt`. Current shipped 7 tags: Fire, Ice, Crit, Execution, Shatter, Inferno, AbsoluteZero.

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

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

## Documentation

- `docs/LayeredArchitectureDesign.md` - Three-layer architecture
- `docs/CombatNodeArchitecture.md` - Combat scheduler and state machine
- `docs/MapEntityArchitecture.md` - Map orchestration services
- `docs/TagSystemDesign.md` - Tag system rules
- `docs/GameDesign.md` - High-level game design
- `docs/MVP-Scope.md` - Current MVP scope