Polis Genesis

An autonomous town simulation where artificial life meets a living 3D world.

Overview

Polis Genesis models a town of autonomous residents. Each person has a genome, needs, mood, memories, relationships, and a mind that chooses actions. Residents work, trade, find homes, form families, talk, and respond to crime and the changing environment as the town evolves.

The Rust engine keeps simulation state and seeded behavior reproducible. A Python command-line package runs the tools, while a browser viewer renders exported worlds and replays in 3D. A local HTTP server can also drive the viewer with a live simulation.

Features

• People and behavior: genomes, needs, moods, movement, memory, relationships, conversation, and family life.
• Town systems: jobs, wages, markets, housing, taxes, law enforcement, courts, and a shared treasury.
• World simulation: seeded runs, reports, JSON snapshots, and recorded replays.
• Resumable Rust state: versioned JSON saves preserve the full simulation, including its random-number generator; these are separate from viewer snapshots.
• 3D viewer: districts, residents, detailed homes, civic buildings, varied trees, spaced streets, fountain plazas, a beach promenade, bridges, animated water, and a distant castle backed by low-poly mountains, built with Three.js and Vite. Parked cars are visual markers for occupied homes with a resident balance of at least 250 coins; vehicles are not yet owned or simulated by the Rust economy.
• Optional local speech: the ollama feature can use a local Ollama model; rule-based speech remains the default and fallback.
• Python analysis: a standard-library report script reads exported town JSON.

Architecture

flowchart LR
    User[User] --> Py[Python package and CLI]
    User --> Bin[Rust CLI]
    Py --> Bin
    Bin --> Core[polis_core: world, people, economy and justice]
    Core --> Mind[polis_mind: rule-based or optional Ollama speech]
    Bin -->|snapshot and replay JSON| Viewer[TypeScript viewer]
    Bin -->|local HTTP town API| Viewer
    Viewer -->|Vite development server| Browser[Web browser, Three.js]
    Snapshot[Exported town JSON] --> Analysis[Python analysis tool]

Getting started

Install the Python package

Requires Python 3.9 or newer. Install the published package with:

python -m pip install polis-genesis

The package provides polis-genesis and polis commands. For example, start the interactive console with the default seed, population, and duration:

polis-genesis console

Set the seed, population, number of ticks, or console delay with options:

polis-genesis console --seed 7 --population 120 --ticks 500 --delay 80

Start a local town API server (default port 8787):

polis-genesis serve --seed 1 --population 200 --port 8787

Open the hosted viewer from the command line with polis-genesis web.

Run from source

Install stable Rust and Cargo, Python 3.9 or newer, and Node.js with npm. From the repository root, run a simulation and print its report:

cargo run --release -p polis_cli -- 1 3000 200

The positional arguments are seed, ticks, and population. To write a snapshot and replay as well:

cargo run --release -p polis_cli -- 1 3000 200 town.json replay.json 10

Analyze the exported snapshot with the Python standard library:

python tools/analyze.py town.json

Town exports use format 3 and record the exact seed, initial population, map size, and market food stock over time. The viewer also reads format 2 snapshots.

Rust applications can save and resume the complete simulation state:

let save = world.save_json()?;
let resumed = polis_core::World::load_json(&save)?;

Simulation saves currently use format version 1. The loader rejects unsupported versions and validates restored state. Town exports and replay files remain separate formats for the viewer.

Run the live 3D viewer locally

In one terminal at the repository root, start the simulation server:

cargo run --release -p polis_cli -- serve 1 200 8787

In a second terminal, install viewer dependencies and start Vite:

cd viewer
npm ci
npm run dev

Open the Vite URL printed in the terminal and navigate to world.html. The development server forwards /api requests to the town server on 127.0.0.1:8787. On Windows, ./run.ps1 starts both processes and opens the viewer.

With the live town server connected, the viewer toolbar includes Add 1 person, Add 5 people, and Add 20 people controls. Recorded replays, including the static GitHub Pages demo, cannot change their population; start the live server above to use these controls.

Build the static viewer from the viewer directory with:

npm run build

The output is written to viewer/dist. GitHub Actions builds the site and publishes it to Pages.

Releases and project status

The next coordinated release is v0.4.0. Its versioned tag triggers GitHub Actions to build the cross-platform Rust CLI binaries and static viewer bundle, create the GitHub release, and publish the Python package. The Python package metadata and CLI version output are aligned at 0.4.0. See the changelog for changes and the GitHub releases page for release assets.

Documentation

• Agent architecture and evaluation
• Design notes
• Viewer performance notes
• Contributing guide
• Changelog
• MIT License

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for setup, project rules, and checks used by CI.

License

Polis Genesis is distributed under the MIT License.