# Mana-Loop: Comprehensive Game Briefing Document

**Document Version:** 2.0  
**Updated:** Disciplines Refactor (skills system removed; disciplines replace it entirely)

---

## Table of Contents

1. [Executive Summary](#executive-summary)
2. [Core Game Loop](#core-game-loop)
3. [Mana System](#mana-system)
4. [Time & Incursion System](#time--incursion-system)
5. [Spire & Floor System](#spire--floor-system)
6. [Combat System](#combat-system)
7. [Guardian & Pact System](#guardian--pact-system)
8. [Attunement System](#attunement-system)
9. [Discipline System](#discipline-system)
10. [Equipment & Enchantment System](#equipment--enchantment-system)
11. [Golemancy System](#golemancy-system)
12. [Prestige/Loop System](#prestigeloop-system)
13. [Achievement System](#achievement-system)
14. [Formulas & Calculations](#formulas--calculations)
15. [System Interactions](#system-interactions)
16. [Code Architecture](#code-architecture)

---

## Executive Summary

**Mana-Loop** is a browser-based incremental/idle game with a 30-day time loop mechanic. Players gather mana, practice disciplines, climb a 100-floor spire, defeat guardians, sign pacts, enchant equipment, and prestige for permanent progression.

**Key Differentiators:**
- 3-class Attunement system (Enchanter, Invoker, Fabricator)
- Equipment-based spell system (spells come from enchanted gear)
- Practice-based Discipline system — no discrete skill levels, only continuous XP growth
- Time pressure through the incursion mechanic
- Guardian pacts provide permanent multipliers

**Code Architecture:** Modular stores, crafting actions, discipline data, and constants. The old skill system (study, skill tiers, milestone upgrades) has been fully removed and replaced by the Discipline system.

---

## Core Game Loop

### Primary Loop (Within Each Run)

```
┌─────────────────────────────────────────────────────────────┐
│                      TIME LOOP (30 Days)                     │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────┐    ┌────────────┐    ┌───────────┐    ┌──────┐ │
│  │ GATHER  │───▶│  PRACTICE  │───▶│   CLIMB   │───▶│CRAFT │ │
│  │  MANA   │    │ DISCIPLINES│    │   SPIRE   │    │ GEAR │ │
│  └─────────┘    └────────────┘    └───────────┘    └──────┘ │
│       │               │                │               │    │
│       └───────────────┴────────────────┴───────────────┘    │
│                            │                                 │
│                            ▼                                 │
│  ┌─────────────────────────────────────────────────────┐   │
│  │           DEFEAT GUARDIANS → SIGN PACTS              │   │
│  └─────────────────────────────────────────────────────┘   │
│                            │                                 │
│                            ▼                                 │
│  ┌─────────────────────────────────────────────────────┐   │
│  │           DAY 30: LOOP ENDS → GAIN INSIGHT           │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
```

### Game Actions

| Action | Effect | Time Cost |
|--------|--------|-----------|
| **Meditate** | Regen mana with meditation bonus multiplier | Passive (auto-selected after actions) |
| **Climb** | Progress through spire floors, cast spells | Active combat |
| **Practice** | Run active disciplines, consuming mana each tick | Continuous |
| **Craft** | Create/enchant equipment | Hours per stage |
| **Convert** | Auto-convert raw mana to elements | Per tick |
| **Design** | Create enchantment designs (limited to owned gear types) | Hours |
| **Prepare** | Ready equipment for enchanting | Hours + mana |
| **Enchant** | Apply enchantment to equipment | Hours + mana |

### Action Transitions

- After completing Design, Prepare, Enchant, or Craft the game automatically transitions to **Meditate**
- Action buttons are hidden when in Spire Mode
- `currentAction` state lives in `stores/gameStore.ts`

---

## Mana System

### Mana Types Hierarchy

```
Raw Mana (Base Resource)
    │
    ├──▶ Base Elements (7) ─────────────────────────────────────┐
    │    Fire*, Water*, Air*, Earth*, Light, Dark, Death        │
    │    *Locked at start - must be unlocked                    │
    │                                                           │
    ├──▶ Utility Element (1) ───────────────────────────────────┤
    │    Transference (Enchanter attunement - UNLOCKED at start) │
    │                                                           │
    ├──▶ Compound Elements (3) ── Created from 2 base ──────────┤
    │    Metal = Fire + Earth                                   │
    │    Sand  = Earth + Water                                  │
    │    Lightning = Fire + Air                                 │
    │                                                           │
    └──▶ Exotic Elements (3) ── Created from advanced recipes ──┤
         Crystal = Sand + Sand + Light                          │
         Stellar = Fire + Fire + Light                          │
         Void    = Dark + Dark + Death                          │
```

Fire, Water, Air, and Earth are **locked at start**. Only Transference is unlocked initially.

### Mana Formulas

**Maximum Raw Mana:**
```
maxMana = (100 + (manaWellLevel × 100) + (prestigeManaWell × 500) + equipmentBonuses) × maxManaMultiplier
```

**Maximum Elemental Mana:**
```
elementMax = (10 + (elemAttuneLevel × 50) + (prestigeElemAttune × 25)) × elementCapMultiplier
```

**Base Regeneration (per hour):**
```
baseRegen       = 2 + (manaFlowLevel × 1) + (manaSpringLevel × 2) + (prestigeManaFlow × 0.5)
effectiveRegen  = baseRegen × (1 - incursionStrength) × meditationMultiplier
```

**Meditation Bonus:**
```
Base: 1 + min(hours/4, 0.5)  →  up to 1.5× after 4 hours
```

**Attunement Mana Conversion:**
- Enchanter: Raw → Transference at 0.2/hour base (scales with level)
- Fabricator: Raw → Earth at 0.25/hour base (scales with level)

### Starting Elements

| Element | Unlocked at Start |
|---------|-------------------|
| Transference | ✅ Yes |
| Fire | ❌ No |
| Water | ❌ No |
| Air | ❌ No |
| Earth | ❌ No |
| Light | ❌ No |
| Dark | ❌ No |
| Death | ❌ No |

### Mana Conversion Cost
- **100 Raw Mana = 1 Elemental Mana** (for base elements)
- Compound/Exotic elements are crafted, not converted

---

## Time & Incursion System

### Time Constants

| Constant | Value | Description |
|----------|-------|-------------|
| `TICK_MS` | 200ms | Real time per game tick |
| `HOURS_PER_TICK` | 0.04 | Game hours per tick |
| `MAX_DAY` | 30 | Days per loop |
| `INCURSION_START_DAY` | 20 | When incursion begins |

### Time Progression
- 1 real second = 5 game hours (at 5 ticks/second)
- 1 game day = 24 game hours = 4.8 real seconds
- Full 30-day loop ≈ 2.4 real minutes

### Incursion Mechanic

```
if (day < 20): incursionStrength = 0
else:          incursionStrength = min(0.95, (totalHours / maxHours) × 0.95)
```

Reduces mana regeneration by `(1 - incursionStrength)`. Starts at 0% on Day 20, reaches 95% by Day 30.

---

## Spire & Floor System

### Floor Generation

**Floor Element Cycle:**
```javascript
FLOOR_ELEM_CYCLE = ["fire", "water", "air", "earth", "light", "dark", "death"]
element = FLOOR_ELEM_CYCLE[(floor - 1) % 7]
```

**Floor HP Formula:**
```
normalFloorHP  = floor(100 + floor × 50 + floor^1.7)
guardianFloorHP = GUARDIANS[floor].hp  // in constants/guardians.ts
```

**Guardian Floors:** 10, 20, 30, 40, 50, 60, 80, 90, 100

### Room Types

| Room Type | Chance | Description |
|-----------|--------|-------------|
| **Combat** | Default | Single enemy, normal combat |
| **Guardian** | Fixed | Boss floor |
| **Swarm** | 15% | 3–6 enemies with 40% HP each |
| **Speed** | 10% | Enemy with dodge chance (25% base + 0.5%/floor) |
| **Puzzle** | 20% on puzzle floors | Progress-based, faster with relevant attunement |

### Armor Scaling
```javascript
FLOOR_ARMOR_CONFIG = {
  baseChance:     0,      // No armor before floor 10
  chancePerFloor: 0.01,   // +1% chance per floor after 10
  maxArmorChance: 0.5,    // Max 50% of floors have armor
  minArmor:       0.05,   // Min 5% damage reduction
  maxArmor:       0.25    // Max 25% on non-guardians
}
```

---

## Combat System

### Spell Casting Mechanics

```
progressPerTick = HOURS_PER_TICK × spellCastSpeed × totalAttackSpeed
```

Lightning spells get +30% effective cast speed.

### Damage Calculation
```
baseDamage     = spellDamage + disciplineBonus(combatStat)
pctBonus       = 1 + disciplineMultiplier
pactMultiplier = product of all signed pact multipliers
elementalBonus = getElementalBonus(spellElement, floorElement)

finalDamage = baseDamage × pctBonus × pactMultiplier × elementalBonus
```

### Elemental Effectiveness

| Condition | Multiplier |
|-----------|------------|
| Spell same element as floor | 1.25× |
| Spell is opposite of floor element | 1.50× (Super Effective) |
| Spell's opposite matches floor | 0.75× (Not Very Effective) |
| Raw mana spells | 1.00× |

**Element Opposites:**
```
Fire ↔ Water    Air ↔ Earth    Light ↔ Dark
Lightning — no opposite (has armor pierce instead)
```

### Armor & Damage Reduction

```
effectiveArmor = max(0, enemyArmor - armorPierce)
damageDealt    = damage × (1 - effectiveArmor)
```

### Critical Hits

Critical chance and multiplier come from discipline bonuses (no fixed skill levels).

### Special Combat Effects

| Effect | Description |
|--------|-------------|
| **Burn** | Damage over time |
| **Freeze** | Prevents dodge |
| **Stun** | Temporary disable |
| **Pierce** | Ignores % armor |
| **Chain** | Hits multiple targets |
| **AOE** | Area damage |
| **Buff** | Damage multiplier |

---

## Guardian & Pact System

### Guardian Floors & Stats

| Floor | Guardian | Element | HP | Pact Mult | Armor | Unique Perk |
|-------|----------|---------|-----|-----------|-------|-------------|
| 10 | Ignis Prime | Fire | 5,000 | 1.5× | 10% | Fire spells cast 10% faster |
| 20 | Aqua Regia | Water | 15,000 | 1.75× | 15% | Water spells +15% damage |
| 30 | Ventus Rex | Air | 30,000 | 2.0× | 18% | Air spells 15% crit chance |
| 40 | Terra Firma | Earth | 50,000 | 2.25× | 25% | Earth spells +25% vs guardians |
| 50 | Lux Aeterna | Light | 80,000 | 2.5× | 20% | Light spells reveal weaknesses |
| 60 | Umbra Mortis | Dark | 120,000 | 2.75× | 22% | Dark spells +25% vs armored |
| 80 | Mors Ultima | Death | 250,000 | 3.25× | 25% | Death spells execute <20% HP |
| 90 | Primordialis | Void | 400,000 | 4.0× | 30% | Void spells ignore 30% resistance |
| 100 | The Awakened One | Stellar | 1,000,000 | 5.0× | 35% | All spells +50% dmg, 25% faster |

### Guardian Boons (on pact)

| Boon Type | Effect |
|-----------|--------|
| `maxMana` | +Max raw mana |
| `manaRegen` | +Regen/hour |
| `castingSpeed` | +% cast speed |
| `elementalDamage` | +% element damage |
| `rawDamage` | +% all damage |
| `critChance` | +% crit chance |
| `critDamage` | +% crit multiplier |
| `insightGain` | +% insight |

### Victory Condition
Defeat floor 100 guardian **and** sign the pact → 3× normal insight.

---

## Attunement System

Attunements are class-like specializations that unlock discipline pools and grant unique capabilities.

### The Three Attunements

#### 1. Enchanter (Right Hand) ✅

| Property | Value |
|----------|-------|
| **Slot** | Right Hand |
| **Primary Mana** | Transference |
| **Raw Regen** | +0.5/hour base |
| **Conversion** | 0.2 raw→transference/hour |
| **Unlock** | Starting attunement |

**Disciplines Unlocked:** Enchanter discipline pool (`data/disciplines/enchanter.ts`)  
**Capabilities:** Enchanting & disenchanting equipment

#### 2. Invoker (Chest) ✅

| Property | Value |
|----------|-------|
| **Slot** | Chest |
| **Primary Mana** | None (gains from pacts) |
| **Raw Regen** | +0.3/hour base |
| **Conversion** | None |
| **Unlock** | Defeat first guardian |

**Disciplines Unlocked:** Invoker discipline pool (`data/disciplines/invoker.ts`)  
**Capabilities:** Form pacts with guardians, access guardian powers

#### 3. Fabricator (Left Hand) ✅

| Property | Value |
|----------|-------|
| **Slot** | Left Hand |
| **Primary Mana** | Earth |
| **Raw Regen** | +0.4/hour base |
| **Conversion** | 0.25 raw→earth/hour |
| **Unlock** | Prove crafting worth |

**Disciplines Unlocked:** Fabricator discipline pool (`data/disciplines/fabricator.ts`)  
**Capabilities:** Golem crafting, gear crafting, Earth shaping

### Attunement Leveling

```javascript
Level 2: 1,000 XP
Level 3: 2,500 XP
Level 4: 5,000 XP
Level 5: 10,000 XP
// Each level ≈ 2× previous; Max Level: 10

regenMultiplier  = 1.5^(level - 1)
conversionRate   = baseRate × 1.5^(level - 1)
```

---

## Discipline System

Disciplines replace the old skill system entirely. There are no discrete levels or study actions — disciplines grow **continuously** through practice. The player activates a discipline and it drains mana each tick in exchange for permanent stat growth.

### Core Concept

> The more you practice a discipline, the stronger its effect — but the more mana it costs to maintain.

- **XP** accumulates each tick the discipline is active and has enough mana to drain
- **Stat bonus** grows as a power curve of XP (never resets within a run)
- **Mana drain** also increases with XP — mastery has a cost
- **Perks** unlock at XP thresholds, granting bonus effects

### Disciplines vs Old Skills

| Old Skill System | Discipline System |
|-----------------|-------------------|
| Discrete levels (1–10 per tier) | Continuous XP accumulation |
| Mana cost paid once on study | Mana drained every tick |
| Required hours to level up | Grows passively while active |
| Milestone upgrades at L5/L10 | Perks unlock at XP thresholds |
| 5-tier evolution (T1–T5) | Single continuous curve per discipline |

### Formulas

**Stat Bonus (continuous):**
```
StatBonus = baseValue × (XP / scalingFactor)^0.65
```

**Mana Drain Per Tick:**
```
ManaDrainPerTick = drainBase × (1 + (XP / difficultyFactor)^0.4)
```

- `scalingFactor` controls how quickly stats grow
- `difficultyFactor` controls how quickly drain increases
- Higher `scalingFactor` → slower stat gain; higher `difficultyFactor` → slower drain increase

### Concurrent Discipline Limit

```
concurrentLimit = 1 + floor(totalXP / 500)   // capped at base + 3
```

Players start with 1 active discipline slot. As total XP across all disciplines grows, additional slots unlock (max 4 total).

### Perk Types

| Type | Behaviour |
|------|-----------|
| `once` | Unlocks permanently when XP reaches `threshold` |
| `capped` | Grants stacking bonus tiers; each tier requires another `interval` XP beyond `threshold` |
| `infinite` | Repeating bonus — a new stack every `interval` XP past `threshold` (no cap) |

### Attunement Pools

| Pool | File | Requires |
|------|------|---------|
| Base | `data/disciplines/base.ts` | None (all attunements) |
| Enchanter | `data/disciplines/enchanter.ts` | Enchanter attunement |
| Invoker | `data/disciplines/invoker.ts` | Invoker attunement |
| Fabricator | `data/disciplines/fabricator.ts` | Fabricator attunement |

### Example Disciplines

| Discipline | Attunement | Mana Type | Stat Bonus | Description |
|------------|------------|-----------|------------|-------------|
| Raw Mana Mastery | Base | Raw | `maxManaBonus` | More raw mana from practice |
| Elemental Attunement | Base | Fire | `elementCap_fire` | Expanded fire capacity |
| Lightning Surge | Invoker | Lightning | `lightningDamage` | Boosts lightning spell damage |
| Void Echo | Invoker | Void | `voidCastSpeed` | Increases void spell cast speed |
| Metalworking | Fabricator | Metal | `craftSpeed_metal` | Faster metal equipment crafting |
| Crystal Shaping | Fabricator | Crystal | `durability_crystal` | More durable crystal equipment |
| Soulforge | Enchanter | Light | `enchantPower` | Stronger enchantment effects |
| Mana Prism | Enchanter | Light | `manaReflect` | Prismatic mana focusing |

### Discipline Lifecycle

```
1. Player opens Disciplines tab → sees available disciplines for their attunements
2. Player activates discipline (costs nothing up-front; requires mana type unlocked)
3. Each game tick:
   a. ManaDrain deducted from mana pool
   b. If insufficient mana → discipline auto-pauses
   c. If sufficient mana → disc.xp += 1; stat bonuses recomputed
4. Player can manually pause/resume disciplines
5. On loop end, XP resets (stat bonuses are per-run, not permanent)
   — Prestige upgrades may eventually preserve some XP
```

### Discipline UI

`src/components/game/tabs/DisciplinesTab.tsx`  
`src/lib/game/stores/discipline-slice.ts` — Zustand store (persisted)  
`src/lib/game/effects/discipline-effects.ts` — integrates into `getUnifiedEffects()`

---

## Equipment & Enchantment System

### Equipment Slots

```
mainHand   - Staves (2H), Wands, Swords
offHand    - Shields, Catalysts (blocked by 2-handed weapons)
head       - Hoods, Hats, Helms
body       - Robes, Armor
hands      - Gloves, Gauntlets
feet       - Boots, Shoes
accessory1 - Rings, Amulets
accessory2 - Rings, Amulets
```

### Two-Handed Weapons

2-handed weapons (Staves) occupy both `mainHand` and `offHand`. The offhand slot is **blocked** when a 2H weapon is equipped. The UI shows a "Blocked by 2-handed weapon" label on the offhand slot.

### Equipment Instance Structure

```typescript
interface EquipmentInstance {
  instanceId:     string;
  typeId:         string;
  name:           string;
  enchantments:   AppliedEnchantment[];
  usedCapacity:   number;
  totalCapacity:  number;
  rarity:         'common' | 'uncommon' | 'rare' | 'epic' | 'legendary' | 'mythic';
  quality:        number;  // 0–100
}
```

### Enchantment Process (3 Stages)

#### Stage 1: Design
- Select effects from unlocked pool (`data/enchantment-effects.ts`)
- Limited to owned gear types
- Time: 1h base + 0.5h per effect stack
- Implemented in `crafting-actions/design-actions.ts`

#### Stage 2: Prepare
- Mana cost: `capacity × 10`
- Time: `2h + 1h per 50 capacity`
- Auto-transitions to Meditate on complete
- Implemented in `crafting-actions/preparation-actions.ts`

#### Stage 3: Apply
- Mana per hour: `20 + 5 per effect stack`
- Time: `2h + 1h per effect stack`
- Grants Enchanter XP: 1 XP per 10 capacity
- Auto-transitions to Meditate on complete
- Implemented in `crafting-actions/application-actions.ts`

### Enchantment Effect Categories

| Category | Description | Equipment Types |
|----------|-------------|-----------------|
| **Spell** | Grants spell ability | Casters only |
| **Mana** | Max/regen/click bonuses | Casters, Catalysts, Head, Body, Accessories |
| **Combat** | Damage, crit, speed | Casters, Hands |
| **Utility** | Meditation, insight | Most equipment |
| **Special** | Unique effects | Various |
| **Elemental** | Weapon enchantments | Swords, Casters |

### Starting Equipment

| Slot | Item | Enchantment | Capacity |
|------|------|-------------|----------|
| Main Hand | Basic Staff | Mana Bolt spell | 50/50 |
| Body | Civilian Shirt | None | 0/30 |
| Feet | Civilian Shoes | None | 0/15 |

---

## Golemancy System

### Golem Slots

```
Fabricator Level 2: 1 slot
Fabricator Level 4: 2 slots
Fabricator Level 6: 3 slots
Fabricator Level 8: 4 slots
Fabricator Level 10: 5 slots

slots = floor(fabricatorLevel / 2)
```

### Golem Types

#### Base Golems

| Golem | Element | Damage | Speed | Armor Pierce | Unlock |
|-------|---------|--------|-------|--------------|--------|
| Earth Golem | Earth | 8 | 1.5/h | 15% | Fabricator 2 |

#### Elemental Variants

| Golem | Element | Damage | Speed | Pierce | Unlock |
|-------|---------|--------|-------|--------|--------|
| Steel Golem | Metal | 12 | 1.2/h | 35% | Metal mana unlocked |
| Crystal Golem | Crystal | 18 | 1.0/h | 25% | Crystal mana unlocked |
| Sand Golem | Sand | 6 | 2.0/h | 10% | Sand mana unlocked |

#### Advanced Hybrid Golems (Enchanter 5 + Fabricator 5)

| Golem | Elements | Damage | Speed | Pierce | Special |
|-------|----------|--------|-------|--------|---------|
| Lava Golem | Earth + Fire | 15 | 1.0/h | 20% | AOE 2 |
| Galvanic Golem | Metal + Lightning | 10 | 3.5/h | 45% | Fast |
| Obsidian Golem | Earth + Dark | 25 | 0.8/h | 50% | High damage |
| Prism Golem | Crystal + Light | 20 | 1.5/h | 35% | AOE 3 |
| Quicksilver Golem | Metal + Water | 8 | 4.0/h | 30% | Very fast |
| Voidstone Golem | Earth + Void | 40 | 0.6/h | 60% | Ultimate |

### Golem Combat

```
progressPerTick = HOURS_PER_TICK × attackSpeed × efficiencyBonus
damage          = baseDamage × (1 + golemMasteryBonus)   // bonus from discipline
```

---

## Prestige/Loop System

### Loop End Conditions

| Condition | Result |
|-----------|--------|
| Day 30 reached | Loop ends, gain insight |
| Floor 100 + Pact 100 signed | Victory! 3× insight |

### Insight Formula

```
baseInsight  = floor(maxFloorReached × 15 + totalManaGathered / 500 + signedPacts.length × 150)
finalInsight = floor(baseInsight × (1 + insightAmpLevel × 0.25) × disciplineBonus)
```

### Prestige Upgrades

| Upgrade | Max | Cost | Effect |
|---------|-----|------|--------|
| Mana Well | 5 | 500 | +500 starting max mana |
| Mana Flow | 10 | 750 | +0.5 permanent regen |
| Deep Memory | 5 | 1000 | +1 memory slot |
| Insight Amp | 4 | 1500 | +25% insight gain |
| Spire Key | 5 | 4000 | Start at floor +2 |
| Temporal Echo | 5 | 3000 | +10% mana generation |
| Steady Hand | 5 | 1200 | -15% durability loss |
| Ancient Knowledge | 5 | 2000 | Start with blueprint |
| Elemental Attune | 10 | 600 | +25 element cap |
| Spell Memory | 3 | 2500 | Start with random spell |
| Guardian Pact | 5 | 3500 | +10% pact multiplier |
| Quick Start | 3 | 400 | +100 starting mana |
| Elem. Start | 3 | 800 | +5 each unlocked element |

### Memory System

- **Base slots:** 3  
- **Additional:** +1 per Deep Memory prestige level  
- **Memories:** Spells preserved across loops

---

## Achievement System

### Categories

| Category | Description |
|----------|-------------|
| `mana` | Mana gathering milestones |
| `combat` | Combat achievements |
| `progression` | Floor/guardian progression |
| `crafting` | Equipment and enchanting |
| `prestige` | Loop and insight milestones |

### Reward Types

| Reward | Effect |
|--------|--------|
| `insight` | One-time insight bonus |
| `manaBonus` | Permanent max mana |
| `damageBonus` | Permanent damage increase |
| `regenBonus` | Permanent regen increase |
| `title` | Cosmetic title |
| `unlockEffect` | Unlocks enchantment effect |

---

## Formulas & Calculations

### Damage Calculation (Complete)

```javascript
function calcDamage(state, spellId, floorElement) {
  const spell = SPELLS_DEF[spellId];        // constants/spells.ts

  // Base damage + discipline bonuses
  let damage = spell.dmg + disciplineBonus('combatDamage');

  // Discipline multiplier bonus
  damage *= 1 + disciplineBonus('damagePct');

  // Guardian bane (vs guardians only)
  if (isGuardian) {
    damage *= 1 + disciplineBonus('guardianBane');
  }

  // Pact multiplier
  damage *= state.signedPacts.reduce((m, f) => m * GUARDIANS[f].pact, 1);

  // Elemental effectiveness
  damage *= getElementalBonus(spell.elem, floorElement);

  // Critical hit (from discipline crit bonus)
  const critChance = disciplineBonus('critChance');
  if (Math.random() < critChance) damage *= 1.5;

  // Equipment effects
  damage *= effects.baseDamageMultiplier;
  damage += effects.baseDamageBonus;

  // Armor reduction
  const effectiveArmor = Math.max(0, enemyArmor - armorPierce);
  damage *= (1 - effectiveArmor);

  return Math.floor(damage);
}
```

### DPS Calculation

```javascript
dps = (damage × castSpeed × attackSpeedMultiplier) / hour
```

---

## System Interactions

### Primary Interaction Map

```
┌─────────────────────────────────────────────────────────────────────────┐
│                         CORE SYSTEM INTERACTIONS                         │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌──────────┐        ┌────────────┐        ┌──────────┐                │
│  │   MANA   │───────▶│ DISCIPLINES│───────▶│  COMBAT  │                │
│  └──────────┘        └────────────┘        └──────────┘                │
│       │                    │                    │                       │
│       │                    │                    │                       │
│       ▼                    ▼                    ▼                       │
│  ┌──────────┐        ┌──────────┐         ┌──────────┐                │
│  │ATTUNEMENT│───────▶│ENCHANTING│────────▶│  SPIRE   │                │
│  └──────────┘        └──────────┘         └──────────┘                │
│       │                    │                    │                       │
│       │                    │                    │                       │
│       ▼                    ▼                    ▼                       │
│  ┌──────────┐        ┌──────────┐         ┌──────────┐                │
│  │GOLEMANCY │        │EQUIPMENT │────────▶│ GUARDIAN │                │
│  └──────────┘        └──────────┘         └──────────┘                │
│                                                 │                       │
│                                                 ▼                       │
│                                          ┌──────────┐                  │
│                                          │   PACT   │                  │
│                                          └──────────┘                  │
│                                                 │                       │
│                                                 ▼                       │
│                                          ┌──────────┐                  │
│                                          │ PRESTIGE │                  │
│                                          └──────────┘                  │
└─────────────────────────────────────────────────────────────────────────┘
```

### Key System Dependencies

| System | Depends On | Unlocks/Enables |
|--------|------------|-----------------|
| **Disciplines** | Mana (drain cost), Attunement (pool access) | All combat/crafting stat bonuses |
| **Enchanting** | Enchanter attunement, Enchanter disciplines | Equipment spells, bonuses |
| **Golemancy** | Fabricator attunement, Earth mana | Additional combat damage |
| **Pacts** | Guardian defeat | Permanent multipliers, boons |
| **Prestige** | Loop completion | Permanent upgrades, memories |
| **Equipment** | Crafting/Blueprints | Spell access, stat bonuses |

### Progression Gates

1. **Early Game (Floors 1–10):** Mana gathering and regen, base disciplines, starting equipment
2. **Mid Game (Floors 10–40):** First guardian pacts, attunement unlocking, attunement discipline pools, equipment enchanting, Golemancy
3. **Late Game (Floors 40–80):** Compound/exotic elements, hybrid golems, advanced discipline perks, advanced enchantments
4. **End Game (Floors 80–100):** Void/Stellar/Crystal spells, ultimate golems, victory preparation

---

## Code Architecture

### Modular Structure Overview

#### Store Architecture

**Active Stores (`src/lib/game/stores/`):**
- **gameStore.ts** — Core state, tick logic, main actions
- **manaStore.ts** — Mana gathering, elements, conversion
- **combatStore.ts** — Combat system, spells, floor progression
- **prestigeStore.ts** — Prestige/loop system, insight, upgrades
- **discipline-slice.ts** — Discipline activation, XP ticking, perk evaluation
- **uiStore.ts** — UI state, modals, debug settings

**Legacy Store (Migration in Progress):**
- **store.ts** — Legacy monolithic store (reduced)
- **store/** — Legacy store slices being migrated to `stores/`
- **store-modules/** — Legacy store utilities

#### Discipline System (`src/lib/game/`)
- `data/disciplines/` — Per-attunement discipline definitions
- `types/disciplines.ts` — `DisciplineDefinition`, `DisciplineState`, perk types
- `utils/discipline-math.ts` — `calculateStatBonus`, `calculateManaDrain`, perk helpers
- `effects/discipline-effects.ts` — `computeDisciplineEffects()` → feeds `getUnifiedEffects()`
- `stores/discipline-slice.ts` — Zustand store for active discipline state

#### Crafting System (`src/lib/game/crafting-actions/`)
- Modular action files for each crafting stage
- Design, preparation, application, equipment, disenchant actions

#### Constants (`src/lib/game/constants/`)
- Domain-specific constant files: elements, guardians, spells, rooms, prestige
- Barrel exports via `constants/index.ts`

#### Game Data (`src/lib/game/data/`)
- Enchantment effects, equipment types, golems, disciplines, achievements, loot tables
- Organized by domain for easy navigation

### File Size Guidelines

All files kept under **400 lines** (enforced by pre-commit hook).

---

## Appendix: Removed Systems

The following systems no longer exist and should not be re-introduced:

| Removed | Replacement |
|---------|-------------|
| Skill System (study, tiers T1–T5, milestone upgrades) | Discipline System |
| `skillStore.ts` | `discipline-slice.ts` |
| `skill-evolution-modules/` | `data/disciplines/` + `discipline-math.ts` |
| `docs/skills.md` | This document (Discipline System section) |
| `docs/strategy/` | Fully implemented; folder removed |
| Ascension skills | Deleted (no replacement) |
| Scroll crafting | Deleted (violates no-instant-finishing pillar) |
| Lifesteal/healing | Banned permanently |

---

*Document Version: 2.0 — Disciplines Refactor*  
*End of Game Briefing Document*