Mana Battle

You can play it for free on itch.

The Steam version offers Achievements and Cloud Saves.

A trigger-based autobattler in a 3x3 board. This repository is open source (MIT) — see Contributing to run it locally or hack on it.

Quick Start

cd phaser
npm install
npm run dev        # game at http://localhost:8080

cd server
npm install
npm run dev        # multiplayer API at http://127.0.0.1:8787

Single-player and local multiplayer work out of the box. Online logins (Steam / itch.io / Google) require server-side keys the maintainers hold — see cp .env.example .env and docs/building-and-running.md for details.

Overview

Mana Battle is a strategic auto-battler where players build teams and try to outlive the enemy team's core. Key features:

• Each unit has a "cooldown" in seconds, not turns
• Combat simulated in pure environment, generating data
• Steam achievements and cloud saves
• Cross-platform: Windows, macOS, Linux

Tech Stack

• Phaser 3 - Game engine
• TypeScript - Language
• Electron - Desktop wrapper (Steam release)
• Capacitor - Android wrapper
• Node + express - Multiplayer game server (server/)
• Steamworks - Achievements & cloud saves (Steam release)

Architecture

• Client (phaser/src/)
  • Screens
    • (Some Screen)
      • Components
      • Phases
  • Events
• Client Framework (framework/): system for managing screens and listeners
• Core game logic (core/): pure, framework-agnostic package
• Multiplayer server (server/): authoritative Node API (sessions, matchmaking, auth) — see docs/game-server.md

Documentation

Detailed documentation is organized by topic in the docs directory:

• Project Architecture - High-level architecture chart showing runtime, pure logic, combat playback, server abstraction, and platform layers.
• Building and Running - Setup instructions, available commands, and platform requirements
• Unit Balance - Complete guide to the unit power and cost calculation system, including action/reaction budgets, trigger frequencies, effect costs, and balancing formulas
• Trigger System - Documentation on the Action-Reaction model, including trigger conditions, targeting, and effect types
• Storage System - Details on the Storage Provider pattern and Steam Cloud / LocalStorage integration
• Localization System - Architecture, usage, and guide for adding new languages
• Achievement System - Overview of Steam achievement integration, victory tiers, and calculation logic
• Combat Architecture - Documentation of the client-server separation for combat simulation.
• Game Server Plan - Phased plan for the new Node multiplayer backend (replaces the retired Supabase functions).
• Battle System - Core combat loop, phase management, and board logic.
• Character/Unit System - Unit definitions, classes, and asset management.
• Audio System - Music and SFX management.
• UI System - UI components, event handling, layout management.
• Effect System - Visual effect pipeline and combat integration.
• Options System - Options data model, persistence, UI bindings.

AI Agent Entry Point

See AGENTS.md for the AI agent guide — project knowledge index, current issues, task queue, and workflow instructions.

Contributing

Issues and pull requests are welcome. Each package has its own AGENTS.md with conventions — read it before editing (core/, framework/, server/, phaser/). Run the package's tests + typecheck before submitting; format with npm run format from the repo root. For AI-assisted contributions, start at AGENTS.md.

Publishing (maintainers only)

Publishing needs private credentials (Steam, itch.io, Play signing keys) that are not in this repo — forks cannot run these targets as-is.

Release builds must be made with MANA_SERVER_URL=https://us-central1-mana-battle-f3b15.cloudfunctions.net/api (and MANA_ITCH_CLIENT_ID for the web build) so multiplayer points at the deployed server instead of the player's own http://127.0.0.1:8787. The production webpack build warns if either is missing. See docs/building-and-running.md and docs/release-audit.md.

• Steam: make steam-publish — builds the desktop app for Windows/macOS/Linux and uploads it to Steam via steamcmd (Docker runner by default; credentials in the root .env — see steam/STEAM_UPLOAD.md).
• Steam Demo: make steam-publish-demo.
• Itch: make itch-publish — builds the web build and pushes it to itch.io via butler.
• Android: run make android-build, then, in Android Studio, Build > Generate Signed Bundle / APK.

License

MIT — see LICENSE.