Anexim/Mana-Loop
1
1
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1a0886f70266df254865e34ac5c1e3a1782298c9
Mana-Loop/docs/GAME_BRIEFING.md
T
n8n-gitea 1a0886f702
Build and Publish Mana Loop Docker Image / build-and-publish (push) Successful in 1m19s
Details
chore: golemancy redesign cleanup — remove orphaned legacy code and update docs
2026-06-07 12:54:12 +02:00

49 KiB
Raw Blame History

Mana-Loop: Comprehensive Game Briefing Document

Document Version: 4.0 Updated: Post-refactoring — 22 mana types, 8-tier guardian system, 64 disciplines, 14 prestige upgrades, 43 equipment types, 8 Zustand stores, localStorage-only

Table of Contents

  1. Executive Summary
  2. Core Game Loop
  3. Mana System
  4. Time & Incursion System
  5. Spire & Floor System
  6. Combat System
  7. Guardian System
  8. Attunement System
  9. Discipline System
  10. Equipment & Enchantment System
  11. Golemancy System
  12. Prestige/Loop System
  13. Achievement System
  14. Formulas & Calculations
  15. System Interactions
  16. 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 procedurally-tiered guardians, sign pacts, enchant equipment, summon golems, and prestige for permanent progression.

Key Differentiators:

  • 3-class Attunement system (Enchanter, Invoker, Fabricator)
  • Equipment-based spell system (spells come from enchanted gear and learned spells)
  • Practice-based Discipline system — no discrete skill levels, only continuous XP growth
  • Time pressure through the incursion mechanic (starts day 20)
  • Guardian progression: base (10-80) → composite (90-160) → exotic (170-240) → combo bosses (250+, 8 tiers)
  • Guardian pacts provide permanent multipliers that persist through prestige
  • No backend — pure client-side with localStorage persistence

Code Architecture: 8 modular Zustand stores, crafting actions, discipline data, and constants. No legacy store files remain.

Core Game Loop

Primary Loop (Within Each Run)

┌─────────────────────────────────────────────────────────────┐
│                      TIME LOOP (30 Days)                     │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────┐    ┌────────────┐    ┌───────────┐    ┌──────┐ │
│  │ GATHER  │───▶│  PRACTICE  │───▶│   CLIMB   │───▶│CRAFT │ │
│  │  MANA   │    │ DISCIPLINES│    │   SPIRE   │    │ GEAR │ │
│  └─────────┘    └────────────┘    └───────────┘    └──────┘ │
│       │               │                │               │    │
│       └───────────────┴────────────────┴───────────────┘    │
│                            │                                 │
│                            ▼                                 │
│  ┌─────────────────────────────────────────────────────┐   │
│  │     DEFEAT GUARDIANS → SIGN PACTS (every 10th)      │   │
│  │     Base(10-80) → Composite(90-160) → Exotic(170-240)│  │
│  │     → Combo Bosses(250+, 8 tiers)                    │   │
│  └─────────────────────────────────────────────────────┘   │
│                            │                                 │
│                            ▼                                 │
│  ┌─────────────────────────────────────────────────────┐   │
│  │           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 (Design/Prepare/Apply) Hours per stage
Convert Auto-convert raw mana to elements Per tick
Design Create enchantment designs 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 the combat store

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 via guardian pacts │
    │                                                           │
    ├──▶ Utility Element (1) ───────────────────────────────────┤
    │    Transference (Enchanter attunement — UNLOCKED at start)│
    │                                                           │
    ├──▶ Composite Elements (8) ── Created from 2 base ────────┤
    │    Metal = Fire + Earth                                   │
    │    Sand  = Earth + Water                                  │
    │    Lightning = Fire + Air                                 │
    │    Frost = Air + Water                                    │
    │    BlackFlame = Dark + Fire                               │
    │    Radiant Flames = Light + Fire                          │
    │    Miasma = Air + Death                                   │
    │    Shadow Glass = Earth + Dark                            │
    │                                                           │
    └──▶ Exotic Elements (6) ── Created from advanced recipes ──┤
         Crystal = Sand + Sand + Light                          │
         Stellar = Plasma + Light + Fire                        │
         Void    = Dark + Dark + Death                          │
         Soul = Light + Dark + Transference                     │
         Time = Soul + Sand + Transference                       │
         Plasma = Lightning + Fire + Transference                │

Only Transference is unlocked at start. All other elements must be unlocked through guardian pacts.

Mana Formulas

Maximum Raw Mana:

base = 100 + (manaWell_prestige × 500) + disciplineMaxManaBonus
final = (base + equipmentMaxManaBonus) × equipmentMaxManaMultiplier

Maximum Elemental Mana:

elementMax = (10 + (elemAttune_prestige × 25)) × elementCapMultiplier

Base Regeneration (per hour):

base = 2 + (manaFlow_prestige × 0.5)
temporalMult = 1 + (temporalEcho_prestige × 0.1)
regen = base × temporalMult + attunementRegen + disciplineRegenBonus
final = (regen + equipmentRegenBonus) × equipmentRegenMultiplier

Effective Regen (per tick):

effectiveRegen = max(0, baseRegen × (1 - incursionStrength) × meditationMultiplier - totalConversionPerTick)

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 1.5^level)
  • Fabricator: Raw → Earth at 0.25/hour base (scales with 1.5^level)
  • Invoker: No automatic conversion (gains mana from pacts)

Mana Conversion Cost

  • 100 Raw Mana = 1 Elemental Mana (for base elements)
  • Composite/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)
  where totalHours = (day - 20) × 24 + hour
        maxHours   = (30 - 20) × 24 = 240

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

Spire & Floor System

Floor Element Cycle

FLOOR_ELEM_CYCLE = [fire, water, air, earth, light, dark, death]
element = FLOOR_ELEM_CYCLE[(floor - 1) % 7]

Floor HP Formulas

Normal floors:

HP = floor(100 + floor × 50 + floor^1.7)

Guardian floors:

HP = floor(5000 × (floor/10) ^ (1.1 + floor/200))

Room Types

Room Type Chance Description
Guardian Every 10th floor Boss encounter
Puzzle 100% on every 7th floor (except guardian floors) Attunement-themed trial
Swarm ~12% 3–7 weak enemies
Speed ~10% Single enemy with elevated dodge chance
Combat ~68% (default) Single enemy, normal combat
Recovery ~4% 1 hour; grants 10× mana regen & conversion
Treasure ~3% 1 hour; grants 2–15 random items
Library ~3% 1 hour; grants discipline XP at 25× rate

Puzzle Room Types

  • Single attunement: enchanter_trial, fabricator_trial, invoker_trial
  • Dual attunement: hybrid_enchanter_fabricator, hybrid_enchanter_invoker, hybrid_fabricator_invoker
  • Base progress: 1.5–2% per tick; attunement bonus: 2.5–3% per relevant attunement level

Enemy Modifiers (Non-Guardian Floors)

Modifier Min Floor Effect Scaling
Armored 5+ Armor (damage reduction) 10%–45%, scales with floor
Agile 12+ Dodge chance 20% base + 0.4%/floor, max 55%
Mage 15+ Barrier (shield HP) Up to 40% of max HP, recharges 5%/tick
Shield 10+ One-time shield 15% of max HP
Swarm 8+ Multiple weaker enemies 3–7 enemies, each 35% HP

Max 2 modifiers per enemy. Low floors (1–4) get no modifiers.

Armor Scaling (Non-Guardian)

  • No armor below floor 10
  • Armor chance: min(0.5, (floor - 10) × 0.01)
  • Armor value: 5%–25% damage reduction, scaling with floor progress

Combat System

Spell Casting Mechanics

castProgress += HOURS_PER_TICK × spellCastSpeed × attackSpeedMultiplier
When castProgress >= 1: deduct mana, deal damage, reset progress

Damage Calculation

baseDmg = spell.dmg + disciplineBaseDmgBonus
pctMult = 1 + disciplineDmgMult
elemMasteryMult = 1 + (elementalMastery × 0.15)
guardianBaneMult = 1 + (guardianBane × 0.2)  [guardian floors only]
rawDmgMult = 1 + boonRawDamage / 100
elemDmgMult = 1 + boonElementalDamage / 100

damage = baseDmg × pctMult × elemMasteryMult × guardianBaneMult × rawDmgMult × elemDmgMult
damage *= getElementalBonus(spellElement, floorElement)

// Critical hit
critChance = disciplineCritChance + boonCritChance / 100
critDmgMult = 1.5 + boonCritDamage / 100
if (random() < critChance) damage *= critDmgMult

// Special modifiers
if (floorHP / floorMaxHP < 0.25) damage *= 2    // Executioner
if (rawMana < maxMana × 0.5) damage *= 1.5      // Berserker

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

Elemental Effectiveness

Condition Multiplier
Spell opposes floor element (super effective) 1.50×
Spell matches floor element 1.25×
Spell's opposite matches floor (not very effective) 0.75×
Neutral / Raw mana spells 1.00×

Element Opposites (bidirectional):

Fire ↔ Water     Air ↔ Earth     Light ↔ Dark
Frost ↔ Fire

Element Counters (directional):

Lightning → Water    Earth → Lightning

Composite Element Counters (bidirectional):

BlackFlame ↔ Frost, Water, Light
Radiant Flames ↔ Frost, Water, Dark
Miasma ↔ Air
Shadow Glass ↔ Light

Spell Tiers

Tier Category Example Spells
0 Raw Mana Bolt (5 dmg), Mana Strike (8 dmg)
1 Basic Elemental Fireball, Water Jet, Gust, Stone Bullet, Light Lance, Shadow Bolt, Drain
1 Lightning Spark, Lightning Bolt, Chain Lightning, Storm Call
1 Compound Metal Shard, Iron Fist, Sand Blast, Sandstorm
1 Compound+ Frost Bolt, BlackFlame Bolt, Cursed Flame, Toxic Cloud, Shadow Spike
1 AOE Fireball AOE, Frost Nova, Meteor Shower, Blizzard
1 Utility Transfer Strike, Mana Rip, Essence Drain
2 Advanced Inferno, Tidal Wave, Earthquake, Hurricane
3 Master Pyroclasm, Tsunami, Meteor Strike, Heaven Light, Oblivion
3 Compound Master Furnace Blast, Dune Collapse
4 Legendary Stellar Nova, Void Collapse, Crystal Shatter, Soul Rend, Time Warp, Plasma Cannon

Spell Effects

  • burn: Damage over time
  • freeze: Prevents dodge
  • chain: Hits additional targets
  • aoe: Area of effect
  • armor_pierce: Ignores percentage of armor
  • stun, pierce, multicast, shield, buff

Guardian System

Guardian Tiers

Tier 1 — Base Elements (Floors 10–80)

Floor Name Element Armor Pact Mult Pact Cost Pact Time
10 Ignis Prime fire 10% 1.5× formula 2h
20 Aqua Regia water 15% 1.75× formula 4h
30 Ventus Rex air 20% 2.0× formula 6h
40 Terra Firma earth 25% 2.25× formula 8h
50 Lux Aeterna light 30% 2.5× formula 10h
60 Umbra Mortis dark 35% 2.75× formula 12h
70 Mors Ultima death 40% 3.0× formula 14h
80 Vinculum Arcana transference 45% 3.25× formula 16h

Tier 1 Formulas:

  • Pact Cost: floor(hp × 0.3 + power × 5 + hp × armor × 0.5 + shield × 2 + hp × barrier × 0.3)
  • Pact Time: 2 + floor(floor / 10) hours
  • Armor: Starts at 10% on floor 10, increases by 5% per 10th floor

Tier 2 — Composite Elements (Floors 90–160)

Floor Element Armor Pact Mult Pact Cost Pact Time
90 metal 50% 3.5× formula 18h
100 sand+fire+earth 55% 3.75× formula 20h
110 lightning 60% 4.0× formula 22h
120 frost 65% 4.25× formula 24h
130 metal+fire+earth (blackflame) 70% 4.5× formula 26h
140 sand+earth+water (radiantflames) 75% 4.75× formula 28h
150 lightning+fire+air (miasma) 80% 5.0× formula 30h
160 shadowglass 85% 5.25× formula 32h

Tier 2 Formulas:

  • Pact Cost: Same formula as Tier 1
  • Pact Time: 2 + floor(floor / 10) hours
  • Armor: Starts at 50% on floor 90, increases by 5% per 10th floor (capped at 90%)
  • Note: Floor 100 guardian element is sand+fire+earth (composite components), Floor 140 is sand+earth+water, Floor 150 is lightning+fire+air

Tier 3 — Exotic Elements (Floors 170–240)

Floor Element Armor Pact Mult Pact Cost Pact Time
170 crystal 35% 5.5× formula 37h
180 stellar 30% 6.0× formula 38h
190 void 35% 6.5× formula 39h
200 crystal+stellar+void 35% 7.0× formula 40h
210 soul+time+plasma 32% 7.5× formula 41h
220 plasma 28% 8.0× formula 42h
230 crystal+stellar+void 40% 8.5× formula 43h
240 soul+time+plasma 42% 9.0× formula 44h

Tier 3 Formulas:

  • Pact Cost: Same formula as Tier 1
  • Pact Time: 2 + floor(floor / 10) hours
  • Armor: Varies per guardian (see code for exact values)
  • Note: Floor 200 is crystal+stellar+void, Floor 210 is soul+time+plasma (matching the code in guardian-data.ts)

Floors 90–240 have procedurally generated names via generateGuardianName().

Tier 4 — Dual Element Pairs (Floors 250–280)

Nine dual-element combinations cycle every 10 floors:

Combo Index Elements Theme
0 fire + water Steam
1 fire + air Smoke
2 water + earth Mud
3 light + dark Twilight
4 death + light Undeath
5 fire + death Hellfire
6 water + dark Abyssal
7 air + light Radiant wind
8 earth + death Fossil

Tiers 5–8 — Scaling Combo Bosses (Floors 290+)

  • Tier 5 (290–330): Dual composite + components
  • Tier 6 (340–380): Exotic + components
  • Tier 7 (390–430): Exotic + composite + components
  • Tier 8 (440+): Full fusion — 1 exotic + 2 composites + all base elements

Scaling (per tier):

armor           = min(0.7, 0.30 + floor_increment × 0.002-0.003)
pactMultiplier  = 7.5+ (scales with tier)
pactTime        = 20+ hours (scales with tier)
damageMult      = 3.5+ (scales with tier)
insightMult     = 3.0+ (scales with tier)

Combo guardians grant boons to both elements (+10% each) and dual-aspect perks (+20% effectiveness to both element spells). Names generated from combined prefixes (e.g., "Ignis-Aqua the Warden").

Guardian HP Formula (All Tiers)

HP(floor) = floor(5000 × (floor/10) ^ (1.1 + floor/200))

Guardian Combat Effects

Element Passive Effect
fire burn (0.1)
water armor_pierce (0.15)
air cast_speed (0.05)
earth armor_pierce (0.2)
light crit_chance (0.1)
dark crit_damage (0.15)
death raw_damage (0.1)
transference cost_reduction (0.25)
metal armor_pierce (0.2)
sand slow (0.25)
lightning chain (2)
crystal reflect (0.15)
stellar night_bonus (0.3)
void resist_ignore (0.4)
frost freeze (0.2)
blackflame curse+burn (0.15+0.15)
radiantflames blind+burn (0.15+0.1)
miasma corrosion+poison (0.2+0.15)
shadowglass armor_pierce+pierce (0.3+0.25)
soul defense_pierce (0.5), mana_drain (0.2)
time slow (0.3), temporal_snap (0.15)
plasma chain (3), burn (0.1)

Guardian Boons (on pact)

Each guardian grants 2 boons from: maxMana, manaRegen, castingSpeed, elementalDamage, rawDamage, critChance, critDamage, spellEfficiency, manaGain, insightGain, prestigeInsight.

Pact Ritual

  1. Defeat guardian → floor added to defeatedGuardians
  2. Start ritual: costs raw mana + time (guardian-specific)
  3. Progress increases by HOURS_PER_TICK per tick
  4. On completion: floor moves to signedPacts, boons applied
  5. Pact slots limit simultaneous signed pacts (starting 1, upgradeable)

Victory Condition

No specific victory condition is currently defined. The loop ends when day 30 is reached (or floor 30 for early completion). A victory condition with a ×3 multiplier is awaiting design finalization.

Signed pacts do NOT persist through prestige — the player must re-defeat Guardians and re-sign pacts each loop.

Attunement System

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

The Three Attunements

1. Enchanter (Right Hand) — Starting

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

Disciplines: 10 disciplines across 4 files (core: 4, utility: 2, spells: 3, special: 1) Capabilities: Enchanting & disenchanting equipment

2. Invoker (Chest) — Locked

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

Disciplines: 2 disciplines (Spell Casting, Void Manipulation) Capabilities: Form pacts with guardians, access guardian powers

3. Fabricator (Left Hand) — Locked

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: 5 disciplines (Golem Crafting, Crafting Efficiency, Study Fabricator Recipes, Study Wizard Equipment, Study Physical Equipment) Capabilities: Golem crafting, gear crafting, Earth shaping

Attunement Leveling

Level 2: 1,000 XP
Level 3: 2,500 XP
Level 4+: 1000 × 2^(level-2) × 1.25
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 — disciplines grow continuously through practice. The player activates a discipline and it drains mana each tick in exchange for permanent stat growth within the run.

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

Formulas

Stat Bonus (continuous):

StatBonus = baseValue × (XP / scalingFactor)^0.65

Mana Drain Per Tick:

ManaDrainPerTick = drainBase × (1 + (XP / difficultyFactor)^0.4)

Concurrent Discipline Limit

concurrentLimit = min(1 + floor(totalXP / 500), 4)

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)

Discipline Pools (64 Total)

Pool File Count Requires
Base base.ts 3 None
Elemental Attunement elemental.ts 21 None
Elemental Regen elemental-regen.ts 8 None
Advanced Regen elemental-regen-advanced.ts 15 Mana type unlocked
Enchanter Core enchanter.ts 4 Enchanter attunement
Enchanter Utility enchanter-utility.ts 2 Enchanter attunement
Enchanter Spells enchanter-spells.ts 3 Enchanter attunement
Enchanter Special enchanter-special.ts 1 Enchanter attunement
Invoker invoker.ts 2 Invoker attunement
Fabricator fabricator.ts 5 Fabricator attunement
Total 64

Example Disciplines

Discipline Pool Mana Type Stat Bonus Description
Raw Mana Mastery Base raw maxManaBonus More raw mana from practice
Elemental Attunement (×7) Elemental per element elementCap_{type} Expanded element capacity
Elemental Regen (×8) Regen per element regen_{type} Passive element regen
Advanced Regen (×6) Adv. Regen composite/exotic regen_{type} Composite/exotic regen
Enchantment Crafting Enchanter transference enchantPower Stronger enchantments
Study Basic Weapon Enchantments Enchanter fire — Unlocks sword_fire, sword_frost, sword_lightning
Study Advanced Weapon Enchantments Enchanter dark — Unlocks sword_void, damage_5, crit_5, attack_speed_10
Study Utility Enchantments Enchanter light — Unlocks meditate_10, study_10, insight_5
Study Mana Enchantments Enchanter water — Unlocks mana_cap_50, mana_cap_100, mana_regen_1/2, click_mana_1/3
Study Basic Spell Enchantments Enchanter air — Unlocks 8 basic spell enchants
Study Intermediate Spell Enchantments Enchanter earth — Unlocks 6 intermediate spell enchants
Study Advanced Spell Enchantments Enchanter dark — Unlocks 10 master spell enchants
Study Special Enchantments Enchanter death — Unlocks spell_echo_10, guardian_dmg_10, overpower_80, etc.
Spell Casting Invoker light baseDamage +Base damage
Void Manipulation Invoker void baseDamageMult +Base damage multiplier
Golem Crafting Fabricator earth golemCapacity +Golem capacity
Crafting Efficiency Fabricator sand craftCostReduction -Crafting costs

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)

Equipment & Enchantment System

Equipment Slots (8)

mainHand   - Casters (some 2H), Swords, Catalysts
offHand    - Catalysts, Spell Focuses (blocked by 2-handed weapons)
head       - Hoods, Hats, Helms
body       - Robes, Armor
hands      - Gloves, Gauntlets
feet       - Boots, Shoes
accessory1 - Rings, Amulets
accessory2 - Rings, Amulets

Equipment Categories & Types (43 total)

Category Slot Count Examples
Casters mainHand 6 Basic Staff (2H), Apprentice Wand, Oak Staff (2H), Crystal Wand, Arcanist Staff (2H), Battlestaff (2H)
Swords mainHand 5 Iron Blade, Steel Blade, Crystal Blade, Arcanist Blade, Void-Touched Blade
Catalysts mainHand/offHand 4 Basic Catalyst, Fire Catalyst, Void Catalyst, Metal Spell Focus
Body body 5 Civilian Shirt, Apprentice Robe, Scholar Robe, Battle Robe, Arcanist Robe
Head head 5 Cloth Hood, Apprentice Cap, Wizard Hat, Arcanist Circlet, Battle Helm
Hands hands 4 Civilian Gloves, Apprentice Gloves, Spellweave Gloves, Combat Gauntlets
Feet feet 4 Civilian Shoes, Apprentice Boots, Traveler Boots, Battle Boots
Accessories accessory1/2 10 Copper Ring, Silver Ring, Gold Ring, Signet Ring, Copper Amulet, Silver Amulet, Crystal Pendant, Mana Brooch, Arcanist Pendant, Void-Touched Ring

Total: 43 equipment types across 8 categories. Shields are banned. Catalysts can be equipped in offHand slot.

Two-Handed Weapons

2H weapons (Basic Staff, Oak Staff, Arcanist Staff, Battlestaff) occupy both mainHand and offHand. The offhand slot is blocked when a 2H weapon is equipped.

Equipment Instance Structure

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/enchantments/)
  • Name the design, choose equipment type
  • Time: 1h base + 0.5h per effect stack
  • Dual design slot available with Enchant Mastery special
  • 10% chance per tick for instant completion (Instant Designs special)
  • Implemented in crafting-design.ts / design-actions.ts

Stage 2: Prepare

  • Equipment must be equipped
  • Removes all existing enchantments (confirmation dialog if enchanted)
  • Mana cost: totalCapacity × 10
  • Time: 2h + floor(totalCapacity / 50) hours
  • Auto-transitions to Meditate on complete
  • ONLY stage where explicit disenchanting is possible
  • Implemented in crafting-prep.ts / preparation-actions.ts

Stage 3: Apply

  • Equipment must have "Ready for Enchantment" tag
  • Select a saved design to apply
  • Time: 2h + sum(stacks) hours
  • Mana per hour: 20 + 5 × sum(stacks)
  • Free enchant chances: Enchant Preservation (25%), Thrifty Enchanter (10%), Optimized Enchanting (25%)
  • Pure Essence special: effects with base cost < 100 get 1.25× stacks
  • Cannot re-enchant already enchanted gear (must Prepare first)
  • Implemented in crafting-apply.ts / application-actions.ts

Enchantment Effect Categories

Category File Equipment Types Example Effects
Mana mana-effects.ts Most mana_cap_50, mana_regen_1, click_mana_1, {element}_cap_10/25/50
Combat combat-effects.ts Casters, Hands damage_5, damage_10, damage_pct_10, crit_5, attack_speed_10
Elemental elemental-effects.ts Casters, Swords sword_fire, sword_frost, sword_lightning, sword_void
Special special-effects.ts Various spell_echo_10, guardian_dmg_10, overpower_80, first_strike, combo_master, adrenaline_rush
Utility utility-effects.ts Most meditate_10, study_10, insight_5
Spell spell-effects/ Casters only manaBolt, fireball, inferno, pyroclasm, stellarNova, etc. (~40+ spells)
Defense defense-effects.ts — Placeholder (empty)

Capacity & Stacking

  • Each equipment type has baseCapacity (15–80)
  • Each enchantment effect has baseCapacityCost per stack
  • Stacking cost: each additional stack costs 20% more: cost × (1 + i × 0.2) for stack index i
  • Efficiency bonus reduces total cost: totalCost × (1 - efficiencyBonus)

Disenchanting

  • Only possible during Prepare stage (or via explicit disenchant action)
  • Recovery rate: 0.1 + disenchantLevel × 0.2 (base 10% + 20% per level)
  • Clears all enchantments, resets usedCapacity to 0

Starting Equipment

Slot Item Enchantment Capacity
Main Hand Basic Staff (2H) Mana Bolt spell 50/50
Body Civilian Shirt None 0/30
Feet Civilian Shoes None 0/15

Golemancy System

Golem Slots

slots = floor(fabricatorLevel / 2)   [minimum 0]
Level 2: 1 slot
Level 4: 2 slots
Level 6: 3 slots
Level 8: 4 slots
Level 10: 5 slots

Component-Based Construction

Golems are designed by assembling three mandatory components plus optional enchantments:

Component Role Count Examples
Core Power source: mana types, capacity, regen, upkeep, duration 4 (Basic, Intermediate, Advanced, Guardian) Basic Core (Earth only), Guardian Core (all guardian mana types)
Frame Combat stats: damage, speed, armor pierce, magic affinity, special 7 (Earth, Sand, Frost, Crystal, Steel, Shadowglass, Crystal-Steel Hybrid) Earth (balanced), Shadowglass (fast + AoE), Crystal-Steel Hybrid (guardian constructs)
Mind Circuit Behavior: basic attacks, spell casting, spell cycling 4 (Simple, Intermediate, Advanced, Guardian) Simple (basic only), Guardian (cycle all spells)
Enchantments Sword effects on basic attacks (optional) 8 Burn, Slow, Shock, Weaken, Armor Pierce, Crit Chance

Player upkeep formula:

Upkeep per hour = Core.manaRegen × 2

Golems last Core.maxRoomDuration rooms (3–8 depending on core tier). Stats are derived from components via computeGolemStats().

Prestige/Loop System

Loop End Conditions

Condition Result
Day 30 reached Loop ends, gain insight
Floor 30 reached Loop ends early, gain insight

Insight Formula

skillBonus = 1 + (insightHarvest × 0.1) + disciplineInsightBonus
boonInsightMult = 1 + boonInsightGain / 100
mult = (1 + insightAmp × 0.25) × skillBonus × boonInsightMult

baseInsight = floor(maxFloorReached × 15 + totalManaGathered / 500 + signedPacts.length × 150 + prestigeInsightBonus)
finalInsight = floor(baseInsight × mult)

Note: There is currently no specific victory condition or ×3 multiplier. These are awaiting design finalization.

Prestige Upgrades (14 Types)

ID Name Description Max Level Cost
manaWell Mana Well +500 starting max mana 5 500
manaFlow Mana Flow +0.5 regen/sec permanently 10 750
insightAmp Insight Amp +25% insight gain 4 1500
spireKey Spire Key Start at floor +2 5 4000
temporalEcho Temporal Echo +10% mana generation 5 3000
steadyHand Steady Hand -15% durability loss 5 1200
ancientKnowledge Ancient Knowledge Start with blueprint discovered 5 2000
elementalAttune Elemental Attunement +25 elemental mana cap 10 600
spellMemory Spell Memory Start with random spell learned 3 2500
guardianPact Guardian Pact +10% pact multiplier 5 3500
quickStart Quick Start Start with 100 raw mana 3 400
elemStart Elem. Start Start with 5 of each unlocked element 3 800
unlockedManaTypeCapacity Mana Type Capacity +10 capacity for selected mana type 5 1000
pactBinding Pact Binding +1 pact slot per level 5 2000

Pact Persistence

  • Signed pacts do NOT persist through prestige — the player must re-defeat Guardians and re-sign pacts each loop.
  • pactSlots starting value: 1 (upgradeable via pactBinding prestige upgrade)
  • pactSlots starting value: 1 (upgradeable)

Achievement System

Categories (24 Total)

Category Count Examples
Combat (9) First Blood (floor 2), Floor Climber (10), Spire Assault (25), Tower Conqueror (50), Spire Master (75), Apex Reached (100), Heavy Hitter (100 dmg), Devastating Blow (1K dmg), Apocalypse Now (10K dmg)
Progression (3) Pact Seeker (1 pact), Pact Collector (5), Pact Master (9)
Magic (6) Spell Caster/Weaver/Storm (100/1K/10K spells), Mana Pool/Lake/Ocean (1K/100K/10M mana)
Crafting (3) Enchanter (1 craft), Master Enchanter (10), Legendary Enchanter (50)
Special (3) Speed Runner (floor 50 < 5 days, hidden), Perfectionist (floor 100 no pacts, hidden), Survivor (loop during full incursion day 30+)

Reward Types

Reward Effect
insight One-time insight bonus (10–1000)
manaBonus Permanent max mana (10–200)
damageBonus Permanent damage increase (3%–25%)
regenBonus Permanent regen increase (0.5–1)
title Cosmetic title
unlockEffect Unlocks game effect

Hidden Achievements

  • 2 hidden achievements: Speed Runner and Perfectionist
  • Revealed when player reaches 50% progress toward requirement

Formulas & Calculations

Damage Calculation (Complete)

baseDmg = spell.dmg + disciplineBaseDmgBonus
pctMult = 1 + disciplineDmgMult
elemMasteryMult = 1 + (elementalMastery × 0.15)
guardianBaneMult = 1 + (guardianBane × 0.2)  [guardian floors only]
rawDmgMult = 1 + boonRawDamage / 100
elemDmgMult = 1 + boonElementalDamage / 100

damage = baseDmg × pctMult × elemMasteryMult × guardianBaneMult × rawDmgMult × elemDmgMult
damage *= getElementalBonus(spellElement, floorElement)

// Critical hit
critChance = disciplineCritChance + boonCritChance / 100
critDmgMult = 1.5 + boonCritDamage / 100
if (random() < critChance) damage *= critDmgMult

// Special modifiers
if (floorHP / floorMaxHP < 0.25) damage *= 2    // Executioner
if (rawMana < maxMana × 0.5) damage *= 1.5      // Berserker

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

return floor(damage)

DPS Calculation

dps = damage × castSpeed × attackSpeedMultiplier

Elemental Bonus Lookup

getElementalBonus(spellElement, floorElement):
  if spell == floor: return 1.25 (same element)
  if spell opposes floor: return 1.50 (super effective)
  if floor opposes spell: return 0.75 (not very effective)
  return 1.00 (neutral)

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, pact persistence
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–240): All 8 composite elements, all 6 exotic elements, hybrid golems, advanced discipline perks, advanced enchantments, all guardian tiers
  4. End Game (Floors 250+): Procedural combination bosses with dual/multi elements, indefinite scaling

Code Architecture

Modular Structure Overview

Store Architecture (8 Zustand Stores)

Active Stores (src/lib/game/stores/):

  • gameStore.ts — Coordinator/tick pipeline, combines all stores
  • manaStore.ts — Mana pools, regen, element conversion
  • combatStore.ts — Spire/floors, combat, spells, achievements
  • craftingStore.ts — Enchanting (Design/Prepare/Apply), equipment instances, loot
  • attunementStore.ts — Enchanter/Invoker/Fabricator attunement levels & XP
  • prestigeStore.ts — Insight, prestige upgrades, pact persistence, loop state
  • discipline-slice.ts — Discipline activation, XP ticking, perk evaluation
  • uiStore.ts — Logs, pause, game over/victory flags

(Note: useDisciplineStore is exported from discipline-slice.ts, making it the 8th store.)

Supporting store files:

  • tick-pipeline.ts — buildTickContext() / applyTickWrites() pattern
  • combat-actions.ts — Combat tick processing
  • gameLoopActions.ts — Climb/spire actions
  • gameHooks.ts — React hooks bound to stores
  • craftingStore.types.ts — Crafting type definitions
  • crafting-initial-state.ts — Default crafting state
  • combat-state.types.ts — Combat type definitions

No legacy store files remain. The old store.ts, store/, and store-modules/ directories have been fully removed.

Data Layer (src/lib/game/data/)

  • disciplines/ — 11 files: per-attunement discipline definitions (64 disciplines total)
  • enchantments/ — 7 files + spell-effects/ subdirectory: enchantment effects by category
  • equipment/ — 13 files: equipment type definitions by slot
  • golems/ — 7 files: golem definitions (base, elemental, hybrid)
  • guardian-data.ts — Static guardian definitions (floors 10–240)
  • guardian-encounters.ts — Procedural guardian lookup & combo bosses (250+, 8 tiers)
  • attunements.ts — Attunement definitions
  • achievements.ts — Achievement definitions (24 achievements)
  • crafting-recipes.ts / fabricator-recipes.ts — Crafting recipes
  • loot-drops.ts — Loot drop tables
  • enchantment-effects.ts / enchantment-types.ts — Enchantment metadata

Constants (src/lib/game/constants/)

  • core.ts — Tick rate, caps, time constants
  • elements.ts — Element definitions, opposites, floor cycle
  • prestige.ts — Prestige upgrade definitions
  • rooms.ts — Room type configs (armor, speed, swarm, puzzle)
  • spells.ts — Spell constants barrel
  • spells-modules/ — 15 files: spell definitions by category (raw, basic, advanced, master, legendary, lightning, compound, compound+, frost, blackflame, radiantflames, miasma, shadowglass, AOE, utility, enchantment, plasma, soul, time)

Types (src/lib/game/types/)

  • game.ts — Core game types (GameState, ActivityLogEntry, etc.)
  • disciplines.ts — Discipline definition types
  • attunements.ts — Attunement types
  • equipment.ts — Equipment instance types
  • equipmentSlot.ts — Equipment slot enum
  • elements.ts — Element type definitions
  • spells.ts — Spell types

Utilities (src/lib/game/utils/)

  • combat-utils.ts — Damage calculation, elemental bonuses, insight formula
  • spire-utils.ts — Spire/floor progression
  • mana-utils.ts — Mana calculation helpers
  • enemy-generator.ts — Enemy spawning with modifiers
  • discipline-math.ts — Discipline XP/drain/perk formulas
  • room-utils.ts — Room type generation
  • enemy-utils.ts — Enemy stat calculations
  • pact-utils.ts — Guardian pact helpers
  • floor-utils.ts — Floor HP calculations
  • formatting.ts — Number/time formatting
  • activity-log.ts — Activity log helper
  • result.ts — Result/Either type
  • safe-persist.ts — Safe localStorage persistence

Effects (src/lib/game/effects/)

  • discipline-effects.ts — Discipline → stat bonuses/multipliers/specials
  • dynamic-compute.ts — Dynamic stat computation
  • special-effects.ts — Special one-off effects
  • upgrade-effects.ts — Upgrade effect application
  • upgrade-effects.types.ts — Types for upgrade effects

Top-Level Game Logic (src/lib/game/)

  • effects.ts — Unified effects orchestration (merges equipment + discipline + upgrade effects)
  • crafting-design.ts — Enchantment design logic
  • crafting-prep.ts — Preparation logic
  • crafting-apply.ts — Application logic
  • crafting-equipment.ts — Equipment crafting logic
  • crafting-loot.ts — Loot generation from crafting
  • crafting-utils.ts — Shared crafting utilities
  • crafting-attunements.ts — Attunement-crafting integration

Crafting Actions (src/lib/game/crafting-actions/)

  • design-actions.ts — Design stage actions
  • preparation-actions.ts — Preparation stage actions
  • application-actions.ts — Application stage actions
  • crafting-equipment-actions.ts — Equipment crafting actions
  • equipment-actions.ts — Equipment management (equip/unequip/delete)
  • disenchant-actions.ts — Disenchant/salvage actions
  • computed-getters.ts — Derived crafting state

UI Components (src/components/game/)

Tabs (14 tabs):

  • SpireSummaryTab.tsx — Spire overview/progress (largest tab)
  • DisciplinesTab.tsx — Discipline management
  • GolemancyTab.tsx — Golem summoning/management
  • PrestigeTab.tsx — Prestige/insight upgrades
  • CraftingTab.tsx — Crafting wrapper (with EnchanterSubTab, FabricatorSubTab)
  • EquipmentTab.tsx — Equipment management
  • GuardianPactsTab.tsx — Guardian pact signing
  • SpellsTab.tsx — Spell management
  • AttunementsTab.tsx — Attunement management
  • AchievementsTab.tsx — Achievement viewer
  • StatsTab.tsx — Player statistics
  • DebugTab.tsx — Debug tools (8 sections)
  • SpireCombatPage/ — In-combat UI (7 files)
  • ActivityLog.tsx — Activity log display

Shared Components:

  • ManaDisplay.tsx, ActionButtons.tsx, TimeDisplay.tsx
  • AttunementStatus.tsx, GameToast.tsx, UpgradeDialog.tsx
  • crafting/ — EnchantmentDesigner, EnchantmentPreparer, EnchantmentApplier, EquipmentCrafter
  • debug/ — Debug components for each system
  • LootInventory/ — Loot/blueprint/materials UI

Persistence

  • All state persisted to localStorage via Zustand persist middleware
  • No backend, no database, no Prisma
  • Store keys: mana-loop-crafting, mana-loop-ui-storage, etc.

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 / store.ts / store-modules/ Modular Zustand stores in stores/
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
Familiar System Replaced by Golemancy and Pact systems
Legacy static guardians (named Primordialis, The Awakened One) Procedural guardian system with 8 tiers
Prisma / database Removed; localStorage-only persistence

Document Version: 5.0 — Updated: 8 stores, 22 mana types, 64 disciplines, 14 prestige upgrades, 43 equipment types, 10 golems (redesign pending), 8-tier guardians, localStorage-only End of Game Briefing Document

Reference in New Issue View Git Blame Copy Permalink