n8n-gitea
b402b8f56e
Build and Publish Mana Loop Docker Image / build-and-publish (push) Successful in 1m20s
407 lines
17 KiB
Markdown
Executable File
407 lines
17 KiB
Markdown
Executable File
# 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 disciplines, 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.3.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, 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
|
||
|
||
1. **Gather Mana** - Click to collect mana or let it regenerate automatically (14 total mana types)
|
||
2. **Practice Disciplines** - Continuously train abilities that drain mana each tick in exchange for growing stat bonuses
|
||
3. **Climb the Spire** - Battle through procedurally-generated floors; every 10th floor is a guardian encounter
|
||
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)
|
||
|
||
### 📜 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
|
||
|
||
```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
|
||
│ │ ├── 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](./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:
|
||
|
||
1. **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.
|
||
2. **Compound Elements (Floors 90–110)**: Metal, Sand, and Lightning guardians with procedurally generated names.
|
||
3. **Exotic Elements (Floors 120–140)**: Crystal, Stellar, and Void guardians - the most powerful single-element encounters.
|
||
4. **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:
|
||
1. **Design**: Choose effects for your equipment type
|
||
2. **Prepare**: Ready equipment (ONLY stage where disenchanting is possible)
|
||
3. **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
|
||
|
||
```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`
|
||
- **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 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](./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](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> |