Mana-Loop/docs/GAME_BRIEFING.md

# Mana-Loop: Comprehensive Game Briefing Document

**Document Version:** 1.1  
**Generated:** Game Systems Analysis  
**Updated:** After Task 2 Completion  

---

## 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. [Skill System](#skill-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)

---

## Executive Summary

**Mana-Loop** is a browser-based incremental/idle game with a 30-day time loop mechanic. Players gather mana, study skills, 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)
- 5-tier skill evolution with milestone upgrade choices
- Time pressure through incursion mechanic
- Guardian pacts provide permanent multipliers

---

## Core Game Loop

### Primary Loop (Within Each Run)

```
┌─────────────────────────────────────────────────────────────┐
│                      TIME LOOP (30 Days)                     │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────┐    ┌──────────┐    ┌───────────┐    ┌───────┐ │
│  │ GATHER  │───▶│  STUDY   │───▶│   CLIMB   │───▶│ CRAFT │ │
│  │  MANA   │    │ SKILLS   │    │   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 |
| **Study** | Learn skills/spells, requires mana cost | Hours per level |
| **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 (disabled for non-enchanted items) | Hours + mana |
| **Enchant** | Apply enchantment to equipment | Hours + mana |

### ActionButtons Rework (Task 2)

**Changes Made:**
- **Manual action selection removed**: Players can no longer manually select actions from a list
- **Auto-transition to Meditate**: After completing Design, Prepare, Enchant, or Craft actions, the game automatically transitions to **Meditate** state
- **Simplified UI**: The ActionButtons component now displays only the current action with a progress indicator
- **Spire Mode integration**: Action buttons are hidden when in Spire Mode (climbing simplified UI)

**Implementation:**
- `currentAction` state tracks the active action
- Crafting slice sets `currentAction: 'meditate'` when actions complete
- `ACTION_CONFIG` maps actions to display configs (label, icon, color)

---

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

**Note:** Fire, Water, Air, and Earth elements are **locked at start**. Only Transference is unlocked initially. Players must unlock the base elements through gameplay (element unlocking system).

### 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.5x after 4 hours
With Meditation Focus skill: 2.5x after 4 hours
With Deep Trance skill: 3.0x after 6 hours
With Void Meditation skill: 5.0x after 8 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

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

**Effects:**
- Reduces mana regeneration by `(1 - incursionStrength)`
- Starts at 0% on Day 20, reaches 95% by Day 30
- Creates urgency to complete objectives before loop ends

---

## 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 // Fixed values
```

**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, always on guardian floors |
| **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 |

### Swarm Room Configuration
```javascript
SWARM_CONFIG = {
  minEnemies: 3,
  maxEnemies: 6,
  hpMultiplier: 0.4,    // Each enemy has 40% of normal HP
  armorBase: 0,
  armorPerFloor: 0.01   // +1% armor per 10 floors
}
```

### Speed Room Configuration
```javascript
SPEED_ROOM_CONFIG = {
  baseDodgeChance: 0.25,   // 25% base
  dodgePerFloor: 0.005,    // +0.5% per floor
  maxDodge: 0.50           // Cap at 50%
}
```

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

**Cast Progress:**
```
progressPerTick = HOURS_PER_TICK × spellCastSpeed × totalAttackSpeed
```

**Spell Cast Speed:**
- Each spell has a `castSpeed` value (casts per hour)
- Higher = faster casting
- Lightning spells get +30% effective cast speed

**Damage Calculation:**
```
baseDamage = spellDamage + (combatTrainLevel × 5)
pctBonus = 1 + (arcaneFuryLevel × 0.1)
elemMastery = 1 + (elementalMasteryLevel × 0.15)
pactMultiplier = product of all signed pact multipliers
elementalBonus = getElementalBonus(spellElement, floorElement)

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

### Elemental Effectiveness

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

**Element Opposites:**
```
Fire ↔ Water
Air ↔ Earth
Light ↔ Dark
Lightning ↔ (none, but has armor pierce)
```

### Armor & Damage Reduction

**Effective Damage:**
```
effectiveArmor = max(0, enemyArmor - armorPierce)
damageDealt = damage × (1 - effectiveArmor)
```

**Armor Pierce Sources:**
- Lightning spells: 20-50% pierce
- Metal spells: 25-60% pierce
- Golems: 15-60% pierce

### Critical Hits

```
critChance = precisionLevel × 0.05
critMultiplier = 1.5 (base)
```

### AOE Mechanics

```
aoeDamage = baseDamage × (1 - 0.1 × (numTargets - 1))
// 10% less damage per additional target
```

### Special Combat Effects

| Effect | Description |
|--------|-------------|
| **Burn** | Damage over time |
| **Freeze** | Prevents dodge (100% freeze = no dodge) |
| **Stun** | Temporary disable |
| **Pierce** | Ignores percentage of armor |
| **Chain** | Hits multiple targets |
| **AOE** | Area damage |
| **Buff** | Damage multiplier |

---

## Guardian & Pact System

### Spire Mode (Task 2)

**New Feature:** A simplified UI mode for climbing the spire.

**How it works:**
- Click **"Climb the Spire"** button (available when not already in Spire Mode)
- Enters simplified UI showing only essential spire info
- Hides ActionButtons and other tabs
- Focuses on combat progression
- Exit condition: Automatically exits when player chooses to stop climbing

**Implementation:**
- `spireMode` boolean state in game store
- `enterSpireMode()` and `exitSpireMode()` actions
- `simpleMode` prop passed to SpireTab for simplified rendering
- UI conditionally renders based on `store.spireMode`

---

### Guardian Floors & Stats

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

### Guardian Boons

When a pact is signed, the guardian grants permanent boons:

| Boon Type | Effect | Example |
|-----------|--------|---------|
| `maxMana` | +Max raw mana | +50 to +500 |
| `manaRegen` | +Regen/hour | +0.5 to +2 |
| `castingSpeed` | +% cast speed | +5% |
| `elementalDamage` | +% element damage | +5% to +20% |
| `rawDamage` | +% all damage | +10% |
| `critChance` | +% crit chance | N/A |
| `critDamage` | +% crit multiplier | +15% |
| `insightGain` | +% insight | +10% to +25% |

### Pact Ritual

**Pact Costs:**
```javascript
pactCost: 500 to 150,000 (raw mana)
pactTime: 2 to 24 (hours for ritual)
```

**Victory Condition:**
- Defeat floor 100 guardian AND sign the pact
- Awards 3x normal insight

---

## Attunement System

### Overview

Attunements are class-like specializations that grant unique capabilities and skill access.

### The Three Attunements

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

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

**Capabilities:**
- Enchanting equipment
- Disenchanting for mana recovery

**Skill Categories Unlocked:**
- `enchant` - Enchanting efficiency
- `effectResearch` - Unlock enchantment effects

---

#### 2. Invoker (Chest) ✅ IMPLEMENTED

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

**Capabilities:**
- Form pacts with guardians
- Access guardian powers
- Elemental mastery through pacts
- Invocation skill tree (T1-T5 with perk choices at L5/L10)
- Pact Mastery skill tree (T1-T5)
- Pact-Weaving hybrid skill (Invoker + Enchanter)

**Skill Categories Unlocked:**
- `invocation` - ✅ Implemented (T1-T5 skill tree)
- `pact` - ✅ Implemented (T1-T5 skill tree)

---

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

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

**Capabilities:**
- Golem crafting
- Gear crafting
- Earth shaping

**Skill Categories Unlocked:**
- `fabrication` - Crafting efficiency
- `golemancy` - Golem control

### Attunement Leveling

**XP Formula:**
```
Level 2: 1,000 XP
Level 3: 2,500 XP
Level 4: 5,000 XP
Level 5: 10,000 XP
Each level: 2× previous (approximately)
Max Level: 10
```

**Level Scaling:**
```
regenMultiplier = 1.5^(level - 1)
conversionRate = baseRate × 1.5^(level - 1)
```

**XP Sources:**
- Enchanting: 1 XP per 10 capacity used

---

## Skill System

### Skill Categories

| Category | Attunement | Description |
|----------|------------|-------------|
| `mana` | Core | Max mana, regen, element cap |
| `study` | Core | Study speed, cost reduction |
| `research` | Core | Click bonuses, advanced meditation |
| `ascension` | Core | Insight, guardian damage |
| `enchant` | Enchanter | Enchanting efficiency |
| `effectResearch` | Enchanter | Unlock enchantment effects |
| `invocation` | Invoker | ✅ Implemented (T1-T5 skill tree) |
| `pact` | Invoker | ✅ Implemented (T1-T5 skill tree) |
| `fabrication` | Fabricator | Crafting speed |
| `golemancy` | Fabricator | Golem control |
| `craft` | Legacy | Basic crafting |

### Core Skills

| Skill | Max | Effect | Study Time |
|-------|-----|--------|------------|
| Mana Well | 10 | +100 max mana/level | 4h |
| Mana Flow | 10 | +1 regen/level | 5h |
| Elem. Attunement | 10 | +50 element cap/level | 4h |
| Mana Overflow | 5 | +25% click mana/level | 6h |
| Quick Learner | 10 | +10% study speed/level | 4h |
| Focused Mind | 10 | -5% study cost/level | 5h |
| Meditation Focus | 1 | 2.5x regen after 4h | 6h |

### Skill Tier Evolution

**5-Tier System:**
```
Tier 1: Base skill (multiplier ×1)
Tier 2: Enhanced (multiplier ×10)
Tier 3: Master (multiplier ×100)
Tier 4: Legendary (multiplier ×1,000)
Tier 5: Mythic (multiplier ×10,000)
```

**Tier Up:**
- Requires max level (10) in current tier
- Unlocks new skill ID (e.g., `manaWell_t2`)

### Milestone Upgrades

**At Level 5 and Level 10:**
- Choose 2 upgrades from 4+ options
- Upgrades can be stat multipliers, bonuses, or special effects
- Some upgrades have upgrade paths

**Example Mana Well Tier 1 Upgrades:**
| Level | Upgrade | Effect |
|-------|---------|--------|
| 5 | Expanded Capacity | +25% max mana |
| 5 | Natural Spring | +0.5 regen |
| 5 | Mana Threshold | +30% max, -10% regen |
| 10 | Deep Reservoir | +50% max (replaces Expanded) |
| 10 | Deep Wellspring | +50% meditation efficiency |

### Enchanter Skills

| Skill | Max | Requirement | Effect |
|-------|-----|-------------|--------|
| Enchanting | 10 | Enchanter 1 | Unlocks enchantment design |
| Efficient Enchant | 5 | Enchanter 2, Enchanting 3 | -5% capacity cost/level |
| Disenchanting | 3 | Enchanter 1, Enchanting 2 | +20% mana recovery/level |
| Enchant Speed | 5 | Enchanter 1, Enchanting 2 | -10% time/level |
| Essence Refining | 5 | Enchanter 2, Enchanting 4 | +10% effect power/level |
| Effect Research (all) | 1 | Enchanter 1+ | Unlock enchantment effects (max:1, no evolution) |

### Golemancy Skills

| Skill | Max | Requirement | Effect |
|-------|-----|-------------|--------|
| Golem Mastery | 5 | Fabricator 2 | +10% golem damage/level |
| Golem Efficiency | 5 | Fabricator 2 | +5% attack speed/level |
| Golem Longevity | 3 | Fabricator 3 | +1 floor duration/level |
| Golem Siphon | 3 | Fabricator 3 | -10% maintenance/level |
| Advanced Golemancy | 1 | Fabricator 5, Mastery 3 | Unlock hybrid golems |

---

### Hybrid Skills

Hybrid Skills are advanced skills that require two attunements and combine their powers.

#### Pact-Weaving (Invoker + Enchanter)

**Requirement:** Invoker 3 + Enchanter 3

**Paths:**
- **Path A: The Weaver** - Enhanced enchantment power through pact bonuses
- **Path B: The Warp** - Unpredictable magic blending pacts and enchantments
- **Path C: The World-Weaver** - Ultimate hybrid combining all powers

**Talent Tree (5 Tiers):**
| Tier | Effect |
|------|--------|
| 1 | +10% enchantment power when pact active |
| 2 | +25% enchantment power when pact active |
| 3 | Pact boons apply to enchanted equipment |
| 4 | +50% enchantment power when pact active |
| 5 | Elite Perk: World-Weaver (all pacts + enchants at max) |

**Elite Perks (Choose at Tier 5):**
- **Eternal Weave:** Enchantments persist through loops
- **Pactbound Power:** All pact multipliers doubled for enchanted items
- **Weaver's Boon:** 25% chance to double enchantment effect

---

#### Guardian Constructs (Fabricator + Invoker)

**Requirement:** Fabricator 3 + Invoker 3

**Paths:**
- **Path A: The Architect** - Durable constructs with enhanced defenses
- **Path B: The Monumentalist** - Massive single construct with supreme power
- **Path C: The Eternal** - Constructs that never expire

**Special Rules:**
- Only **1 active at a time** (replaces golems)
- **More durable** than golems (2x HP, 1.5x duration)
- Uses both Earth and Pact mana for summoning

**Talent Tree (5 Tiers):**
| Tier | Effect |
|------|--------|
| 1 | +25% construct HP |
| 2 | Construct lasts +2 floors |
| 3 | Construct gains pact bonuses |
| 4 | +50% construct damage |
| 5 | Elite Perk: Eternal Construct |

**Elite Perks (Choose at Tier 5):**
- **Living Monument:** Construct HP +500%, never expires
- **Guardian's Might:** Construct gains all pact multipliers
- **Architect's Dream:** Can have 2 constructs (reduces HP by 50% each)

---

#### Enchanted Golemancy (Fabricator + Enchanter)

**Requirement:** Fabricator 3 + Enchanter 3

**Paths:**
- **Path A: The Battle-Smith** - Combat-focused enchanted golems
- **Path B: The Enchanter-Smith** - Golems with powerful enchantments
- **Path C: The Spell-Smith** - Golems that cast elemental spells

**Special Rules:**
- Imbues golems with **elemental spell logic**
- Golems gain spell abilities from enchantments
- Combines golem durability with spell power

**Talent Tree (5 Tiers):**
| Tier | Effect |
|------|--------|
| 1 | Golems gain 1 spell slot |
| 2 | +25% golem spell damage |
| 3 | Golems gain 2 spell slots |
| 4 | +50% golem spell damage |
| 5 | Elite Perk: Spell-Smith |

**Elite Perks (Choose at Tier 5):**
- **Arcane Golem:** Golems cast spells at 3x speed
- **Elemental Master:** Golem spells gain +100% elemental bonus
- **Living Spellforge:** Golems create temporary enchantments

---

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

**Supported:** The game now supports **2-Handed Weapons** (e.g., Staves).

**Mechanics:**
- 2-handed weapons occupy both the `mainHand` and `offHand` slots
- When a 2-handed weapon is equipped in `mainHand`, the `offHand` slot is **blocked**
- 2-handed weapons cannot be equipped to the `offHand` slot
- The UI displays a "2-Handed" badge on applicable items and shows "Blocked by 2-handed weapon" for blocked slots

**Implementation:**
- Equipment types have a `twoHanded: true` property
- `equipItem()` validates 2-handed weapon constraints
- `isSlotBlocked()` function checks if offhand is blocked by main hand 2H weapon

### Equipment Categories

| Category | Slots | Description |
|----------|-------|-------------|
| Caster | Main Hand | Staves and wands for spellcasting |
| Sword | Main Hand | Magic swords with weapon enchants |
| Catalyst | Main Hand | Amplifies magical effects |
| Shield | Off Hand | Defensive equipment |
| Head/Body/Hands/Feet | Respective | Armor pieces |
| Accessory | Accessory1/2 | Rings and amulets |

### Equipment Instance Structure

```typescript
interface EquipmentInstance {
  instanceId: string;      // Unique ID
  typeId: string;          // Reference to EquipmentType
  name: string;
  enchantments: AppliedEnchantment[];
  usedCapacity: number;    // Current capacity used
  totalCapacity: number;   // Max capacity
  rarity: 'common' | 'uncommon' | 'rare' | 'epic' | 'legendary' | 'mythic';
  quality: number;         // 0-100
}
```

### Enchantment Process (3 Stages)

#### Stage 1: Design
- Create enchantment design
- Select effects from unlocked pool
- **Limited to owned gear types** (cannot design for equipment you don't have)
- Calculate capacity cost
- Time: Base 1h + 0.5h per effect stack

**Capacity Cost Formula:**
```
totalCost = Σ(effect.baseCost × (1 + 0.2 × stackIndex) × (1 - efficiencyBonus))
```

#### Stage 2: Prepare
- Prepare equipment for enchanting
- **Disabled for non-enchanted items**
- Mana cost: capacity × 10
- Time: 2h + 1h per 50 capacity
- **Auto-transitions to Meditate** when complete

#### Stage 3: Apply
- Apply enchantment design
- 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** when complete

### 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** | Study, 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 Costs

**Summon Cost (one-time per floor):**
```
Earth Golem: 10 Earth
Steel Golem: 8 Metal + 5 Earth
Crystal Golem: 6 Crystal + 3 Earth
```

**Maintenance Cost (per tick):**
```
Earth Golem: 0.5 Earth/hour
Steel Golem: 0.6 Metal + 0.2 Earth/hour
```

### Golem Duration

```
baseDuration = 1 floor
with Golem Longevity: +1 floor per level (max 4 floors)
```

### Golem Combat

**Attack Progress:**
```
progressPerTick = HOURS_PER_TICK × attackSpeed × efficiencyBonus
```

**Damage:**
```
damage = baseDamage × (1 + golemMastery × 0.1)
```

---

## 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) × skillBonus)
```

### 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 level
- **Memories:** Spells or skills preserved across loops

---

## Achievement System

### Achievement Categories

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

### Achievement Rewards

| Reward Type | 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];
  
  // Base damage
  let damage = spell.dmg + (state.skills.combatTrain || 0) * 5;
  
  // Percentage multipliers
  damage *= 1 + (state.skills.arcaneFury || 0) * 0.1;
  
  // Elemental mastery
  damage *= 1 + (state.skills.elementalMastery || 0) * 0.15;
  
  // Guardian bane (vs guardians only)
  if (isGuardian) {
    damage *= 1 + (state.skills.guardianBane || 0) * 0.2;
  }
  
  // Pact multiplier
  damage *= state.signedPacts.reduce((m, f) => m * GUARDIANS[f].pact, 1);
  
  // Elemental effectiveness
  damage *= getElementalBonus(spell.elem, floorElement);
  
  // Critical hit
  const critChance = (state.skills.precision || 0) * 0.05;
  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);
}
```

### Study Time Calculation

```javascript
effectiveStudyTime = baseStudyTime × tier / studySpeedMultiplier

studySpeedMultiplier = 1 + (quickLearnerLevel × 0.1) + equipmentBonus
```

### Study Cost Calculation

```javascript
effectiveCost = floor(baseCost × (currentLevel + 1) × tier × costMultiplier)

costMultiplier = 1 - (focusedMindLevel × 0.05)
```

### DPS Calculation

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

---

## System Interactions

### Primary Interaction Map

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

### Key System Dependencies

| System | Depends On | Unlocks/Enables |
|--------|------------|-----------------|
| **Skills** | Mana (cost) | All combat/crafting bonuses |
| **Enchanting** | Enchanter attunement, Skills | 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
   - Basic skills (mana, study categories)
   - Starting equipment

2. **Mid Game (Floors 10-40):**
   - First guardian pacts
   - Attunement unlocking
   - Equipment enchanting
   - Golemancy (Fabricator)

3. **Late Game (Floors 40-80):**
   - Compound/exotic elements
   - Hybrid golems
   - Skill tier evolution
   - Advanced enchantments

4. **End Game (Floors 80-100):**
   - Void/Stellar/Crystal spells
   - Ultimate golems
   - Victory preparation

---

## Appendix: Known Issues

### Task 2 Updates (Completed)

The following issues/enhancements were completed in Task 2:

1. **Combat UI Casting Bar** - Fixed progress animation
2. **Mana Well Bug** - Fixed Deep Basin perk (+20% Max Mana, was incorrectly 0.20 instead of 1.20)
3. **LootTab** - Removed Transference from essence list (it's a utility element, not a loot drop)
4. **Ascension Skills** - Deleted from the game (were unused/game design change)
5. **Show Component Names** - Fixed debug option to properly display component names in UI
6. **DebugTab** - Added Invoker Debugging Buttons for Pacts (`PactDebug` component)

### Missing Implementations

1. **Field Repair** - Skill exists, no repair system

### Removed Content

1. **Scroll Crafting** - Removed (violates NO INSTANT FINISHING pillar)
2. **Temporal Memory** - Removed (replaced by better mechanics)
3. **Ascension Skills** - Deleted (Task 2)
4. **Transference from LootTab** - Removed (Task 2, not a lootable essence)

### Balance Concerns

1. Exotic elements require extreme mana investment
2. Incursion creates hard time pressure without counterplay
3. Equipment progression limited after starting gear

---

*Document Version: 1.1 (Updated after Task 2 completion)*
*End of Game Briefing Document*