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
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
**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
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
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 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 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)
---
## 🔮 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
### 📜 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 for each tier
- Milestone upgrades at levels 5 and 10 per 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
### ⚔️ Combat & Spire
- Cast-speed based combat system
- 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
- 100-floor spire with elemental themes
- Floor guardians with unique mechanics and pacts
- Golem allies that deal automatic damage each tick
### Floor Navigation & Guardian Battles
- Procedurally generated spire floors
- Elemental floor themes affecting combat
- Guardian bosses with unique mechanics
- Pact system for permanent power boosts
### 🛡️ 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
### Prestige System (Insight)
- Reset progress for permanent bonuses
### 🤖 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 persist through prestige
- Signed pacts and attunements persist through prestige
- Three attunement classes: Enchanter (Transference), Invoker (Spells), Fabricator (Golems/Equipment)
---
## 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 |
| 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
- **Node.js** 18+ or **Bun** runtime
- **npm**, **yarn**, or **bun** package manager
- **Bun** runtime (recommended) or Node.js 18+
- **SQLite** (for local development, included with Prisma)
- Git
### Installation
@@ -144,9 +129,10 @@ Exotic (3)
git clone git@gitea.tailf367e3.ts.net:Anexim/Mana-Loop.git
cd Mana-Loop
# Install dependencies
# Install dependencies (using Bun - recommended)
bun install
# or
# Or using npm
npm install
# Set up the database
@@ -158,7 +144,7 @@ npm run db:push
### Development
```bash
# Start the development server
# Start the development server (runs on port 3000)
bun run dev
# or
npm run dev
@@ -166,134 +152,152 @@ npm run dev
The game will be available at `http://localhost:3000`.
### Other Commands
### Available Scripts
```bash
# Run linting
bun run lint
# Build for production
bun run build
# Start production server
bun run start
```
| 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
```
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
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 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
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:**
- `store.ts` - Mana state and actions
- `computed-stats.ts` - Mana calculations
**Key Files**: `src/lib/game/store.ts`, `src/lib/game/constants/elements.ts`
### 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
### 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
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:**
- `store.ts` - Combat tick logic
- `constants.ts` - Spell definitions (`SPELLS_DEF`)
- `effects.ts` - Damage calculations
**Key Files**: `src/lib/game/store.ts` (combat tick logic), `src/lib/game/constants/spells.ts`
### 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:**
- 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
**Key Files**: `src/lib/game/crafting-slice.ts`, `src/lib/game/data/enchantment-effects.ts`
### 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:**
- 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
**Key Files**: `src/lib/game/data/golems.ts`, `src/lib/game/store.ts`
**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
### 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
**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.
## Deployment
**Key Files:**
- `store.ts` - Prestige logic
- `constants.ts` - Insight upgrades
### 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
```
---
@@ -302,23 +306,26 @@ Reset progress for Insight, which provides permanent bonuses. Signed pacts persi
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
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 store actions
- Keep components focused and extract to separate files when >50 lines
- 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 [AGENTS.md](./AGENTS.md).
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)
---
@@ -344,7 +351,7 @@ The following content has been removed from the game and should not be re-added:
## 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
@@ -370,8 +377,20 @@ 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 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>