Mana Loop is a browser-based incremental/idle game where players gather mana, practice disciplines, climb a mysterious spire, craft enchanted equipment, and summon magical golems. The game features a unique time-loop prestige system (Insight) that provides permanent progression bonuses across playthroughs.

Core Game Loop

Gather Mana - Click to collect mana or let it regenerate automatically (14 total mana types)
Practice Disciplines - Continuously train abilities that drain mana each tick in exchange for growing stat bonuses
Climb the Spire - Battle through procedurally-generated floors; every 10th floor is a guardian encounter
Craft & Enchant - 3-stage equipment enchantment system with capacity limits
Summon Golems - Magical constructs that fight alongside you (4 base + 6 hybrid types)
Prestige (Loop) - Reset progress for Insight currency, gain permanent bonuses

Features

🔮 Mana System

14 Mana Types: 7 base elements + 1 utility + 3 compound + 3 exotic
Elemental conversion, regeneration mechanics, and meditation bonuses
Mana types: Fire, Water, Air, Earth, Light, Dark, Death (base), Transference (utility), Metal, Sand, Lightning (compound), Crystal, Stellar, Void (exotic)

📜 Discipline System

Practice-based progression - no discrete levels, only continuous XP growth
Disciplines drain mana each tick; stat bonuses grow as a power curve of accumulated XP
Perks unlock at XP thresholds (once, capped, or infinite stacking)
Attunement-gated discipline pools (Base / Enchanter / Invoker / Fabricator)
Concurrent discipline slots unlock as total XP grows (max 4)

⚔️ Combat & Spire

Cast-speed based combat system with elemental effectiveness
Multi-spell support from equipped weapons
Every 10th floor is a guardian: base elements (10–80), compound (90–110), exotic (120–140), then procedural combination bosses (150+)
Golem allies that deal automatic damage each tick
Enemy modifiers: Armored, Agile, Mage, Shield, Swarm

🛡️ Equipment & Enchanting

3-stage enchantment process: Design → Prepare → Apply
Equipment capacity system limiting total enchantment power
Enchantment effects: stat bonuses, multipliers, spell grants
Disenchanting to recover mana (only in Prepare stage)
Weapon/armor slots with 2-handed weapon support

🤖 Golemancy System

Summon magical constructs (Earth, Steel, Crystal, Sand + 6 hybrid types)
Golem slots unlock every 2 Fabricator levels (max 5 slots at Level 10)
Hybrid golems require Enchanter 5 + Fabricator 5

🔄 Prestige (Insight)

Reset progress for permanent Insight currency
Insight upgrades across multiple categories
Signed pacts and attunements persist through prestige
Three attunement classes: Enchanter (Transference), Invoker (Spells/Pacts), Fabricator (Golems/Equipment)

Tech Stack

Technology	Version	Purpose
Next.js	^16.1.1	Full-stack framework (App Router)
React	^19.0.0	UI library
TypeScript	^5	Type-safe development
Tailwind CSS	^4	Utility-first styling
shadcn/ui	Radix-based	Reusable UI components
Zustand	^5.0.6	Client state management (with persist)
Prisma ORM	^6.11.1	Database abstraction (SQLite)
Bun	Latest	JavaScript runtime & package manager
Vitest	^4.1.2	Unit testing framework
ESLint	^9	Code linting
@tanstack/react-query	^5.82.0	Data fetching/caching
Framer Motion	^12.23.2	Animation library

Getting Started

Prerequisites

Bun runtime (recommended) or Node.js 18+
SQLite (for local development, included with Prisma)
Git

Installation

# Clone the repository
git clone git@gitea.tailf367e3.ts.net:Anexim/Mana-Loop.git
cd Mana-Loop

# Install dependencies (using Bun - recommended)
bun install

# Or using npm
npm install

# Set up the database
bun run db:push
# or
npm run db:push

Development

# Start the development server (runs on port 3000)
bun run dev
# or
npm run dev

The game will be available at http://localhost:3000.

Available Scripts

Script	Description
`dev`	Start Next.js development server with logging
`build`	Build for production (outputs to `.next/standalone`)
`start`	Start production server (requires build first)
`lint`	Run ESLint
`test`	Run Vitest tests
`test:coverage`	Run tests with coverage report
`db:push`	Push Prisma schema to database
`db:generate`	Generate Prisma client
`db:migrate`	Run database migrations
`db:reset`	Reset database

Project Structure

Mana-Loop/
├── src/                        # Application source code
│   ├── app/                    # Next.js App Router
│   │   ├── layout.tsx          # Root layout (metadata, fonts, providers)
│   │   ├── page.tsx            # Main game UI
│   │   ├── globals.css         # Global styles
│   │   └── api/                # API routes (minimal)
│   ├── components/             # React components
│   │   ├── ui/                 # shadcn/ui components (20+ components)
│   │   └── game/               # Game-specific components
│   │       ├── tabs/           # Tab components (SpireTab, DisciplinesTab, etc.)
│   │       ├── ManaDisplay.tsx, ActionButtons.tsx, TimeDisplay.tsx
│   │       └── crafting/, debug/, shared/, stats/ subdirectories
│   ├── hooks/                  # Custom React hooks (use-mobile, use-toast)
│   └── lib/                    # Utility libraries
│       └── game/               # Core game logic
│           ├── stores/         # Modular Zustand stores
│           │   ├── gameStore.ts        # Core state & tick logic
│           │   ├── manaStore.ts        # Mana gathering & conversion
│           │   ├── combatStore.ts      # Combat, spells, floor progression
│           │   ├── prestigeStore.ts    # Prestige/loop & insight
│           │   ├── discipline-slice.ts # Discipline activation & XP
│           │   ├── attunementStore.ts  # Attunement classes
│           │   ├── craftingStore.ts    # Crafting state
│           │   └── uiStore.ts          # UI state & modals
│           ├── crafting-actions/  # Modular crafting stage handlers
│           ├── constants/         # Elements, spells, rooms, prestige
│           ├── data/              # Game data
│           │   ├── disciplines/   # Per-attunement discipline definitions
│           │   ├── enchantments/  # Enchantment effects by category
│           │   ├── equipment/     # Equipment type definitions
│           │   ├── golems/        # Golem definitions
│           │   ├── guardian-data.ts       # Static guardian definitions (floors 10–140)
│           │   └── guardian-encounters.ts # Procedural guardian lookup & combo bosses
│           ├── effects/           # Unified stat computation
│           │   └── discipline-effects.ts  # Discipline → getUnifiedEffects()
│           ├── types/             # TypeScript types (disciplines, elements, etc.)
│           └── utils/             # Combat, floor, enemy, discipline math helpers
├── prisma/                     # Database schema and migrations
├── public/                     # Static assets
├── docs/                       # Project documentation
│   ├── AGENTS.md               # Architecture guide for AI agents
│   └── GAME_BRIEFING.md        # Comprehensive game design document
└── Configuration Files:
    ├── package.json, tsconfig.json, next.config.ts
    ├── vitest.config.ts, eslint.config.mjs
    ├── Dockerfile, docker-compose.yml, Caddyfile
    └── .gitea/workflows/       # Gitea Actions CI/CD pipeline

For detailed architecture patterns and coding guidelines, see AGENTS.md.

Game Systems

Mana System

The core resource of the game with 14 distinct types organized in a hierarchy:

Base Elements (7): Fire, Water, Air, Earth, Light, Dark, Death
Utility (1): Transference (Enchanter attunement)
Compound (3): Metal (Fire+Earth), Sand (Earth+Water), Lightning (Fire+Air)
Exotic (3): Crystal (Sand+Sand+Light), Stellar (Fire+Fire+Light), Void (Dark+Dark+Death)

Key Files: src/lib/game/stores/manaStore.ts, src/lib/game/constants/elements.ts

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.

Stat bonus grows as a power curve of XP: baseValue × (XP / scalingFactor)^0.65
Mana drain also increases with XP: drainBase × (1 + (XP / difficultyFactor)^0.4)
Perks unlock at XP thresholds (once, capped, or infinite)
Concurrent slots start at 1 and unlock as total XP grows (max 4)

Key Files: src/lib/game/data/disciplines/, src/lib/game/stores/discipline-slice.ts, src/lib/game/utils/discipline-math.ts

Guardian & Spire System

Every 10th floor is a guardian encounter. Guardians progress through four tiers of complexity:

Base Elements (Floors 10–80): One guardian per base element + Transference. Static definitions with named guardians (Ignis Prime, Aqua Regia, etc.). Defeating them unlocks their associated mana types.
Compound Elements (Floors 90–110): Metal, Sand, and Lightning guardians with procedurally generated names.
Exotic Elements (Floors 120–140): Crystal, Stellar, and Void guardians - the most powerful single-element encounters.
Combination Bosses (Floor 150+): Fully procedural dual-element guardians. Each one wields two base elements simultaneously (e.g. Fire+Water, Light+Dark) and grows stronger every 10 floors.

Key Files: src/lib/game/data/guardian-data.ts, src/lib/game/data/guardian-encounters.ts

Combat System

Cast-speed based spell casting with elemental effectiveness multipliers
Enemy modifiers: Armored, Agile, Mage (barrier), Shielded, Swarm
Golem allies deal automatic damage each tick
Discipline bonuses feed into damage via getUnifiedEffects()

Key Files: src/lib/game/stores/combatStore.ts, src/lib/game/utils/combat-utils.ts, src/lib/game/utils/enemy-generator.ts

Enchanting System

3-stage equipment enchantment process:

Design: Choose effects for your equipment type
Prepare: Ready equipment (ONLY stage where disenchanting is possible)
Apply: Apply designed enchantments (cannot re-enchant already enchanted gear)

Key Files: src/lib/game/crafting-actions/, src/lib/game/data/enchantments/

Golemancy System

Base Golems: Earth (Fabricator 2), Steel (Metal), Crystal, Sand
Hybrid Golems (Enchanter 5 + Fabricator 5): Lava, Galvanic, Obsidian, Prism, Quicksilver, Voidstone
Golem Slots: 1 slot at Fabricator Level 2, +1 every 2 levels (max 5 at Level 10)

Key Files: src/lib/game/data/golems/, src/lib/game/stores/gameStore.ts

Prestige (Insight)

Reset progress to gain Insight currency for permanent upgrades:

Signed pacts persist through prestige
Attunement choices affect gameplay (Enchanter/Invoker/Fabricator)
Insight upgrades provide bonuses across all loops

Deployment

Docker Deployment

# Build and run with Docker Compose
docker-compose up -d

# Or build manually
docker build -t mana-loop .
docker run -p 3000:3000 mana-loop

CI/CD Pipeline

Gitea Actions: .gitea/workflows/docker-build.yaml automatically builds and pushes Docker images to gitea.tailf367e3.ts.net/anexim/mana-loop:latest on push to master/main
Multi-platform: Builds for linux/amd64 architecture
Image Tags: Branch name, commit SHA, "latest"

Reverse Proxy

A Caddyfile is included for reverse proxy setup (forwards port 81 to 3000).

Production Build

bun run build
NODE_ENV=production bun .next/standalone/server.js

Contributing

We welcome contributions! Please follow these guidelines:

Development Workflow

Pull latest changes before starting work: git pull origin master
Create a feature branch for your changes: git checkout -b feature/your-feature
Follow existing patterns in the codebase (see AGENTS.md)
Run linting before committing: bun run lint
Test your changes thoroughly: bun run test
Commit and push to your branch, then create a pull request

Code Style

TypeScript throughout with strict typing
Use existing shadcn/ui components over custom implementations
Follow the modular store pattern (src/lib/game/stores/)
Keep files under 400 lines (enforced by pre-commit hook)
Use path aliases: @/* maps to ./src/*

Adding New Features

For detailed patterns on adding new effects, disciplines, spells, or systems, see the comprehensive AGENTS.md guide, which includes architecture overview, coding patterns, and git workflow.

Banned Content

The following content has been removed from the game and must not be re-added:

Banned Mechanics

Lifesteal - Player cannot heal from dealing damage
Healing - Player cannot heal themselves (floors take damage, not the player)
Scroll crafting - Violates the no-instant-finishing design pillar
Ascension skills - Removed; no replacement

Banned Mana Types

Life - Removed (healing theme conflicts with core design)
Blood - Removed (life derivative)
Wood - Removed (life derivative)
Mental - Removed
Force - Removed

Banned Systems

Familiar System - Removed in favour of Golemancy and Pact systems
Skill System (study, tiers T1–T5, milestone upgrades) - Fully replaced by the Discipline System

License

MIT License

Copyright (c) 2024 Mana Loop

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Acknowledgments

Built with modern web technologies (Next.js, React, TypeScript, Tailwind CSS)
UI components from shadcn/ui
State management with Zustand
Game icons from Lucide React
Special thanks to the open-source community for the amazing tools that make this project possible.

Climb the spire. Master the mana. Uncover the loop.

README.md Unescape Escape

Mana Loop

Table of Contents

Overview