Hero's Legend — Tale of Seven Kingdoms

A 2D pixel-art JRPG built with Phaser 3, featuring AI + procedural art generation, turn-based combat, and 12-region adventure.

English | 繁體中文

---

Features

• Epic Adventure — Journey through 12 kingdoms (Elf, Treant, Beast, Merfolk, Giant, Dwarf, Undead...), rising from a wandering hero to king
• Turn-based Combat — AGI-based turn order with attack, skills, items, defend, and flee
• 120+ Monsters & 12 Bosses — 10 monsters + 1 regional boss per region, culminating in a final boss battle
• 7 Companions — Each with unique racial skills; bring up to 3 into battle
• AI + Procedural Art — Monsters generated by Stable Diffusion pixel-art models; characters, buildings, terrain, and UI panels rendered in real-time via Canvas 2D (AI-first with procedural fallback)
• AI Audio — Background music and SFX generated by MusicGen
• Equipment System — 5 slots × 8 tiers of gear affecting ATK, DEF, AGI, and more
• Save System — 3 manual save slots + autosave (localStorage)
• Menu System — Items / Equipment / Party / Skills / Save / System

Controls

Key	Action
WASD / Arrow Keys	Move
Enter / Space / Z	Confirm / Advance dialogue
ESC	Menu / Cancel
A	Auto-attack mode (battle)
F11	Toggle fullscreen
Mouse click	Confirm / Select target
Right-click	Cancel

Screenshots

Title Screen	World Map

Town Exploration	Field Adventure

Battle Scene	Boss Fight

Tech Stack

Technology	Purpose
Phaser 3	2D game framework (WebGL / Canvas)
TypeScript	Type-safe game logic
Vite	Dev server & bundler
Playwright	E2E browser testing
Stable Diffusion	AI pixel-art sprite generation (All-In-One-Pixel-Model)
MusicGen	AI background music & SFX generation

Getting Started

Prerequisites

• Node.js >= 20
• pnpm >= 9

Installation

git clone https://github.com/osisdie/phaser-rpg-game.git
cd phaser-rpg-game
pnpm install

Run

pnpm start          # Start dev server (port 5473)
pnpm run status     # Check if server is running
pnpm run stop       # Stop the server

Or run directly:

pnpm run dev        # Vite dev server
pnpm run build      # TypeScript check + production build
pnpm run preview    # Preview production build

Docker

docker build -t phaser-rpg-game .
docker run -p 8080:8080 phaser-rpg-game

Open http://localhost:8080 to play.

Project Structure

phaser-rpg-game/
├── src/
│   ├── scenes/        # Phaser scenes (Boot → Title → NameInput → WorldMap → Town/Field → Battle → …)
│   ├── systems/       # Game logic (state, combat, audio, i18n)
│   ├── entities/      # Player sprite & movement
│   ├── data/          # Static data (monsters, items, skills, regions, tables)
│   ├── ui/            # Reusable UI components (TextBox, BattleHUD, menus)
│   ├── maps/          # Procedural map generation (town 40×32, field 48×36)
│   ├── art/           # Procedural pixel art generation (Canvas 2D)
│   └── types/         # TypeScript interfaces
├── e2e/               # Playwright E2E tests
├── scripts/           # Dev workflow & AI asset generation scripts
├── public/assets/ai/  # AI-generated sprites, audio & manifests
├── docs/screenshots/  # Game screenshots
├── playwright.config.ts
├── index.html
├── vite.config.ts
└── tsconfig.json

Scripts

Command	Description
pnpm start	Start dev server with port-check
pnpm run stop	Stop dev server on port 5473
pnpm run status	Check server status + health check
pnpm run dev	Vite dev server (raw)
pnpm run build	TypeScript check + Vite build
pnpm run preview	Preview production build
pnpm test	Run Playwright E2E tests
pnpm run test:ui	Open Playwright test UI
pnpm run capture:screenshots	Capture README screenshots (title, worldmap, town, field, battle, boss)
bash scripts/build.sh	TypeScript check + build with output

Contributing

Contributions are welcome! See CONTRIBUTING.md for the full guide.

Quick steps:

1. Fork the repository
2. Create a branch: git checkout -b feat/my-feature
3. Commit using Conventional Commits:

   git commit -m "feat: add new monster sprites"

4. Push and open a Pull Request

License

MIT — the codebase is licensed under MIT; feel free to use, modify, and distribute. Note: AI-generated assets in public/assets/ai/ may be subject to additional license terms (see AI-Generated Assets Notice below).

AI-Generated Assets Notice

Assets in public/assets/ai/ (sprites, audio, etc.) are generated using third-party AI models and may be subject to additional license terms beyond MIT:

Asset Type	Model / Source	License
Pixel-art sprites	All-In-One-Pixel-Model (Stable Diffusion)	Check model card on Hugging Face
Background music & SFX	MusicGen	Meta's license

Users are responsible for complying with all applicable licenses when using, modifying, or distributing these AI-generated assets. The MIT License applies to the codebase; AI assets may have different terms.