🔥 Fire Legasy

A browser-based snake game with biome progression, elemental mechanics, and competitive leaderboards.

Play through three biomes — Plains, Fire, and Ice — each with a distinct elemental snake that changes gameplay. Register an account, compete for high scores, and conquer all biomes to achieve victory.

Live at firelegasy.com

Features

• 3 Biomes with progressive difficulty: Plains → Fire → Ice
• Elemental mechanics: Fire snake moves 30% faster; Ice snake slides 1 extra tile on turns
• Email/password authentication with JWT tokens
• Global leaderboard with rank, score, and highest biome reached
• Quick restart from the post-game screen

Quick Start

Prerequisites

• Docker and Docker Compose
• (For development): Node.js 20+, Python 3.13+

Run with Docker Compose

# Clone the repo
git clone <repo-url> fire-legasy
cd fire-legasy

# Copy environment config
cp .env.example .env
# Fill in all values (see .env.example for docs)

# Start the stack
docker compose up -d

# Open in browser
# https://firelegasy.com (or http://localhost:8080 for local dev)

The stack includes:

• Frontend (Caddy) on port 8080
• Backend (FastAPI) proxied at /api/*
• PostgreSQL database (internal)

Development Setup

Backend:

python -m venv .venv
source .venv/bin/activate   # or .venv\Scripts\activate on Windows
pip install -e ".[dev]"

# Start a test database
docker run -d --name fire-test-db -p 5433:5432 \
  -e POSTGRES_USER=fire -e POSTGRES_PASSWORD=fire \
  -e POSTGRES_DB=firelegacy_test postgres:16

# Run tests
python -m pytest tests/ -v

Frontend:

npm install
npx tsc              # compile TypeScript
npx vitest run       # run game logic tests

Architecture

Browser (TypeScript + Canvas)  →  Caddy (reverse proxy)  →  FastAPI (auth + leaderboard)  →  PostgreSQL

All game logic runs client-side. The backend handles authentication and score persistence only.

Tech Stack

• Frontend: TypeScript, HTML5 Canvas (no framework)
• Backend: Python FastAPI, asyncpg, bcrypt, PyJWT
• Database: PostgreSQL 16
• Proxy: Caddy 2
• Infrastructure: Docker Compose on Hetzner VPS

Deploying to Production

See DEPLOY.md for full step-by-step instructions:

1. Create a Hetzner CX22 server (~$5/mo)
2. Point firelegasy.com DNS A record to server IP (Namecheap)
3. cp .env.example .env and fill in secrets
4. ./deploy.sh --setup (first time only)
5. ./deploy.sh

Caddy handles HTTPS automatically via Let's Encrypt.