Mana-Loop/README.md

# Mana Loop

An incremental/idle game about climbing a magical spire, mastering skills, and uncovering the secrets of an ancient tower.

## Overview

**Mana Loop** is a browser-based incremental game where players gather mana, study skills and spells, climb the floors of a mysterious spire, and craft enchanted equipment. The game features a prestige system (Insight) that provides permanent progression bonuses across playthroughs.

### The Game Loop

1. **Gather Mana** - Click to collect mana or let it regenerate automatically
2. **Study Skills & Spells** - Spend mana to learn new abilities and unlock upgrades
3. **Climb the Spire** - Battle through floors, defeat guardians, and sign pacts for power
4. **Craft Equipment** - Enchant your gear with powerful effects
5. **Prestige** - Reset for Insight, gaining permanent bonuses

---

## Features

### Mana Gathering & Management
- Click-based mana collection with automatic regeneration
- Elemental mana system with multiple elements
- Mana conversion between raw and elemental forms
- Meditation system for boosted regeneration
- Compound mana types created from base elements
- Exotic mana types for ultimate power

---

## 🔮 Mana Types

Mana is the core resource of Mana Loop. There are four categories of mana types:

### Base Mana Types (7)
| Element | Symbol | Color | Theme |
|---------|--------|-------|-------|
| Fire | 🔥 | #FF6B35 | Destruction, burn damage |
| Water | 💧 | #4ECDC4 | Flow, freeze effects |
| Air | 🌬️ | #00D4FF | Speed, wind damage |
| Earth | ⛰️ | #F4A261 | Stability, armor pierce |
| Light | ☀️ | #FFD700 | Radiance, holy damage |
| Dark | 🌑 | #9B59B6 | Shadows, void damage |
| Death | 💀 | #778CA3 | Decay, rot damage |

### Utility Mana Types (1)
| Element | Symbol | Color | Theme |
|---------|--------|-------|-------|
| Transference | 🔗 | #1ABC9C | Mana transfer, Enchanter attunement |

### Compound Mana Types (3)
Created by combining two base elements:
| Element | Recipe | Theme |
|---------|--------|-------|
| Metal | Fire + Earth | Armor piercing, forged weapons |
| Sand | Earth + Water | AOE damage, desert winds |
| Lightning | Fire + Air | Fast damage, armor pierce, chain effects |

### Exotic Mana Types (3)
Created from advanced recipes:
| Element | Recipe | Theme |
|---------|--------|-------|
| Crystal | Sand + Sand + Light | Prismatic, high damage |
| Stellar | Fire + Fire + Light | Cosmic, ultimate fire/light |
| Void | Dark + Dark + Death | Oblivion, ultimate dark/death |

### Mana Type Hierarchy
```
Base Elements (7)
       ↓
Compound (3)    Utility (1)
       ↓
Exotic (3)
```

---

### Skill Progression with Tier Evolution
- 20+ skills across multiple categories (mana, study, enchanting, golemancy)
- 5-tier evolution system for each skill
- Milestone upgrades at levels 5 and 10 for each tier
- Unique special effects unlocked through skill upgrades

### Equipment Crafting & Enchanting
- 3-stage enchantment process (Design → Prepare → Apply)
- Equipment capacity system limiting total enchantment power
- Enchantment effects including stat bonuses, multipliers, and spell grants
- Disenchanting to recover mana from unwanted enchantments (only in Prepare stage)
- Cannot re-enchant already enchanted gear

### Golemancy System
- Summon magical constructs to fight alongside you
- Golem slots unlock every 2 Fabricator levels (Level 2=1, Level 10=5)
- Base golems: Earth, Steel (metal), Crystal, Sand
- Advanced hybrid golems at Enchanter 5 + Fabricator 5: Lava, Galvanic, Obsidian, Prism, Quicksilver, Voidstone
- Golems cost mana to summon and maintain
- Golemancy skills improve damage, speed, duration, and maintenance costs

### Combat System
- Cast speed-based spell casting
- Multi-spell support from equipped weapons
- Golem allies deal automatic damage each tick
- Elemental damage bonuses and effectiveness
- Floor guardians with unique boons and pacts

### Floor Navigation & Guardian Battles
- Procedurally generated spire floors
- Elemental floor themes affecting combat
- Guardian bosses with unique mechanics
- Pact system for permanent power boosts

### Prestige System (Insight)
- Reset progress for permanent bonuses
- Insight upgrades across multiple categories
- Signed pacts persist through prestige

---

## Tech Stack

| Technology | Purpose |
|------------|---------|
| **Next.js 16** | Full-stack framework with App Router |
| **TypeScript 5** | Type-safe development |
| **Tailwind CSS 4** | Utility-first styling |
| **shadcn/ui** | Reusable UI components |
| **Zustand** | Client state management with persistence |
| **Prisma ORM** | Database abstraction (SQLite) |
| **Bun** | JavaScript runtime and package manager |

---

## Getting Started

### Prerequisites

- **Node.js** 18+ or **Bun** runtime
- **npm**, **yarn**, or **bun** package manager

### Installation

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

# Install dependencies
bun install
# or
npm install

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

### Development

```bash
# Start the development server
bun run dev
# or
npm run dev
```

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

### Other Commands

```bash
# Run linting
bun run lint

# Build for production
bun run build

# Start production server
bun run start
```

---

## Project Structure

```
src/
├── app/
│   ├── page.tsx          # Main game UI (single-page application)
│   ├── layout.tsx        # Root layout with providers
│   └── api/              # API routes
├── components/
│   ├── ui/               # shadcn/ui components
│   └── game/             # Game-specific components
│       ├── tabs/         # Tab-based UI components
│       │   ├── CraftingTab.tsx
│       │   ├── GolemancyTab.tsx
│       │   ├── LabTab.tsx
│       │   ├── SpellsTab.tsx
│       │   ├── SpireTab.tsx
│       │   └── ...
│       ├── ManaDisplay.tsx
│       ├── TimeDisplay.tsx
│       ├── ActionButtons.tsx
│       └── ...
└── lib/
    ├── game/
    │   ├── store.ts              # Zustand store (state + actions)
    │   ├── effects.ts            # Unified effect computation
    │   ├── upgrade-effects.ts    # Skill upgrade definitions
    │   ├── skill-evolution.ts    # Tier progression paths
    │   ├── constants.ts          # Game data definitions
    │   ├── computed-stats.ts     # Stat calculation functions
    │   ├── crafting-slice.ts     # Equipment/enchantment actions
    │   ├── navigation-slice.ts   # Floor navigation actions
    │   ├── study-slice.ts        # Study system actions
    │   ├── types.ts              # TypeScript interfaces
    │   ├── formatting.ts         # Display formatters
    │   ├── utils.ts              # Utility functions
    │   └── data/
    │       ├── equipment.ts      # Equipment definitions
    │       ├── enchantment-effects.ts  # Enchantment catalog
    │       ├── golems.ts         # Golem definitions
    │       ├── crafting-recipes.ts     # Crafting recipes
    │       ├── achievements.ts   # Achievement definitions
    │       └── loot-drops.ts     # Loot drop tables
    └── utils.ts                  # General utilities
```

For detailed architecture documentation, see [AGENTS.md](./AGENTS.md).

---

## Game Systems Overview

### Mana System
The core resource of the game. Mana is gathered manually or automatically and used for studying skills, casting spells, and crafting.

**Key Files:**
- `store.ts` - Mana state and actions
- `computed-stats.ts` - Mana calculations

### Skill System
Skills provide passive bonuses and unlock new abilities. Each skill can evolve through 5 tiers with milestone upgrades.

**Key Files:**
- `constants.ts` - Skill definitions (`SKILLS_DEF`)
- `skill-evolution.ts` - Evolution paths and upgrades
- `upgrade-effects.ts` - Effect computation

### Combat System
Combat uses a cast-speed system where each spell has a unique cast rate. Damage is calculated with skill bonuses, elemental modifiers, and special effects.

**Key Files:**
- `store.ts` - Combat tick logic
- `constants.ts` - Spell definitions (`SPELLS_DEF`)
- `effects.ts` - Damage calculations

### Enchanting System
A 3-stage enchantment system for equipment. Design effects, prepare equipment, and apply enchantments within capacity limits.

**Key Rules:**
- Design: Choose effects for your equipment type
- Prepare: Prepare equipment for enchanting (ONLY way to disenchant existing enchantments)
- Apply: Apply designed enchantments (cannot re-enchant already enchanted gear)

**Key Files:**
- `crafting-slice.ts` - Crafting actions
- `data/equipment.ts` - Equipment types
- `data/enchantment-effects.ts` - Available effects

### Golemancy System
Summon magical constructs to fight alongside you. Requires Fabricator attunement.

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

**Golem Types:**
- Base: Earth (available at Fabricator 2)
- Element Unlocks: Steel (metal), Crystal, Sand
- Hybrids (Enchanter 5 + Fabricator 5): Lava, Galvanic, Obsidian, Prism, Quicksilver, Voidstone

**Key Files:**
- `data/golems.ts` - Golem definitions and unlock conditions
- `store.ts` - Golemancy actions and state

### Prestige System
Reset progress for Insight, which provides permanent bonuses. Signed pacts persist through prestige.

**Key Files:**
- `store.ts` - Prestige logic
- `constants.ts` - Insight upgrades

---

## Contributing

We welcome contributions! Please follow these guidelines:

### Development Workflow

1. **Pull the latest changes** before starting work
2. **Create a feature branch** for your changes
3. **Follow existing patterns** in the codebase
4. **Run linting** before committing (`bun run lint`)
5. **Test your changes** thoroughly

### Code Style

- TypeScript throughout with strict typing
- Use existing shadcn/ui components over custom implementations
- Follow the slice pattern for store actions
- Keep components focused and extract to separate files when >50 lines

### Adding New Features

For detailed patterns on adding new effects, skills, spells, or systems, see [AGENTS.md](./AGENTS.md).

---

## Banned Content

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

### Banned Mechanics
- **Lifesteal** - Player cannot heal from dealing damage
- **Healing** - Player cannot heal themselves (floors take damage, not player)

### 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 favor of Golemancy and Pact systems

---

## License

This project is licensed under the MIT 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 love using modern web technologies. Special thanks to the open-source community for the amazing tools that make this project possible.