gridfall

GridFall — a SimCity-style city run by GMI Cloud AI

Day 12 in GridFall: the chaos director bursts a sewage main while Mayor Argon-4 explains, in a private thought and a public post, how it will pay for the repairs

Watch the trailer · Website · Download v0.1.0 · Write-up on DEV

GridFall is a 3D SimCity-style city builder made with Godot 4.7 (Forward+), Blender, GMI Cloud inference and ACE-Step 1.5 audio. You don’t build the city. Five autonomous AI mayors do, each running on a different GMI Cloud model. Every other layer of the city also has a GMI model behind it. You watch, inspect and intervene.

GridFall was built with Factory’s Droid coding agent, which wrote the Godot code, the Blender asset pipeline and the tests. Every mayor, resident and city agent runs on GMI Cloud inference.

The AI city

Role Model What it does
Mayor Argon-4 (NW Civic Campus) google/gemini-4-argon Utility-first planner
Mayor DeepSeek-V4 (NE Tech Corridor) deepseek-ai/DeepSeek-V4-Flash-0731 Systems engineer
Mayor Kimi-K3 (Central Plaza) moonshotai/kimi-k3 Coalition builder
Mayor Qwen-3.8 (SW Eco Quarter) Qwen/Qwen3.8-Max Fiscal pragmatist
Mayor Grok-4.5 (SE Boomtown) x-ai/grok-4.5 Growth maximalist
Citizen Voices MiniMaxAI/MiniMax-M3 Residents react to their real tile data
GridFall Gazette XiaomiMiMo/MiMo-V2.6-Flash Daily newspaper and editorial
Council Speaker openai/gpt-6-luna Rules on ordinances the mayors propose and vote on
Chaos Director deepseek-ai/DeepSeek-V4-Pro Picks disasters that test real weaknesses
Grid Operator google/gemini-3.8-flash Sets the power load-shedding priority
Street Inspector MiniMaxAI/MiniMax-M3 Click any tile; whoever is standing there tells you what’s wrong

Once per in-game day, each mayor gets an ASCII map of its district, district and city stats, open lots, its open construction sites, land it can annex, yesterday’s results, other mayors’ posts, letters from its residents, the Gazette headline, open proposals and any player decree. It replies with JSON: a private thought, a public post, a mood, up to 7 actions (road, zone, build, bulldoze, taxes, emergency, grant, annex), an ordinance proposal and votes. The simulation checks every action and rejects invalid ones with a reason.

Simulation

Residents

About 100 named residents (one per ~10 people) each have a job, skills, traits, a household, a home, savings and a memory. Their GMI minds (scripts/ai/resident_minds.gd, batched) decide each day whether to go to work, how to commute, where to spend, what to do in the evening (including helping neighbours or protesting at city hall) and whether to move away. Traffic, wages, sales tax and moods come from those decisions instead of fixed formulas.

Incidents (fires, broken water mains, downed power lines, crashes, quakes…) never end on a timer: they stay broken until residents with the right skills and paid city crews put in enough repair work. Residents write to their mayor, and the mayor reads those letters the next day. Click a person in the city, or use the People tab, to read their mind.

Staged construction

Nothing appears instantly once people live in the city. Every build order opens a construction site (+ on the AI map) that goes through stages:

Site Stages
Service buildings clearing → excavation → foundation → frame → finishing (solar, wind and landfill skip excavation; parks are clearing → landscaping)
Zoned lots (private developers) houses: foundation → frame → finishing; shops/factories: excavation → foundation → frame → finishing; towers rebuild from the foundation; smaller upgrades add a frame and facade around the building while people keep living there
Roads / bridges clearing → grading → paving / piling → decking → paving
Demolition (bulldoze) demolition → hauling (trees: clearing; rubble: hauling)

The paid contractor puts CREW_RATE work points into every open site each tick (4 ticks a day). With contractors alone a park takes about a day, a road a day, a bridge 2.5 days, a police station 3, a hospital 4, a coal plant 9, a stadium 12 and an airport 15. Private developers take about 2 days for houses and 6 for a tower, and run at most MAX_ZONE_SITES (10) sites per district at once. Residents with construction skills (construction workers, civil engineers, electricians, water engineers) spend their working day on the nearest site; together they can add up to HELPER_CAP (60%) of a contractor shift per tick. They are paid a day rate, remember what they helped build, and show up in the tile inspector’s crew list. A building does nothing until it is finished. Sites survive save/load.

Orders you place on foot from the phone go to your own two building crews instead of the contractors. A crew builds one order at a time in real time: 2 minutes for a park up to 5 for the airport at speed 1, and 10 seconds per road tile. A third order waits for the first crew to free up. You can watch them work on site: a foreman by the gate, two builders, and a hauler carrying crates from a pile to the work. A board over the gate names the crew, the order, the stage and the time left. They stand on the ground, among the rebar, on the slab and between the frame’s columns, and on the scaffold once the building fills its lot. A crew that takes an order while you play walks in through the gate.

Progress shows continuously, not stage by stage: the view runs each site forward between ticks at its recent work rate, and each stage changes as work goes in. Trees come down and stumps are pulled, the pit widens and the spoil heaps grow, rebar goes in before the slab is poured across, the frame rises floor by floor, safety netting rolls up, asphalt is laid end to end, bridge piers rise, and demolished buildings sink into a growing rubble pile that is then hauled away.

The view draws each stage with a fenced dirt lot, an excavated pit with spoil heaps, a wet concrete slab with formwork and rebar, a rising concrete frame (floor by floor), scaffolding with safety netting around the finishing building, and a floodlight. Animated procedural machines work the sites: excavators, JCB-style backhoe loaders, tipping dump trucks, cement mixers with turning drums, tower cranes with slewing jibs and moving trolleys, bulldozers and road rollers.

Founding builds made before anyone lives in the city, and runs with residents off, are still instant. CitySim.construction_mode can force "staged" or "instant".

City life

Rendering

Player controls

godot --path . starts in first person at street level. Set GRIDFALL_VIEW=orbit to play the orbit city builder with the full HUD described below.

The orbit view (GRIDFALL_VIEW=orbit):

GMI inference and fallbacks

scripts/ai/gmi_client.gd calls https://api.gmi-serving.com/v1/chat/completions. The API key comes from GMI_API_KEY or from the GMI entry in ~/.factory/settings.json. Hybrid reasoning models get per-model settings so they answer instead of spending the whole token budget on reasoning: DeepSeek and Kimi get thinking: disabled, Qwen gets enable_thinking: false, and Grok gets reasoning_effort: low. A model that refuses the default temperature of 0.7 with an HTTP 400 (Kimi-K3 takes only 1) is tried again at once with 1 and keeps it for the session. Every failed live call prints one GMI_FAIL <role>/<agent> on <model>: <error> line to the output (scrubbed; never the prompt), so a run from the editor shows why replies fell back.

Each call falls back in this order:

  1. Live GMI response.
  2. Replay cache: real recorded responses in data/gmi_replay_cache.json (22 days are included), nearest day for the same agent.
  3. Heuristic fallback for that role.

The source of every call (live, cache or heuristic) is shown on the mayor cards and in the GMI Log.

The replay cache was recorded before wind farms, landfills and the big projects existed. On a replayed day, a mayor therefore also borrows at most one of those builds from its heuristic planner, and only when the district can still afford it after the replayed actions.

GRIDFALL_OFFLINE=1   # never call GMI (replay cache + heuristics)
GRIDFALL_RECORD=1    # write live responses into data/gmi_replay_cache.json
GRIDFALL_SPEED=4     # starting game speed
GRIDFALL_RESIDENTS=0 # no AI residents (old formula behaviour, instant construction)
LIVE_RESIDENTS=30    # residents_live test: how many residents call GMI (default 30)
GRIDFALL_HOUR=21.5   # freeze the clock at this hour (e.g. for night screenshots)
GRIDFALL_VIEW=orbit  # play the legacy orbit view with the full CityHud (default: first person)
GRIDFALL_MOUSE=free  # first person: never capture the mouse pointer
GRIDFALL_FP_SMOKE=1  # headless first-person smoke test (see Running)
GRIDFALL_FP_PHOTO_DIR=/tmp/gf_fp  # first-person photo tour: save eye-level shots to this folder

Running

# Play (first person; add GRIDFALL_VIEW=orbit for the orbit view and CityHud)
godot --path .
GRIDFALL_VIEW=orbit godot --path .

# The gate: parse check and unit tests (quick), plus the orbit and first-person smokes (full),
# or the windowed first-person photo tour and perf report (render). Runs offline in temp user dirs.
tools/gate.sh quick
tools/gate.sh full
tools/gate.sh render

# First-person headless smoke and photo tour
GRIDFALL_FP_SMOKE=1 godot --headless --path .
GRIDFALL_FP_PHOTO_DIR=/tmp/gf_fp GRIDFALL_PHOTO_DAYS=6 godot --path . --resolution 1600x900

# Headless smoke test (offline: 6 days, quake + crews, overlays, inspector, save/load round trip)
GRIDFALL_SMOKE_TEST=1 godot --headless --path .

# Photo tour: grow the city offline, then save landmark, dusk, night, construction and fire shots
# (GRIDFALL_PHOTO_SHOWCASE=1 also builds any missing big project first)
GRIDFALL_PHOTO_DIR=/tmp/gf_photos GRIDFALL_PHOTO_DAYS=12 godot --path . --resolution 1600x900

# Trailer: a ~30 s 1080p clip with captions and a ticker of live GMI mayor calls
# (grows a city offline once, then records with Movie Maker and encodes an MP4 for X)
tools/record_trailer.sh trailer/gridfall_trailer.mp4
# Sim unit test and a live two-day brain test
godot --headless --path . -s tools/tests/sim_test.gd
godot --headless --path . -s tools/tests/buildings_test.gd
godot --headless --path . -s tools/tests/residents_test.gd      # residents, incidents, save/load
godot --headless --path . -s tools/tests/expansion_test.gd      # annexation, survey, old-save migration, 192x192 world
godot --headless --path . -s tools/tests/construction_test.gd   # staged construction and crews
godot --headless --path . -s tools/tests/brain_live_test.gd
LIVE_RESIDENTS=10 godot --headless --path . -s tools/tests/residents_live.gd

# Rebuild the realistic models (procedural Blender + Poly Haven CC0 textures) and validate them
blender --background --python /abs/path/to/tools/blender/make_realistic_city.py -- all
blender --background --python /abs/path/to/tools/blender/validate_real.py

# Rebuild the Blender GLB assets (includes coal plant, water tower, police, fire, hospital, school, apartment tower, factory)
blender --background --python /abs/path/to/tools/blender/make_gridfall_assets.py -- all

# Re-import the Kenney CC0 kits into models/zones, models/props and models/vehicles
blender --background --python /abs/path/to/tools/blender/import_kits.py

Development setup

tools/setup.sh                       # venv with pinned tools, pre-commit hooks, first asset import
pre-commit run --all-files           # gdlint, gdformat --check, large files, secret scan
python tools/checks/run_all.py       # complexity, dead code, duplicates, module boundaries, TODOs, flags
python -m pytest                     # Python tooling tests (coverage gate, >= 80%)

Requires Godot 4.7.x (.godot-version) and Python 3.10+. Run the Python tools from the venv tools/setup.sh creates (. ~/.venvs/gridfall-tools/bin/activate). A dev container with both is in .devcontainer/. See AGENTS.md and CONTRIBUTING.md for rules and workflow, and docs/runbooks/ when something breaks.

Build and export

tools/export.sh linux                # build/linux/gridfall.x86_64 (+ .pck)
tools/export.sh windows              # build/windows/gridfall.exe (+ .pck)
tools/export.sh all                  # both presets in export_presets.cfg

Export needs the Godot export templates for the version in .godot-version (Editor > Manage Export Templates, or tools/export.sh prints the download commands when they are missing). Releases are cut with tools/release.sh <version> (for example tools/release.sh 0.2.0), which updates VERSION and CHANGELOG.md, commits and tags; pushing the tag runs the release workflow, which runs the gate, exports both platforms and publishes a GitHub Release with zips, checksums and generated notes. Each zip also carries the player guide tools/release/PLAYING.md (which heads the release notes) and a play-orbit launcher for the orbit view.

Code map

License

GridFall’s code is released under the MIT License. Third-party assets keep their own licenses, listed below.

Asset credits

Building, prop and vehicle models in models/zones, models/props and models/vehicles are adapted from Kenney asset kits (CC0). See models/LICENSES/. The realistic set in models/real/ is procedural Blender geometry with Poly Haven CC0 textures, HDRIs and a few embedded Poly Haven models; see models/real/LICENSES/polyhaven.txt. The dogs in models/real/animals/ are Quaternius’ Shiba Inu and Husky (CC0); see models/real/LICENSES/quaternius-dogs.txt. The cat there is Quaternius’ Cat (CC0); see models/real/LICENSES/quaternius-cat.txt.

Assets from earlier GridFall versions