Anexim/Mana-Loop
1
1
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

chore: update README with comprehensive project documentation
Build and Publish Mana Loop Docker Image / build-and-publish (push) Successful in 4m31s
Details

Browse Source 
- Complete rewrite of README.md with updated project information
- Added tech stack with exact version numbers from package.json
- Updated project structure to reflect current codebase
- Added deployment section with Docker, CI/CD, and reverse proxy info
- Included attunement system and golemancy details
- Added git repository information
- Improved formatting and organization with table of contents
This commit is contained in:
Refactoring Agent
2026-04-27 11:59:14 +02:00
parent 35c69809a1
commit beafa82789
1 changed files with 240 additions and 221 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+240 -221
View File
@@ -1,141 +1,126 @@
# Mana Loop # Mana Loop
An incremental/idle game about climbing a magical spire, mastering skills, and uncovering the secrets of an ancient tower. <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 ## 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. **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.
### The Game Loop ### Core Game Loop
1. **Gather Mana** - Click to collect mana or let it regenerate automatically 1. **Gather Mana** - Click to collect mana or let it regenerate automatically (14 total mana types)
2. **Study Skills & Spells** - Spend mana to learn new abilities and unlock upgrades 2. **Study Skills & Spells** - 20+ skills with 5-tier evolution system and milestone upgrades
3. **Climb the Spire** - Battle through floors, defeat guardians, and sign pacts for power 3. **Climb the Spire** - Battle through 100 procedurally-generated floors, defeat guardians, sign pacts
4. **Craft Equipment** - Enchant your gear with powerful effects 4. **Craft & Enchant** - 3-stage equipment enchantment system with capacity limits
5. **Prestige** - Reset for Insight, gaining permanent bonuses 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 ## Features
### Mana Gathering & Management ### 🔮 Mana System
- Click-based mana collection with automatic regeneration - **14 Mana Types**: 7 base elements + 1 utility + 3 compound + 3 exotic
- Elemental mana system with multiple elements - Elemental conversion, regeneration mechanics, and meditation bonuses
- Mana conversion between raw and elemental forms - Mana types: Fire, Water, Air, Earth, Light, Dark, Death (base), Transference (utility), Metal, Sand, Lightning (compound), Crystal, Stellar, Void (exotic)
- Meditation system for boosted regeneration
- Compound mana types created from base elements
- Exotic mana types for ultimate power
--- ### 📜 Skill & Spell System
## 🔮 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) - 20+ skills across multiple categories (mana, study, enchanting, golemancy)
- 5-tier evolution system for each skill - 5-tier evolution system for each skill
- Milestone upgrades at levels 5 and 10 for each tier - Milestone upgrades at levels 5 and 10 per tier
- Unique special effects unlocked through skill upgrades - Unique special effects unlocked through skill upgrades
### Equipment Crafting & Enchanting ### ⚔️ Combat & Spire
- 3-stage enchantment process (Design → Prepare → Apply) - Cast-speed based combat system
- 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 - Multi-spell support from equipped weapons
- Golem allies deal automatic damage each tick - 100-floor spire with elemental themes
- Elemental damage bonuses and effectiveness - Floor guardians with unique mechanics and pacts
- Floor guardians with unique boons and pacts - Golem allies that deal automatic damage each tick
### Floor Navigation & Guardian Battles ### 🛡️ Equipment & Enchanting
- Procedurally generated spire floors - 3-stage enchantment process: Design → Prepare → Apply
- Elemental floor themes affecting combat - Equipment capacity system limiting total enchantment power
- Guardian bosses with unique mechanics - Enchantment effects: stat bonuses, multipliers, spell grants
- Pact system for permanent power boosts - Disenchanting to recover mana (only in Prepare stage)
- Weapon/armor slots with 2-handed weapon support
### Prestige System (Insight) ### 🤖 Golemancy System
- Reset progress for permanent bonuses - 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 - Insight upgrades across multiple categories
- Signed pacts persist through prestige - Signed pacts and attunements persist through prestige
- Three attunement classes: Enchanter (Transference), Invoker (Spells), Fabricator (Golems/Equipment)
--- ---
## Tech Stack ## Tech Stack
| Technology | Purpose | | Technology | Version | Purpose |
|------------|---------| |------------|---------|---------|
| **Next.js 16** | Full-stack framework with App Router | | **Next.js** | ^16.1.1 | Full-stack framework (App Router) |
| **TypeScript 5** | Type-safe development | | **React** | ^19.0.0 | UI library |
| **Tailwind CSS 4** | Utility-first styling | | **TypeScript** | ^5 | Type-safe development |
| **shadcn/ui** | Reusable UI components | | **Tailwind CSS** | ^4 | Utility-first styling |
| **Zustand** | Client state management with persistence | | **shadcn/ui** | Radix-based | Reusable UI components |
| **Prisma ORM** | Database abstraction (SQLite) | | **Zustand** | ^5.0.6 | Client state management (with persist) |
| **Bun** | JavaScript runtime and package manager | | **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 ## Getting Started
### Prerequisites ### Prerequisites
- **Bun** runtime (recommended) or Node.js 18+
- **Node.js** 18+ or **Bun** runtime - **SQLite** (for local development, included with Prisma)
- **npm**, **yarn**, or **bun** package manager - Git
### Installation ### Installation
@@ -144,9 +129,10 @@ Exotic (3)
git clone git@gitea.tailf367e3.ts.net:Anexim/Mana-Loop.git git clone git@gitea.tailf367e3.ts.net:Anexim/Mana-Loop.git
cd Mana-Loop cd Mana-Loop
# Install dependencies # Install dependencies (using Bun - recommended)
bun install bun install
# or
# Or using npm
npm install npm install
# Set up the database # Set up the database
@@ -158,7 +144,7 @@ npm run db:push
### Development ### Development
```bash ```bash
# Start the development server # Start the development server (runs on port 3000)
bun run dev bun run dev
# or # or
npm run dev npm run dev
@@ -166,134 +152,152 @@ npm run dev
The game will be available at `http://localhost:3000`. The game will be available at `http://localhost:3000`.
### Other Commands ### Available Scripts
```bash | Script | Description |
# Run linting |--------|-------------|
bun run lint | `dev` | Start Next.js development server with logging |
| `build` | Build for production (outputs to `.next/standalone`) |
# Build for production | `start` | Start production server (requires build first) |
bun run build | `lint` | Run ESLint |
| `test` | Run Vitest tests |
# Start production server | `test:coverage` | Run tests with coverage report |
bun run start | `db:push` | Push Prisma schema to database |
``` | `db:generate` | Generate Prisma client |
| `db:migrate` | Run database migrations |
| `db:reset` | Reset database |
--- ---
## Project Structure ## Project Structure
``` ```
src/ Mana-Loop/
├── app/ ├── src/ # Application source code
│ ├── page.tsx # Main game UI (single-page application) │ ├── app/ # Next.js App Router
│ ├── layout.tsx # Root layout with providers │ │ ├── layout.tsx # Root layout (metadata, fonts, providers)
│ └── api/ # API routes │ │ ├── page.tsx # Main game UI (~583 lines)
├── components/ │ │ ├── globals.css # Global styles
│ ├── ui/ # shadcn/ui components │ │ └── api/ # API routes (minimal)
│ └── game/ # Game-specific components │ ├── components/ # React components
│ ├── tabs/ # Tab-based UI components │ │ ├── ui/ # shadcn/ui components (20+ components)
│ │ ├── CraftingTab.tsx │ │ └── game/ # Game-specific components
│ │ ├── GolemancyTab.tsx │ │ ├── tabs/ # Tab components (SpireTab, SkillsTab, etc.)
│ │ ├── LabTab.tsx │ │ ├── ManaDisplay.tsx, ActionButtons.tsx, TimeDisplay.tsx
│ │ ├── SpellsTab.tsx │ │ └── crafting/, debug/, shared/, stats/ subdirectories
│ │ ├── SpireTab.tsx │ ├── hooks/ # Custom React hooks (use-mobile, use-toast)
│ │ └── ... │ ├── lib/ # Utility libraries
│ ├── ManaDisplay.tsx │ │ ├── game/ # Core game logic
│ ├── TimeDisplay.tsx │ │ │ ├── store.ts # Main Zustand store (~2862 lines)
│ ├── ActionButtons.tsx │ │ │ ├── crafting-slice.ts, study-slice.ts, navigation-slice.ts
│ └── ... │ │ │ ├── effects.ts, upgrade-effects.ts
└── lib/ │ │ │ ├── skill-evolution.ts (~3400 lines)
├── game/ │ │ │ ├── constants/ # Game definitions (elements, spells, skills)
│ ├── store.ts # Zustand store (state + actions) │ │ │ ├── data/ # Game data (equipment, golems, recipes)
│ ├── effects.ts # Unified effect computation │ │ │ └── __tests__/ # Test files for game logic
│ ├── upgrade-effects.ts # Skill upgrade definitions │ │ └── db.ts, utils.ts
│ ├── skill-evolution.ts # Tier progression paths │ └── test/ # Test setup
│ ├── constants.ts # Game data definitions ├── prisma/ # Database schema and migrations
│ ├── computed-stats.ts # Stat calculation functions │ └── schema.prisma # SQLite schema
│ ├── crafting-slice.ts # Equipment/enchantment actions ├── public/ # Static assets (logo.svg, robots.txt)
│ ├── navigation-slice.ts # Floor navigation actions ├── docs/ # Project documentation
│ ├── study-slice.ts # Study system actions │ ├── AGENTS.md # Comprehensive architecture guide
│ ├── types.ts # TypeScript interfaces │ ├── GAME_BRIEFING.md # Game design document
│ ├── formatting.ts # Display formatters │ └── task/ # Task tracking documentation
│ ├── utils.ts # Utility functions ├── .next/ # Next.js build output (generated)
│ └── data/ ├── node_modules/ # Dependencies (generated)
│ ├── equipment.ts # Equipment definitions ├── Configuration Files:
│ ├── enchantment-effects.ts # Enchantment catalog │ ├── package.json # Project metadata and scripts
│ ├── golems.ts # Golem definitions │ ├── tsconfig.json # TypeScript configuration
│ ├── crafting-recipes.ts # Crafting recipes │ ├── next.config.ts # Next.js config (standalone output)
│ ├── achievements.ts # Achievement definitions │ ├── vitest.config.ts # Vitest test configuration
│ └── loot-drops.ts # Loot drop tables │ ├── eslint.config.mjs # ESLint configuration
└── utils.ts # General utilities │ ├── 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 documentation, see [AGENTS.md](./AGENTS.md). For detailed architecture patterns and coding guidelines, see [AGENTS.md](./docs/AGENTS.md).
--- ---
## Game Systems Overview ## Game Systems
### Mana System ### Mana System
The core resource of the game. Mana is gathered manually or automatically and used for studying skills, casting spells, and crafting. 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:** **Key Files**: `src/lib/game/store.ts`, `src/lib/game/constants/elements.ts`
- `store.ts` - Mana state and actions
- `computed-stats.ts` - Mana calculations
### Skill System ### Skill Evolution System
Skills provide passive bonuses and unlock new abilities. Each skill can evolve through 5 tiers with milestone upgrades. Each skill progresses through 5 tiers with upgrades at levels 5 and 10 per tier:
- **Tier 1**: Basic functionality
**Key Files:** - **Tier 2-5**: Unlock new mechanics and bonuses
- `constants.ts` - Skill definitions (`SKILLS_DEF`) - **Evolution Paths**: Defined in `src/lib/game/skill-evolution.ts` (~3400 lines)
- `skill-evolution.ts` - Evolution paths and upgrades
- `upgrade-effects.ts` - Effect computation
### Combat System ### 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. - 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:** **Key Files**: `src/lib/game/store.ts` (combat tick logic), `src/lib/game/constants/spells.ts`
- `store.ts` - Combat tick logic
- `constants.ts` - Spell definitions (`SPELLS_DEF`)
- `effects.ts` - Damage calculations
### Enchanting System ### Enchanting System
A 3-stage enchantment system for equipment. Design effects, prepare equipment, and apply enchantments within capacity limits. 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 Rules:** **Key Files**: `src/lib/game/crafting-slice.ts`, `src/lib/game/data/enchantment-effects.ts`
- 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 ### Golemancy System
Summon magical constructs to fight alongside you. Requires Fabricator attunement. - **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)
**Golem Slots:** **Key Files**: `src/lib/game/data/golems.ts`, `src/lib/game/store.ts`
- 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:** ### Prestige (Insight)
- Base: Earth (available at Fabricator 2) Reset progress to gain Insight currency for permanent upgrades:
- Element Unlocks: Steel (metal), Crystal, Sand - Signed pacts persist through prestige
- Hybrids (Enchanter 5 + Fabricator 5): Lava, Galvanic, Obsidian, Prism, Quicksilver, Voidstone - Attunement choices affect gameplay (Enchanter/Invoker/Fabricator)
- Insight upgrades provide bonuses across all loops
**Key Files:** ---
- `data/golems.ts` - Golem definitions and unlock conditions
- `store.ts` - Golemancy actions and state
### Prestige System ## Deployment
Reset progress for Insight, which provides permanent bonuses. Signed pacts persist through prestige.
**Key Files:** ### Docker Deployment
- `store.ts` - Prestige logic The project includes Docker configuration for containerized deployment:
- `constants.ts` - Insight upgrades
```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
```
--- ---
@@ -302,23 +306,26 @@ Reset progress for Insight, which provides permanent bonuses. Signed pacts persi
We welcome contributions! Please follow these guidelines: We welcome contributions! Please follow these guidelines:
### Development Workflow ### Development Workflow
1. **Pull latest changes** before starting work: `git pull origin master`
1. **Pull the latest changes** before starting work 2. **Create a feature branch** for your changes: `git checkout -b feature/your-feature`
2. **Create a feature branch** for your changes 3. **Follow existing patterns** in the codebase (see AGENTS.md)
3. **Follow existing patterns** in the codebase 4. **Run linting** before committing: `bun run lint`
4. **Run linting** before committing (`bun run lint`) 5. **Test your changes** thoroughly: `bun run test`
5. **Test your changes** thoroughly 6. **Commit and push** to your branch, then create a pull request
### Code Style ### Code Style
- TypeScript throughout with strict typing - TypeScript throughout with strict typing
- Use existing shadcn/ui components over custom implementations - Use existing shadcn/ui components over custom implementations
- Follow the slice pattern for store actions - Follow the slice pattern for Zustand store actions
- Keep components focused and extract to separate files when >50 lines - Keep components focused (extract to separate files when >50 lines)
- Use path aliases: `@/*` maps to `./src/*`
### Adding New Features ### 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:
For detailed patterns on adding new effects, skills, spells, or systems, see [AGENTS.md](./AGENTS.md). - Architecture overview
- Coding patterns
- Git workflow (mandatory pull before work, commit & push after)
- Credentials for automation (if applicable)
--- ---
@@ -344,7 +351,7 @@ The following content has been removed from the game and should not be re-added:
## License ## License
This project is licensed under the MIT License. This project is licensed under the MIT License - see the LICENSE section below for details.
``` ```
MIT License MIT License
@@ -370,8 +377,20 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. 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 ## Acknowledgments
Built with love using modern web technologies. Special thanks to the open-source community for the amazing tools that make this project possible. - 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>