Autobattler Server

FastAPI server for an async autobattler game. The server owns all run state — the Godot client sends actions and replays deterministic battle logs returned by the server.

Stack

• FastAPI + Uvicorn
• Tortoise ORM + Aerich (migrations)
• PostgreSQL (JSONB for squad and battle log storage)
• Steam Web API authentication → internal JWT

Prerequisites

• Python 3.11+
• uv for dependency management
• Docker + Docker Compose (for local dev database)
• The battle_engine package at ../battle_engine

Local Development

1. Install dependencies

uv sync --extra dev
uv pip install -e "../battle_engine"

Activate the venv (.venv\Scripts\activate on Windows, source .venv/bin/activate on Linux/macOS) or prefix commands with uv run.

2. Configure environment

Copy .env.example to .env and fill in values:

cp .env.example .env

Key variables:

Variable	Default	Notes
DATABASE_URL	postgres://...	Tortoise-compatible URL
JWT_SECRET	—	Long random string
STEAM_AUTH_ENABLED	true	Set false to skip Steam validation in dev
STEAM_WEB_API_KEY	—	Required when STEAM_AUTH_ENABLED=true

3. Start the database

docker-compose up -d db

4. Run migrations

aerich upgrade

5. Start the server

uvicorn app.main:app --reload

API available at http://localhost:8000. Docs at http://localhost:8000/docs.

Running Tests

pytest

Production

Run only the app container and point DATABASE_URL at your dedicated PostgreSQL instance:

docker build -t autobattler-server .
docker run -p 8000:8000 --env-file .env autobattler-server

API Overview

Method	Path	Description
POST	/auth/steam	Validate Steam ticket, receive JWT
POST	/runs	Start a new run
GET	/runs/me/current	Current run state (squad, inventory, gold, shop)
POST	/runs/me/shop/buy	Buy an item from the shop
POST	/runs/me/equip	Attach/detach rune or reorder weapons
POST	/runs/me/fight	Run a battle, receive BattleLog
GET	/players/me	Player profile and ELO
GET	/battles/{id}	Retrieve a past battle log