Mana-Loop/AGENTS.md

Mana Loop — Agent Guide

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

🔑 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. get_repo_summary → resume in-progress or pick top todo
4. update_issue_status → ai:in-progress
5. Work, log with add_comment, then update_issue_status → ai:done

Labels

ai:todo | ai:in-progress | ai:review | ai:blocked | ai: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/Playwright, Bun
• Active stores: src/lib/game/stores/{game,mana,combat,prestige,discipline,ui}Store.ts
• Legacy (migrating): src/lib/game/store/ and store-modules/
• Crafting: 3-step flow — Design → Prepare → Apply via crafting-actions/
• Disciplines: data/disciplines/ + stores/discipline-slice.ts + utils/discipline-math.ts
• Effects: All stat mods through getUnifiedEffects() — discipline bonuses enter via computeDisciplineEffects()

Adding Effects

1. data/enchantment-effects.ts
2. effects.ts → computeEquipmentEffects()
3. Access via getUnifiedEffects(state)

Adding Disciplines

1. Choose the correct data file under data/disciplines/:
   • base.ts — available to all attunements
   • enchanter.ts — requires Enchanter attunement
   • invoker.ts — requires Invoker attunement
   • fabricator.ts — requires Fabricator attunement
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 +3)

Adding Spells

1. constants/spells.ts
2. data/enchantment-effects.ts
3. EFFECT_RESEARCH_MAPPING

Banned

Lifesteal/healing, scroll crafting, ascension skills, LabTab, pause, 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 🔗
Compound (3): Fire+Earth=Metal, Earth+Water=Sand, Fire+Air=Lightning
Exotic (3): Sand+Sand+Light=Crystal, Fire+Fire+Light=Stellar, Dark+Dark+Death=Void