Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/at6132/econ/llms.txt

Use this file to discover all available pages before exploring further.

Realm runs as two local processes: a Python FastAPI simulation engine on port 8000 and a Next.js web client on port 3000. The web client proxies all /api/engine requests to the engine, so you only need two terminal sessions to get a fully working development environment. No external database, no cloud services, and no API keys are required for solo mode.
Realm requires Python 3.11 or later and Node.js 18 or later. Check your versions with python --version and node --version before proceeding.

​
Setup

1

Install the simulation engine

Clone the repository and install the Python package in editable mode. The engine is a standard Python package built with Hatchling; editable install means local source changes take effect immediately without reinstalling.
Terminal 1
cd engine
pip install -e .
This installs fastapi, uvicorn, and the realm package itself. Optional extras (llm, lua, dev) are not required for basic solo-mode play.
2

Start the engine API

Start the FastAPI server with live reload enabled. The engine bootstraps a Frontier scenario world in memory on startup using a deterministic seed.
Terminal 1
uvicorn realm.api:app --reload --port 8000
You will see Uvicorn print Application startup complete. The engine is now serving on http://localhost:8000.
3

Install web dependencies

Open a second terminal and install the Next.js frontend dependencies. The web client uses Next.js 14, React 18, Pixi.js for the map renderer, and Recharts for economic charts.
Terminal 2
cd web
npm install
4

Start the web client

Start the Next.js development server. It will automatically proxy requests prefixed with /api/engine to the engine running on port 8000.
Terminal 2
npm run dev
Next.js will print a local URL when the server is ready.
5

Open the game

Open http://localhost:3000 in your browser. You will see the 2D map grid with the Frontier scenario world loaded — a set of unclaimed plots with terrain, climate, and coastal-access indicators visible on hover.
Solo mode runs entirely in-memory. No database setup is required for development. The engine does support optional SQLite save/load via POST /persistence/save and POST /persistence/load, but those endpoints are not needed to start playing.

​
Verify the engine is healthy

Before interacting with the map, confirm the engine is responding correctly. The health endpoint requires no authentication and returns immediately. 
curl http://localhost:8000/health
If the engine is not running, the web client will display fetch errors. Start the engine (Step 2 above) and reload.

​
Your first session

Once the map loads, here is what to do in your first session. Claim a plot. Click any highlighted unclaimed plot on the map. Each plot shows its terrain type and whether it has coastal access. You start with $10,000 in capital. Claiming a plot costs nothing upfront but commits you to a location with specific physical properties. Survey your plot. Click Survey on your claimed plot. A survey costs $500 and reveals the subsurface composition — copper, clay, timber, or nothing. Subsurface data is hidden until surveyed; the API will not return it for a plot you have not surveyed. This information asymmetry is intentional. Pick a production recipe. After surveying, the plot panel shows the recipes available for your terrain and subsurface results. Select a recipe — for example, a clay quarry if your survey returned clay deposits. Advance ticks. Click Advance tick to move the simulation forward. Each tick represents one game-day. Buildings take a few ticks to construct; production then runs automatically each tick. Watch your inventory fill and your capital change as wages are paid and goods accumulate. Open the market panel. Once you have inventory, open the market panel to place a sell order. Set a quantity and a price per unit. When another agent (AI or human) places a matching buy order, the trade executes and your capital increases.

​
Terminal commands at a glance

cd engine
pip install -e .
uvicorn realm.api:app --reload --port 8000

​
Next steps

First hour guide

A minute-by-minute walkthrough of your first solo session: from plot selection through your first contract negotiation with a named AI rival.

Game modes

Understand solo scenarios, public persistent multiplayer, and competitive seasons before choosing how to play.

Economic primitives

Learn the nine building blocks — land, materials, labor, time, capital, production, markets, contracts, and code — that underpin every action in the engine.

Engine API reference

Every endpoint the FastAPI engine exposes, with parameters, query strings, and example responses.

Build docs developers (and LLMs) love

Get started for freeTalk to us