# Mana Loop

<p align="center">
  <img src="public/logo.svg" alt="Mana Loop Logo" width="200" />
  <br />
  <em>An incremental/idle game about climbing a magical spire, mastering skills, and uncovering ancient secrets.</em>
</p>

<p align="center">
  <a href="https://gitea.tailf367e3.ts.net/Anexim/Mana-Loop">Repository</a> ·
  <a href="#getting-started">Getting Started</a> ·
  <a href="#game-systems">Game Systems</a> ·
  <a href="#contributing">Contributing</a> ·
  <a href="#deployment">Deployment</a>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/version-0.2.0-blue" alt="Version" />
  <img src="https://img.shields.io/badge/license-MIT-green" alt="License" />
  <img src="https://img.shields.io/badge/Next.js-16.1.1-black" alt="Next.js" />
  <img src="https://img.shields.io/badge/TypeScript-5-blue" alt="TypeScript" />
  <img src="https://img.shields.io/badge/React-19-61DAFB" alt="React" />
</p>

---

## Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Tech Stack](#tech-stack)
- [Getting Started](#getting-started)
- [Project Structure](#project-structure)
- [Game Systems](#game-systems)
- [Deployment](#deployment)
- [Contributing](#contributing)
- [Banned Content](#banned-content)
- [License](#license)
- [Acknowledgments](#acknowledgments)

---

## Overview

**Mana Loop** is a browser-based incremental/idle game where players gather mana, master skills, climb a mysterious 100-floor 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

1. **Gather Mana** - Click to collect mana or let it regenerate automatically (14 total mana types)
2. **Study Skills & Spells** - 20+ skills with 5-tier evolution system and milestone upgrades
3. **Climb the Spire** - Battle through 100 procedurally-generated floors, defeat guardians, sign pacts
4. **Craft & Enchant** - 3-stage equipment enchantment system with capacity limits
5. **Summon Golems** - Magical constructs that fight alongside you (4 base + 6 hybrid types)
6. **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)

### 📜 Skill & Spell System
- 20+ skills across multiple categories (mana, study, enchanting, golemancy)
- 5-tier evolution system for each skill
- Milestone upgrades at levels 5 and 10 per tier
- Unique special effects unlocked through skill upgrades

### ⚔️ Combat & Spire
- Cast-speed based combat system
- Multi-spell support from equipped weapons
- 100-floor spire with elemental themes
- Floor guardians with unique mechanics and pacts
- Golem allies that deal automatic damage each tick

### 🛡️ 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
- Golem maintenance costs and stat upgrades via skills

### 🔄 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), 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

```bash
# 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

```bash
# 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 (~583 lines)
│   │   ├── 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, SkillsTab, 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
│   │   │   ├── store.ts        # Main Zustand store (~2862 lines)
│   │   │   ├── crafting-slice.ts, study-slice.ts, navigation-slice.ts
│   │   │   ├── effects.ts, upgrade-effects.ts
│   │   │   ├── skill-evolution.ts (~3400 lines)
│   │   │   ├── constants/      # Game definitions (elements, spells, skills)
│   │   │   ├── data/           # Game data (equipment, golems, recipes)
│   │   │   └── __tests__/      # Test files for game logic
│   │   └── db.ts, utils.ts
│   └── test/                   # Test setup
├── prisma/                     # Database schema and migrations
│   └── schema.prisma           # SQLite schema
├── public/                     # Static assets (logo.svg, robots.txt)
├── docs/                       # Project documentation
│   ├── AGENTS.md               # Comprehensive architecture guide
│   ├── GAME_BRIEFING.md        # Game design document
│   └── task/                   # Task tracking documentation
├── .next/                      # Next.js build output (generated)
├── node_modules/               # Dependencies (generated)
├── Configuration Files:
│   ├── package.json            # Project metadata and scripts
│   ├── tsconfig.json           # TypeScript configuration
│   ├── next.config.ts          # Next.js config (standalone output)
│   ├── vitest.config.ts        # Vitest test configuration
│   ├── eslint.config.mjs       # ESLint configuration
│   ├── Dockerfile              # Docker multi-stage build
│   ├── docker-compose.yml      # Docker Compose setup
│   ├── Caddyfile               # Reverse proxy configuration
│   └── .gitea/workflows/       # Gitea Actions CI/CD pipeline
└── README.md                   # This file
```

For detailed architecture patterns and coding guidelines, see [AGENTS.md](./docs/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/store.ts`, `src/lib/game/constants/elements.ts`

### Skill Evolution System
Each skill progresses through 5 tiers with upgrades at levels 5 and 10 per tier:
- **Tier 1**: Basic functionality
- **Tier 2-5**: Unlock new mechanics and bonuses
- **Evolution Paths**: Defined in `src/lib/game/skill-evolution.ts` (~3400 lines)

### Combat System
- Cast-speed based spell casting with DPS calculations
- Elemental damage bonuses and effectiveness
- Multi-spell support from equipped weapons
- Golem allies deal automatic damage each tick

**Key Files**: `src/lib/game/store.ts` (combat tick logic), `src/lib/game/constants/spells.ts`

### Enchanting System
3-stage equipment enchantment process:
1. **Design**: Choose effects for your equipment type
2. **Prepare**: Prepare equipment (ONLY way to disenchant existing enchantments)
3. **Apply**: Apply designed enchantments (cannot re-enchant already enchanted gear)

**Key Files**: `src/lib/game/crafting-slice.ts`, `src/lib/game/data/enchantment-effects.ts`

### 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.ts`, `src/lib/game/store.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
The project includes Docker configuration for containerized deployment:

```bash
# 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` branches
- **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
```bash
bun run build
NODE_ENV=production bun .next/standalone/server.js
```

---

## Contributing

We welcome contributions! Please follow these guidelines:

### Development Workflow
1. **Pull latest changes** before starting work: `git pull origin master`
2. **Create a feature branch** for your changes: `git checkout -b feature/your-feature`
3. **Follow existing patterns** in the codebase (see AGENTS.md)
4. **Run linting** before committing: `bun run lint`
5. **Test your changes** thoroughly: `bun run test`
6. **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 slice pattern for Zustand store actions
- Keep components focused (extract to separate files when >50 lines)
- Use path aliases: `@/*` maps to `./src/*`

### Adding New Features
For detailed patterns on adding new effects, skills, spells, or systems, see the comprehensive [AGENTS.md](./docs/AGENTS.md) guide, which includes:
- Architecture overview
- Coding patterns
- Git workflow (mandatory pull before work, commit & push after)
- Credentials for automation (if applicable)

---

## 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 - see the LICENSE section below for details.

```
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.
```

**Note**: A `LICENSE` file is not currently present in the project root. It is recommended to create one with the above MIT License text.

---

## Acknowledgments

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

---

<p align="center">
  <em>Climb the spire. Master the mana. Uncover the loop.</em>
</p>
