Baking a city offline for a faster start

Why

Slopcouver builds the city in the browser from open data every time it starts. On an iPad that takes about a minute to the first frame. One step, "cutting" the city's flat ground layers (roads, sidewalks, parks) to the shape of the terrain, ran on every cold start even though its inputs only change when the data changes. The game already saved cut tiles in the browser's storage, so a second visit was faster, but a first visit, a cleared cache, or a new release paid the full cost.

Hypothesis

1. The game's own ground code can run unchanged outside the browser (in Node) and produce exactly the tiles Safari would cut.
2. Downloading those tiles instead of cutting them shortens the iPad's cold start, measured as the ground step and the time to first frame.

Method

• Run the builders in Node: a small harness maps the game's imports to the vendored three.js (r187), stubs the page's host framework, runs the game's ground worker in Node worker threads, and provides an in-memory IndexedDB. The game's own setOnTerrain saves its cut tiles into it: exactly the records an iPad stores.
• Cross-engine check: run the same modules in macOS's JavaScriptCore shell (Safari's engine) and compare every mesh and tile byte for byte with Node's V8.
• Formats: first, exact tiles (unique vertices plus an index, gzip); then a compact format: positions quantised on one city-wide grid (1/64 m across, 1/256 m up), octahedral normals, planar UVs dropped and rebuilt, then meshoptimizer's vertex and index codecs (meshoptimizer 1.3.0, MIT; the decoder already ships with three.js), packed into bundles of many tiles.
• The test: physical iPad Pro 11-inch (M5), Safari, phone tier, starting at the Stanley Park card. Interleaved A/B: A cuts as before, B reads the bake. Every cold run on a never-used origin so nothing is cached. Three cold runs per arm per session.
• Hardware and time: a Mac for the bake (the whole city in about 97 s), the iPad for timing. No cost.

Results

1. Node and Safari cut identical tiles, but disagreed on the name

• All 201 core city-grid meshes are bit-identical in V8 and JavaScriptCore, and all 884 core tile records cut in both engines have the same bytes.
• But the key each tile is saved under hashed the bridge decks' lengths, and Math.hypot is not correctly rounded: the two engines differ in the last bit for 120 deck numbers. So Safari computed a different key and would never have found a tile baked in Node. Switching to Math.sqrt(dx*dx + dz*dz), which is exact in every engine, made the key identical everywhere. The iPad then used every baked tile, which confirms the fix on the device.

2. The first form saved nothing

3. Fewer, smaller files

4. The compact bundles on the iPad (shipped form)

• Regions built during play read from the bake too: a jump to UBC read its whole ground layer instead of cutting it; Kitsilano's 21 tiles in 1.6 s against 4.1 s.
• On a slow link the bake loses. Throttled to "4G" (9 Mbps, 60 ms) on a fast desktop CPU: cut 53.6 / 53.6 s against baked 57.4 / 59.2 s. So the loader measures its first bundle; if the rest would take over 3 s, it cuts those tiles instead.
• Whole city: 5,982 tile records in 980 bundles, 74.2 MB gzipped (1.6 GB as cut), worst error 7.8 mm across and 2.0 mm up.

5. What it doesn't fix

The first frame stays near 50 s because the ground was never the main cost. A profile of the whole start puts the traffic network (a road graph built with millions of box tests) and the late "ground" stage of about 30 small parts ahead of it. The next design bakes whole parts (their meshes and the data the rest of the start reads from them), aiming at a start under 15 s; that work is designed and its first slice is being built.

Limitations and threats to validity

• Small samples: three cold runs per arm per session. Sessions drift (shader compile went from 6.1 to 9.1 s over one session), and the first-frame saving (−3.2 s) is inside the run-to-run spread. The ground-step saving (−3.6 s) is well outside it.
• One start location, one tier, one device. Two of 19 tiles in one region didn't match the bake because that region's flat layer depends on which regions loaded first; they were cut instead (the key prevents a wrong tile, not an unused one).
• Beach sand and street details are still cut in the browser (they depend on tier and season).

Verdict

Practical application

• For the game: faster, steadier starts on phones and tablets; the ground step went from 5.3–7.5 s to 4.1–4.3 s across runs.
• For any browser app that builds geometry from data: precompute in the same code, not a port; check byte equality across JavaScript engines (watch Math.hypot, atan2 and other functions that aren't correctly rounded); ship few, compact bundles, not many small files; and keep the in-browser path as a fallback for slow links.
• What it takes to run: the bake is regenerated with each data release (about 1.5 minutes on a laptop) and checked against the release tree before deploy.

Reproducibility

In the Slopcouver repository (private for now): app/tools/bake/ (Node harness, bake-ground.mjs, quantize.mjs, check-bake, quant-check.mjs, the JavaScriptCore check jsc/check.sh).

(cd app/tools/bake && npm ci)       # pins meshoptimizer 1.3.0
node app/tools/bake/bake-ground.mjs --pack <copy of cities/vancouver> --out <folder>   # compact format by default; decodes and bound-checks every record
node app/tools/bake/check-bake.mjs <release app dir> <index-stream.json>          # the bake matches this code and pack

Credits: three.js (MIT), meshoptimizer by Arseny Kapoulkine (MIT). City data: City of Vancouver Open Data (OGL–Vancouver), OpenStreetMap contributors (ODbL).