Mana-Loop/AGENTS.md

Mana Loop — Agent Guide

Browser incremental/idle game. Next.js 16 + Zustand, no backend, localStorage persistence.

🔑 Git

https://n8n-gitea:tkF9HFgxL2k4cmT@gitea.tailf367e3.ts.net/Anexim/Mana-Loop.git

git config --global user.name "n8n-gitea"
git config --global user.email "n8n-gitea@anexim.local"

Workflow

cd /home/user/repos/Mana-Loop && git pull origin master
# ... work ...
git add -A && git commit -m "type: desc" && git push origin master

Session Start

1. docs/project-structure.txt
2. docs/dependency-graph.json
3. gitea_start_session → retrieve active task registry and issues
4. Evaluate the queue to find the highest-priority ai_state: todo item (or locate an existing in-progress task if resuming work)
5. gitea_update_issue_status → ai_state: "in-progress"
6. Work, log with gitea_add_comment, then gitea_update_issue_status → ai_state: "done"

Labels

ai_state: todo | ai_state: in-progress | ai_state: review | ai_state: blocked | ai_state: done

Terminal Tool

Always pair run_command → get_process_status in same turn. Use wait: 120 for long tasks.

Sub-Agents

Use for 3+ sequential independent calls. Zero context from parent — paste everything needed.

Architecture

• Stack: Next.js 16, TS 5, Tailwind 4 + shadcn/ui, Zustand+persist, Vitest, Bun
• No backend: Pure client-side. No Prisma, no database. State persisted to localStorage.
• Active stores (8 Zustand stores):
  • useGameStore — Coordinator/tick pipeline, imports all other stores
  • useManaStore — Mana pools, regen, element conversion
  • useCombatStore — Spire/floors, combat, spells, achievements
  • useCraftingStore — Enchanting (Design/Prepare/Apply), equipment instances, loot
  • useAttunementStore — Enchanter/Invoker/Fabricator attunement levels & XP
  • usePrestigeStore — Insight, prestige upgrades, pact persistence, loop state
  • useDisciplineStore — Discipline activation, XP ticking, perk evaluation (slice)
  • useUIStore — Logs, pause, game over/victory flags
• Legacy: Fully migrated. No legacy store.ts, store/, or store-modules/ directories remain.

Adding Effects

1. data/enchantments/ — Add effect definition in the appropriate category file
2. craftingStore.ts → effects computation
3. Equipment effects flow through src/lib/game/effects.ts → getUnifiedEffects()

Adding Disciplines

1. Choose the correct data file under data/disciplines/:
   • base.ts — Raw Mana Mastery (available to all)
   • elemental.ts — Elemental Attunement (7 base+ elements)
   • elemental-regen.ts — Elemental Regen (7 base + transference)
   • elemental-regen-advanced.ts — Advanced Regen (3 composite + 3 exotic)
   • enchanter.ts — Core Enchanter disciplines (4 disciplines)
   • enchanter-utility.ts — Utility enchantment disciplines (2 disciplines)
   • enchanter-spells.ts — Spell enchantment disciplines (3 disciplines)
   • enchanter-special.ts — Special enchantment disciplines (1 discipline)
   • invoker.ts — Invoker combat disciplines (2 disciplines)
   • fabricator.ts — Fabricator crafting/golem disciplines (2 disciplines)
2. Define a DisciplineDefinition (see types/disciplines.ts):
   • statBonus.stat must match a key consumed by computeDisciplineEffects()
   • Set difficultyFactor and scalingFactor to control growth rate
   • Add perks (once, capped, or infinite)
3. Re-export from data/disciplines/index.ts so it appears in ALL_DISCIPLINES
4. Add any new statBonus.stat keys to discipline-effects.ts → computeDisciplineEffects()

Discipline Math (quick reference)

StatBonus     = baseValue × (XP / scalingFactor)^0.65
ManaDrainPerTick = drainBase × (1 + (XP / difficultyFactor)^0.4)

• XP accrues every tick the discipline is active and mana drain is met
• concurrentLimit starts at 1 and expands by 1 per 500 total XP (max 4)

Adding Spells

1. constants/spells-modules/ — Add to the appropriate category file
2. data/enchantments/spell-effects/ — Add enchantment effect for the spell
3. Re-export from barrel files

Store Architecture (Key Files)

• stores/gameStore.ts — Main coordinator, combines all stores, tick orchestration
• stores/tick-pipeline.ts → buildTickContext() / applyTickWrites() pattern
• stores/combat-actions.ts — Combat tick processing
• stores/gameLoopActions.ts — Climb/spire actions
• stores/pipelines/[name].ts — Individual pipeline phases

Crafting System

Enchanting: 3-Step Flow — Design → Prepare → Apply

• Design: Select effects for a named design. Time: 1h + 0.5h per effect slot. Dual design slot with Enchant Mastery special.
• Prepare: Clears existing enchantments, costs capacity × 10 raw mana, time: 2h + 1h per 50 capacity. ONLY stage where explicit disenchanting occurs.
• Apply: Applies saved design to prepared equipment. Time: 2h + stacks hours. Mana: 20 + 5×stacks per hour.

Equipment

• 8 slots: mainHand, offHand, head, body, hands, feet, accessory1, accessory2
• 50 equipment types across 9 categories (casters, swords, shields, catalysts, head, body, hands, feet, accessories)
• Instance fields: instanceId, typeId, name, enchantments[], usedCapacity, totalCapacity, rarity, quality
• Stacking cost: each additional stack costs 20% more

Golemancy

• 12 golems total: 1 base (Earth) + 3 elemental (Steel, Crystal, Sand) + 6 hybrid (Lava, Galvanic, Obsidian, Prism, Quicksilver, Voidstone) + 2 advanced
• Golems slots: floor(fabricatorLevel / 2), max 5 at level 10
• Hybrid golems require Enchanter 5 + Fabricator 5

Guardian System

• Guardians on every 10th floor
• Base (floors 10–80): 7 base elements + Transference, static definitions with unique names
• Tier 2 — Composite (floors 90–160): 8 composite elements (Metal, Sand, Lightning, Frost, BlackFlame, RadiantFlames, Miasma, ShadowGlass)
• Tier 3 — Exotic (floors 170–240): 6 exotic elements (Crystal, Stellar, Void, Soul, Time, Plasma)
• Tier 4+ — Procedural (floors 250+): Dual-element → multi-element combination bosses cycling through element pairs, scaling indefinitely through 8 tiers
• HP formula: floor(5000 × (floor/10) ^ (1.1 + floor/200))
• Pact signing: costs raw mana + time, grants permanent boons

Combat

• Cast-speed based: castProgress += HOURS_PER_TICK × spellCastSpeed × attackSpeedMult
• Elemental bonuses: super effective (1.5×), same element (1.25×), weak (0.75×), neutral (1.0×)
• Element opposites (bidirectional): fire↔water, air↔earth, light↔dark, frost↔fire
• Element counters (directional): lightning→water (lightning counters water), earth→lightning (earth counters lightning)
• Composite element counters: blackflame counters frost/water/light (and they counter blackflame); radiantflames counters frost/water/dark (and they counter radiantflames)
• All mana types double as spell elements
• Enemy modifiers (max 2 per enemy): Armored, Agile, Mage, Shield, Swarm
• Room types: Combat (default), Guardian (every 10th), Swarm (15%), Speed (10%), Puzzle (20% on every 7th floor)
• Floor HP: 100 + floor × 50 + floor^1.7 for non-guardian floors

Time & Incursion

• TICK_MS: 200ms, HOURS_PER_TICK: 0.04, MAX_DAY: 30
• Incursion starts day 20
• Incursion strength: min(0.95, (totalHours / maxHours) × 0.95)

Prestige (Insight)

• baseInsight = floor(maxFloorReached × 15 + totalManaGathered / 500 + signedPacts.length × 150)
• Multiplied by discipline and boon bonuses. ×3 for victory (floor 100 + pact signed)
• 14 prestige upgrade types: manaWell, manaFlow, insightAmp, spireKey, temporalEcho, steadyHand, ancientKnowledge, elementalAttune, spellMemory, guardianPact, quickStart, elemStart, unlockedManaTypeCapacity
• Signed pacts persist through prestige (bounded by pactSlots)

Starting State

• Attunement: Enchanter only (level 1)
• Mana: Only Transference unlocked
• Equipment: Basic Staff with Mana Bolt enchantment (mainHand), Civilian Shirt (body), Civilian Shoes (feet)
• 1 discipline slot, 1 concurrent discipline

Banned

Lifesteal/healing, scroll crafting, ascension skills, LabTab, pause mechanics, familiar system, shields, mana types: life, blood, wood, mental, force

File Limit

400 lines max (pre-commit hook enforces).

Mana Types

Base (7): Fire 🔥 Water 💧 Air 🌬️ Earth ⛰️ Light ☀️ Dark 🌑 Death 💀 Utility (1): Transference 🔗 Composite (8): Fire+Earth=Metal ⚙️, Earth+Water=Sand ⏳, Fire+Air=Lightning ⚡, Air+Water=Frost ❄️, Dark+Fire=BlackFlame 🌋, Light+Fire=Radiant Flames 🌟, Air+Death=Miasma ☁️, Earth+Dark=Shadow Glass 🖤 Exotic (6): Sand+Sand+Light=Crystal 💎, Plasma+Light+Fire=Stellar ⭐, Dark+Dark+Death=Void 🕳️, Light+Dark+Transference=Soul 💫, Soul+Sand+Transference=Time ⏱️, Lightning+Fire+Transference=Plasma ⚡

Total: 22 mana types (7 base + 1 utility + 8 composite + 6 exotic)