Refactoring Agent
beafa82789
Build and Publish Mana Loop Docker Image / build-and-publish (push) Successful in 4m31s
- 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
397 lines
15 KiB
Markdown
Executable File
397 lines
15 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 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>
|