# Spire Climbing System — Design Spec

> Describes the full lifecycle of a spire run: entering, climbing room-by-room,
> clearing floors, descending, and exiting.

---

## 1. Objective

The Spire is the core progression loop of Mana Loop. The player enters at a starting
floor determined by their `spireKey` prestige level, clears rooms by casting spells
at enemies, advances floor by floor to ever-higher challenges, and must fully descend
back to the exit floor before they can leave.

**Design goals:**
- Each floor is a multi-room dungeon with variable room counts.
- The descent is a meaningful mini-game: the player re-traverses every room they
  climbed in reverse, with each individual room having a 50% independent chance to
  have reset its enemies.
- Climbing rewards (insight, pacts, loot, discipline XP) are gated behind reaching
  high floors and signing pacts with guardians.

---

## 2. Controls / API

### 2.1 Player Actions

| Action | Trigger | Effect |
|---|---|---|
| Enter Spire | UI button on Spire Summary tab | `enterSpireMode()` — init spire state |
| Climb Up | automatic after room is cleared (ascending) | `advanceRoomOrFloor()` |
| Start Descent | "Descend" button on the climb page | `enterDescentMode()` — snapshots peak, begins reverse traversal |
| Exit Spire | "Exit" button (only at exit floor R0 during descent) | `exitSpireMode()` — reset to outside-spire state |

### 2.2 Game Commands (Store Actions)

The following are the **necessary** new store actions. Actions already implemented
that need modification are noted separately.

| Command | Store | Description |
|---|---|---|
| `enterSpireMode()` | combatStore | Reset to starting floor R0, generate first room, enter spire mode |
| `exitSpireMode()` | combatStore | Leave spire, reset all run state |
| `enterDescentMode()` | combatStore | **NEW** — snapshot peak floor/room, set `climbDirection = 'down'` |
| `advanceRoomOrFloor()` | combatStore | **NEW** — move to next room/floor (ascending) or previous room/floor (descending) |
| `processCombatTick(...)` | combatStore | **MODIFY** — must become room-aware (see §4.4) |

> **Removed vs. original draft:** `skipClearedRoom`, `markFloorReset`, `setCurrentRoom`,
> `setClearedFloor`, and `initGuardianDefensiveState` are **not needed as separate public
> actions** — this logic lives inside `advanceRoomOrFloor()` and `processCombatTick()`
> as private helpers. `addActivityLog` already exists.

### 2.3 State Transitions

```
outside-spire
    │  enterSpireMode()
    ▼
climbing-up (startFloor R0)
    │  room cleared → advanceRoomOrFloor() → next room
    │  last room on floor cleared → next floor, R0
    │  player presses "Descend"
    ▼
descending (peak floor, peak room)
    │  room cleared or skipped → advanceRoomOrFloor() → prev room
    │  R0 of floor → prev floor, last room
    │  reach exit floor R0
    ▼
descent complete — "Exit Spire" button shown
    │  exitSpireMode()
    ▼
outside-spire
```

---

## 3. Project Layout

Files to create or modify:

```
docs/specs/
  spire-climbing-spec.md      ← this file
  spire-combat-spec.md        ← companion: spell damage, weapons, golems

src/lib/game/stores/
  combat-state.types.ts       — add currentRoomIndex, roomsPerFloor, descentPeak,
                                 roomResetState, exitFloor fields
  combatStore.ts              — add enterDescentMode(), advanceRoomOrFloor()
  combat-actions.ts           — make processCombatTick room-aware

src/lib/game/utils/
  spire-utils.ts              — ensure getRoomsForFloor accepts a seed
  room-utils.ts               — add generateSpireRoomType(), library XP helper

src/components/game/tabs/
  SpireCombatPage/
    SpireCombatPage.tsx       — wire room-cleared; add descent UI
    SpireHeader.tsx           — "Descend" button on ascent; "Exit" button at exit floor R0
    RoomDisplay.tsx           — show "Room X / Y", room type badge, current game time
    SpireActivityLog.tsx      — log all room/floor events
```

---

## 4. Detailed Mechanics

### 4.1 Entering the Spire

1. Player presses "Enter Spire" on the Spire Summary tab.
2. `enterSpireMode()` runs:
   - `spireMode = true`
   - `currentAction = 'climb'`
   - `startFloor = 1 + (spireKey × 2)` — prestige upgrade; spireKey 0 → F1, spireKey 1 → F3, etc.
   - `exitFloor = startFloor` — the floor the player must reach on descent to be allowed to exit
   - `currentFloor = startFloor`
   - `currentRoomIndex = 0`
   - `roomsPerFloor = getRoomsForFloor(currentFloor, seed)`
   - `currentRoom = generateSpireFloorState(currentFloor, 0, roomsPerFloor)`
   - `clearedRooms = {}` — tracks which `floor:roomIndex` pairs have been cleared
   - `climbDirection = 'up'`
   - `descentPeak = null`
   - `roomResetState = {}` — per-room reset rolls, lazily populated on descent
   - activity log: `"Entered the Spire at Floor ${startFloor}"`

### 4.2 Room Count Per Floor

```
getRoomsForFloor(floor, seed):
  if isGuardianFloor(floor): return 1
  base = 5
  floorBonus = min(10, floor / 20)           // slow scaling, max +10
  randomVariation = floor(seededRandom(seed) * 3)  // 0, 1, or 2
  return base + floorBonus + randomVariation  // range: 5–17
```

- Guardian floors (every 10th): exactly **1 room**.
- All other floors: **5–17 rooms**, scaling slowly with floor level.
- Room count is **deterministic** per floor via seed so the same count is reproduced
  on descent. Seed = `floor × 12345 + runId`.

### 4.3 Room Types

Generated by `generateSpireRoomType(floor, roomIndex, totalRooms)`.

**Base roll (every room):**

```
roll = seededRandom(floor, roomIndex)

if roll < 0.10:  → rare roll (see below)
elif roll < 0.22: → 'swarm'
elif roll < 0.32: → 'speed'
else:             → 'combat'   (~68% of rooms)
```

**Rare roll (~10% of rooms)** — secondary roll determines sub-type:

```
rareRoll = seededRandom(floor, roomIndex, 'rare')

if rareRoll < 0.40: → 'recovery'
elif rareRoll < 0.70: → 'treasure'
else:                 → 'library'
```

So across all rooms: ~40% of 10% = **~4% recovery**, ~30% of 10% = **~3% treasure**,
~30% of 10% = **~3% library**.

**Override rules (applied after base roll):**
- Last room on a guardian floor → always `'guardian'`
- Every 7th floor, one room (chosen by seed) → always `'puzzle'`

**Room type summary:**

| Type | Approx. Frequency | Description |
|---|---|---|
| `combat` | ~68% | Single enemy, normal stats |
| `swarm` | ~12% | 3–7 weak enemies |
| `speed` | ~10% | Single enemy with elevated dodge chance |
| `guardian` | Every 10th floor, 1 room | Boss — high HP, shield, barrier, health regen |
| `recovery` | ~4% | No enemies; restores a portion of current mana pool |
| `treasure` | ~3% | No enemies; grants loot / equipment drop |
| `library` | ~3% | No enemies; grants discipline XP scaled to current floor (see §4.8) |
| `puzzle` | ~1 per 7 floors | Attunement-based challenge; no combat |

**Speed room interaction:** A `speed` room combined with an enemy that also has the
`agile` modifier results in an **additive dodge bonus** on top of the agile modifier
value. See combat spec §2.3 for modifier details.

### 4.4 Ascending — Room and Floor Advancement

Rooms advance **automatically** when all enemies in the current room reach 0 HP
(or immediately for non-combat rooms). The player does not press a button.

```
advanceRoomOrFloor() [direction = 'up']:
  markRoomCleared(currentFloor, currentRoomIndex)
  activityLog("Room ${currentRoomIndex + 1}/${roomsPerFloor} cleared")

  if currentRoomIndex + 1 >= roomsPerFloor:
    // Last room on this floor
    activityLog("Floor ${currentFloor} cleared — ascending")
    newFloor = min(currentFloor + 1, FLOOR_CAP)
    currentFloor = newFloor
    currentRoomIndex = 0
    roomsPerFloor = getRoomsForFloor(newFloor, seed)
    currentRoom = generateSpireFloorState(newFloor, 0, roomsPerFloor)
    resetCastProgress()
  else:
    currentRoomIndex += 1
    currentRoom = generateSpireFloorState(currentFloor, currentRoomIndex, roomsPerFloor)
    resetCastProgress()
```

Non-combat rooms (recovery, treasure, library, puzzle) trigger `advanceRoomOrFloor()`
immediately on entry after applying their effect.

### 4.5 Descent Initiation

The "Descend" button is available at any point during ascent. Pressing it:

```
enterDescentMode():
  descentPeak = { floor: currentFloor, roomIndex: currentRoomIndex }
  climbDirection = 'down'
  activityLog("Beginning descent from Floor ${currentFloor}, Room ${currentRoomIndex + 1}")
  // Start descending from the current room (player re-fights or skips it)
  onEnterRoomDescend()
```

### 4.6 Descending — Reverse Traversal

On descent, rooms are visited in **strict reverse order**: within a floor, rooms
count down from the highest index back to 0. When room 0 is cleared or skipped,
the player moves down to the previous floor at its **highest** room index.

```
advanceRoomOrFloor() [direction = 'down']:
  activityLog("Room ${currentRoomIndex + 1} passed")

  if currentFloor <= exitFloor && currentRoomIndex <= 0:
    // Reached the exit point
    isDescentComplete = true
    activityLog("Descent complete — Exit Spire is now available")
    return

  if currentRoomIndex <= 0:
    // Move down to previous floor, enter at its last room
    currentFloor -= 1
    roomsPerFloor = getRoomsForFloor(currentFloor, seed)
    currentRoomIndex = roomsPerFloor - 1
    activityLog("Descended to Floor ${currentFloor}")
  else:
    currentRoomIndex -= 1

  currentRoom = generateSpireFloorState(currentFloor, currentRoomIndex, roomsPerFloor)
  resetCastProgress()
  onEnterRoomDescend()
```

### 4.7 Per-Room Reset on Descent

Each room is checked **independently** when the player enters it during descent.
Floors do not share a single reset roll — every room rolls on its own.

```
onEnterRoomDescend():
  key = `${currentFloor}:${currentRoomIndex}`

  if roomResetState[key] is undefined:
    roomResetState[key] = (Math.random() < 0.5)

  if !wasRoomCleared(currentFloor, currentRoomIndex):
    // Room was never cleared on the way up — must fight it now
    activityLog("Room ${currentRoomIndex + 1} on Floor ${currentFloor} was not cleared — enemies present")
    // enemies already in currentRoom from generation, no change needed
    return

  if roomResetState[key] === true:
    // Room reset — re-generate enemies
    currentRoom = generateSpireFloorState(currentFloor, currentRoomIndex, roomsPerFloor)
    activityLog("Room ${currentRoomIndex + 1} on Floor ${currentFloor} has reset — enemies respawned")
  else:
    // Room did not reset — auto-skip
    activityLog("Room ${currentRoomIndex + 1} on Floor ${currentFloor} is clear — moving on")
    advanceRoomOrFloor()   // immediately continue
```

Guardian rooms that reset on descent re-initialize the full guardian defensive state
(shield pool, barrier %, health regen) as if the player is fighting the guardian for
the first time.

### 4.8 Library Rooms — Discipline XP

When a `library` room is entered:

```
onEnterLibraryRoom(floor):
  discipline = pickRandom(allActiveDisciplines)
  xpGrant = BASE_LIBRARY_XP × (1 + floor / 10)
  discipline.addXP(xpGrant)
  activityLog("Ancient tome studied — ${discipline.name} gained ${xpGrant} XP")
  advanceRoomOrFloor()
```

- `BASE_LIBRARY_XP` is a tunable constant (suggested starting value: 50).
- XP is granted to a **random active discipline** (one of the player's currently
  running disciplines).
- If no disciplines are active, XP is granted to a random unlocked discipline.
- The grant scales linearly with floor: floor 10 = 2×, floor 20 = 3×, etc.

### 4.9 Exiting the Spire

The "Exit Spire" button is visible **only** when:
- `isDescentComplete === true`

(Internally this means `currentFloor === exitFloor && currentRoomIndex === 0 && climbDirection === 'down'`.)

```
exitSpireMode():
  spireMode = false
  currentAction = 'meditate'
  climbDirection = null
  descentPeak = null
  roomResetState = {}
  clearedRooms = {}
  currentFloor = exitFloor
  currentRoomIndex = 0
  isDescentComplete = false
  activityLog("Exited the Spire")
```

---

## 5. Activity Log Events

Every meaningful state change appends an entry to the spire activity log. Required events:

| Event | Message |
|---|---|
| Enter spire | `"Entered the Spire at Floor {N}"` |
| Room cleared (combat) | `"Floor {N} Room {R}/{total} cleared"` |
| Room skipped (no reset) | `"Floor {N} Room {R} is clear — moving on"` |
| Room reset on descent | `"Floor {N} Room {R} has reset — enemies respawned"` |
| Room not cleared on ascent | `"Floor {N} Room {R} was not cleared — enemies present"` |
| Floor ascended | `"Ascending to Floor {N}"` |
| Floor descended | `"Descended to Floor {N}"` |
| Non-combat room entered | `"Entered {roomType} room on Floor {N}"` |
| Library XP granted | `"{Discipline} gained {XP} XP from ancient tome"` |
| Descent initiated | `"Beginning descent from Floor {N} Room {R}"` |
| Descent complete | `"Descent complete — Exit Spire is now available"` |
| Exit spire | `"Exited the Spire"` |

---

## 6. State Fields Summary

New and modified fields in `combat-state.types.ts`:

```typescript
// Run identity
startFloor: number              // floor entered at (= 1 + spireKey × 2)
exitFloor: number               // floor player must reach to exit (= startFloor)

// Room navigation
currentRoomIndex: number        // 0-indexed room within currentFloor
roomsPerFloor: number           // total rooms on currentFloor (deterministic)

// Descent tracking
climbDirection: 'up' | 'down' | null
descentPeak: { floor: number; roomIndex: number } | null
roomResetState: Record<string, boolean>   // key = "floor:roomIndex"
clearedRooms: Record<string, boolean>     // key = "floor:roomIndex"
isDescentComplete: boolean
```

> `isDescending: boolean` (legacy alias) can be removed in favour of `climbDirection === 'down'`.

---

## 7. Code Style Notes

- Room count uses the same deterministic seed on descent as ascent: `seed = floor × 12345 + runId`.
- `roomResetState` and `clearedRooms` use composite string keys (`"floor:roomIndex"`) to avoid
  nested object complexity.
- Descent-related state is **not persisted** — a page reload mid-descent forfeits the run.
- All activity log calls go through the existing `addActivityLog(type, msg, details)` action.

---

## 8. Testing

### Unit Tests

1. `getRoomsForFloor` — same output for same (floor, seed); returns 1 for guardian floors.
2. `generateSpireRoomType` — rare roll produces recovery/treasure/library at correct ratios; guardian floor override works; puzzle floor override works.
3. `advanceRoomOrFloor` ascending — increments roomIndex; on last room, increments floor and resets roomIndex to 0.
4. `advanceRoomOrFloor` descending — decrements roomIndex; at roomIndex 0, moves to previous floor at `roomsPerFloor - 1`; at exitFloor R0, sets `isDescentComplete`.
5. Per-room reset — each room rolls independently; two rooms on the same floor can have different outcomes.
6. Library XP — grant scales with floor; targets an active discipline.
7. `spireKey` — `startFloor` and `exitFloor` correctly reflect `1 + spireKey × 2`.

### Integration Tests

1. Full ascent then descent — player reaches F3 R4, starts descent, verifies F3 R4→R3→R2→R1→R0, then F2 last_room→...→R0, then F1 last_room→...→R0 (if startFloor = F1).
2. Per-room reset independence — mock random so room 0 resets and room 1 does not on the same floor.
3. Exit gating — "Exit Spire" not visible until `isDescentComplete` is true.

---

## 9. Boundaries / Out of Scope

- Loot generation inside treasure rooms (drop tables are a separate system).
- Golem summoning lifecycle (see combat spec §6).
- DoT / debuff runtime processing (see combat spec §5).
- Incursion's effect on mana regen during spire (handled in manaStore, not here).
- Auto-climb / auto-descend automation.
- Per-floor rewards (insight, mana drops) — handled by `onFloorCleared` in combat-tick.

---

## 10. Acceptance Criteria

| # | Criterion |
|---|---|
| AC-1 | `spireKey 0` starts at F1; `spireKey 1` starts at F3; `spireKey 2` starts at F5. |
| AC-2 | Entering spire starts at `startFloor` R0; rooms advance automatically on clear. |
| AC-3 | Each room shows "Room X / Y" and the room type in the UI. |
| AC-4 | After clearing last room on floor N, player moves to F(N+1) R0 with new room count. |
| AC-5 | "Descend" button is available at any point during ascent. |
| AC-6 | Descent traverses rooms in exact reverse (R_max → R0 per floor, then floor-1). |
| AC-7 | Each room on descent rolls its reset independently (50%); two rooms on the same floor can differ. |
| AC-8 | Skipped rooms (no reset) log an activity entry and auto-advance immediately. |
| AC-9 | Library rooms grant discipline XP scaled by floor to a random active discipline and log the event. |
| AC-10 | "Exit Spire" is only visible when `isDescentComplete === true`. |
| AC-11 | Guardian rooms that reset on descent re-initialize full guardian defensive state. |
| AC-12 | Activity log contains an entry for every room skip, reset, clear, floor transition, and spire entry/exit. |