Choose Simple or Advanced mode
Use the Simple and Advanced buttons at the top of the main game. Simple is the default for new visitors: it keeps city selection, the three universes, city map, building tools, economic-system presets, timeline and main comparison visible. Detailed department panels and expert controls are hidden to make your first city easier to manage.
Choose Advanced to reveal zoning, municipal finance, disasters, citizen programs, detailed policies, historical branching, and other specialist tools. You can switch back at any time; your choice is saved only as a browser preference, not in your game JSON. Neither mode changes the economic simulation, contest scoring, or save integrity.
Citizen decisions: buy, rent, work, and move (v0.9)
Start a new city to use engine 0.3.6. In the Where will people live and work? panel, inspect how three synthetic income cohorts respond to prices, rent burden, employment, public services and economic policy. The display tracks owner and renter households, yearly home purchases, new leases, job changes, local moves, and arrivals and departures.
Choose No program, Workforce retraining, First-home access or Balanced mobility program and click Apply strategy. Programs operate in the next simulated year, cost treasury funds, and receive only the funding available. Homeowner share adjusts gradually with affordability; training has a small bounded jobs effect. Programs do not create housing stock or jobs for free.
Use the comparison chart to display homeowners, buyers, leases, job transitions or program costs at a matched year. Historical views are read-only; create a branch to explore a different policy. Older JSON saves remain on their original engine and do not gain v0.9 decisions.
City services and maintenance (v0.7)
Start a new game to use engine 0.3.3. In the City services panel, review power, water and transit coverage, choose a funded maintenance priority, and display colored service overlays on the schematic Build grid or the geography GRID. Select an existing utility or transit building and choose Repair selected asset to pay for a condition improvement. Upkeep draws from the public or private capital budget and competes with new construction.
Power/water/transportation coverage is synthetic, not real utility coverage or a prediction about named neighborhoods. Older saves replay with their original engine and do not gain service state.
Start your first game
- Open the CityBuilder game and select + New city.
- Choose New York City, Miami, Los Angeles or Harborview.
- Choose an Established city or a hypothetical Greenfield start. An optional simulation seed makes experiments repeatable.
- Click Create parallel universes. Three versions begin with the same resources.
- Choose one universe on the left, inspect its economic indicators, and advance time.
To use the v0.6 project pipeline, start a new game. Imported older saves deliberately retain their earlier construction rules.
Navigate the two maps
Real geography: Select it above the map for real reference streets and neighborhood markers (browser Internet access required). Drag to pan, use +/− to zoom, FIT to recenter and GRID to display the fictional planning cells. Shift + arrow keys pans the map.
Build view: An isometric drawing of the synthetic city. Select a tool and click a compatible cell. The GRID and isometric board refer to the same game planning cells, not real properties.
Build, zone and rehabilitate
- Select a building from the Build your city toolbar.
- In the Construction Economy panel choose Construct, then Public / treasury or Private / investment.
- Click a compatible simulated planning cell. If zoning is wrong, use Rezone first. An occupied cell may only be upgraded where the rules permit.
- New v0.3.2 games place funded projects in the Development pipeline. Advance time to see progress and possible delays. Only completed projects change housing capacity and city facilities.
- Select Inspect to review a cell or Rehabilitate to improve an eligible existing building using the owner's funds.
The game denies unaffordable or incompatible actions; no building can be obtained for free through a client-side edit.
Use the Development pipeline
The pipeline shows projects under construction, total completions, delays and abandonments. Each active project lists its financing source, simulated cell, cost and time remaining. Click a row to locate the project in Build view.
Projects reserve their full funding at approval. More regulation and limited trade can increase modeled cost or delay probability; these are deliberately simplified game mechanisms. Delayed projects can resume and eventually finish. Repeated adverse events may result in abandonment and partial salvage.
Change economic policies
Use the Economic Policy Lab on the right. Choose an ideology preset and click Apply, or adjust the sliders individually and click Apply policy changes.
Taxation, ownership, regulation, trade and spending affect the same underlying rules for every universe. Outcomes depend on the full policy mix, city conditions, and financing. The blue/red/yellow themes reflect the selected preset only and do not determine performance.
Keyboard controls and historical viewing
| Key | Action |
|---|---|
| ← | One year back |
| → | One year forward |
| ↓ | Ten years back |
| ↑ | Ten years forward |
The timeline also has clickable controls and a slider. Years before the latest saved year are read-only. To change an earlier decision, return to the relevant checkpoint and use Create branch. Keyboard arrows do not steal input while you're editing a field.
Compare parallel universes
Go to Parallel universe comparison. The chart and side-by-side city views show the same selected year across all universes. Choose metrics such as GDP, poverty, prices or neighborhood condition. If a universe has not reached that year, the interface says so rather than inventing data.
Use Create branch with a source year, new policy preset and optional name to test alternative decisions from an existing checkpoint.
Citizens, migration and housing assistance (v0.8)
The v0.8 citizen module uses engine 0.3.4 and includes a Citizens & Migration panel. It groups residents into three illustrative income cohorts rather than tracking individual people. Review households, income, unemployment, rent burden, satisfaction, arrivals and departures as time advances.
Housing assistance is optional: choose No assistance, Targeted rent assistance or Broad rent assistance, then apply. Program funding is charged to the treasury every simulated year; insufficient treasury balance reduces the effect. All decisions are recorded in the JSON event history. Older games stay on their prior engine and show an explanatory legacy message.
Privacy: The simulated household groups are synthetic; no player or resident personal information is collected.
Scenario Lab — test the model (v1.0)
Open Scenario Lab from the game header. Choose NYC, Miami, LA or Harborview, then choose 5, 10 or 25 years and 1–5 deterministic seeds. Run the same three policy presets through the same simulation rules and annual shocks. See outcomes and year-by-year trends, policy sensitivity, and validation checks.
Change a policy sensitivity lever to see the difference between an unchanged Mixed economy and a Mixed economy with one policy intervention. Export the resulting audit JSON to your PC; this report is not a playable game save. The lab does not edit, save or branch any active CityBuilder game.
Interpretation: Scenario Lab checks reproducibility and internal model consistency. It cannot validate real-world accuracy or declare any economic ideology superior; all starting economic data other than cited city population assumptions remain illustrative.
Chaos Factor, crime and crises
For new engine 0.3.6 cities, the Chaos & Security panel controls optional disasters. Chaos Factor starts OFF; crime is a separate, initially enabled citywide system that can also be disabled. Choose event types, intensity, public-safety strategy and emergency preparedness. Costs are deducted from the city treasury.
Miami includes hurricanes and floods; Los Angeles includes earthquakes and wildfires; New York City includes severe winter storms and very rare fictional major security incidents. Labor strikes, cyber disruptions, health emergencies and financial shocks can affect any city. The event probabilities are invented for gameplay, not historical rates or forecasts.
For a repeatable crisis, schedule a controlled challenge for a future year. Every parallel universe experiences the same externally generated incident and severity; different policies and readiness affect damages. The scenario history is replay-validated as part of your JSON save.
Historic years remain read-only. Use Create branch to change policies starting from a historical checkpoint.
Crisis comparison (v1.3)
After a disaster is recorded, find Same shock. Different recovery. below the three parallel city maps. Select a recorded incident and navigate with the year arrows or timeline slider. Each universe's incident-specific damage, output loss, emergency readiness at the event, and mitigation index are compared at the same year. The citywide recovery backlog and repair spending may include more than one disaster.
If a branch has not reached the review year or did not record the original incident, the dashboard identifies the missing checkpoint instead of inventing values. This screen is entirely read-only and does not alter the save file or engine calculations.
Project Goals and community feedback (v1.4)
Open Project Goals from the game menu to see the current release and a proposed roadmap. Future version labels are planning targets, not promises. Use Feedback to suggest a feature, report a bug, or ask a question.
Feedback is stored privately in a local SQLite database, separate from game saves and MariaDB. After submitting, save your unique ticket number and private receipt code; both are required to check status or read an operator reply. CityBuilder does not collect an email address, publish submissions automatically, or expose an anonymous administrator panel. Do not submit passwords, private addresses, or other sensitive information.
Feedback requests have size limits and rate limits. If the administrator has disabled the feature, the page explains that submissions are unavailable. For public use, the administrator must first enable HTTPS and review security controls.
Save, load and verify games
Click ↓ Save JSON to download a portable file to your computer. Click ↑ Load JSON and choose that file to resume it. Import validates the SHA-256 checksum and replays recorded actions against the saved engine version.
Cloud storage has been removed from the player interface and disabled by default in v0.8 to reduce security risk. Save files remain on your own PC; no game account is required. Existing MariaDB save records are not deleted by the update.
Economic calibration and historical data (v1.5)
Economic Calibration Lab compares frozen engine 0.3.6 with new engine 0.3.7 using matched seeds. New games track synthetic inflation, nominal and real wage indexes, financing rates, and investment incentives. Real-world unemployment references are 2025 metropolitan annual averages, not city-proper observations or 2026 forecasts.
The Federal Reserve’s 2% PCE is a national policy objective, not a simulated city inflation fact. Earlier years with actual observed figures are an available v2.2 Historical Backtesting feature; real observations can be explored in the separate Historical Lab, without rewriting ordinary game saves.
Understand the two version numbers
SOFTWARE identifies the installed user-interface and documentation release. ENGINE identifies the current Python simulation rules used for new games. A loaded save can use an older engine and still be valid.
The current engine is 0.4.2, while older JSON games continue with their recorded engine rules for reproducibility.
Troubleshooting
Map tiles do not load
Confirm the browser can reach OpenStreetMap and that Nginx permits the tile requests. The isometric Build view still works without map tiles.
A project won't start
Inspect the cell's zoning and occupancy, check public treasury or private capital, verify it has no existing active project, and ensure you're viewing the current year rather than read-only history.
Game feels different after an update
Imported saves preserve their recorded engine version. Create a new city to test updated rules. Check both version badges in the header.
Python API unavailable
Developers can open /documentation.html directly; this reference is intentionally absent from the game navigation.
v2.2 — Historical Backtesting Lab
Open History Lab to explore earlier years. Select NYC, Miami or Los Angeles, a starting year and an end year. The starter dataset contains verified Census 2010 and 2020 population counts, plus the 2025 estimate. Enter or import additional cited observations as JSON or CSV; every number needs a geography, units, reference date, publisher and source URL.
Run three reproducible counterfactual paths with the same seed. Compare observed points to simulated lines at a selected year. Missing years are not filled in. Metro/county numbers and inconsistent dollar definitions are reference only. The rest of the historical initial state remains a synthetic game approximation, not an empirically reconstructed historical economy.
Export your historical dataset or complete report locally. The History Lab stores no observations in MariaDB, SQLite or public Cloud saves. Its report is separate from CityBuilder game JSON and cannot enter contests. The ordinary game's arrow-key historical checkpoints are a distinct feature.