lumbridge-public/tera
Archived
1
0
Fork 0
Code Activity

feat: one California as one pack, behind ?one=1

Browse Source 
The nesting preview is gone and this replaces it. That one drew each metro's
built scene inside the state board's under a similarity transform; the transform
was right and two independently built terrains then occupied the same ground and
interpenetrated. `cities/unify.ts` is the version with no seam to stitch,
because the way to not have two grids is to not have two grids: one `City`
carrying the state's landform and both metros' detail, so the engine builds one
world, one lattice and one terrain mesh.

**The merge is mostly a union and twice it must not be.** Everything that
describes a place in a `City` is absolute lat/lng, so hills, districts,
landmarks, bridges, ports and airports concatenate. Two do not:

  - `World.elevationAt` *blends* every hill covering a point, so leaving the
    state's coarse hills under a metro's fine ones adds their heights and lifts
    the whole Bay. 25 state hills are dropped where a metro replaces them.
  - The state's 17 districts include coarse stand-ins for both metros against
    the metros' 99 real ones, and both drawn is two cities in one place. 9 go.

Filtering is by centre-in-bounds, which is honest and not exact, and the file
says so rather than hiding it.

**The lattice was the whole question and the answer was measured, twice.**
`TODO.md` records a statewide lattice at metro fidelity as 23.7M points and
dead. That is true at San Francisco's own 45 m cell, because `buildAxis` refines
per *axis* — a plus, not a box — so two metros at opposite corners refine most
of the state. The blowup is a function of the fine cell and is gentle until 45 m,
so the first pass took 150 m / x8, or 1.23M points.

That rendered **1,114,226 triangles at the whole-board pose against a 440,000
cap**, and the useful part is where it did *not* come from: with every metro
building hidden, triangles fell by 43,000 and draw calls by 111. The buildings
were never the cost. Terrain was. So the fine cell is what a statewide board can
afford without terrain LOD, and that is **300 m / x16** — 0.18M points, 11.6x
finer than the state pack's 3,473 m cell and 6.7x coarser than San Francisco's
own board. Measured at that size: california 392,862 triangles of 440,000 and
california-drive 405,124 of 430,000, both green on desktop.

**And the detail LOD is the cheapest kind there is.** `createBlocks` now orders
every `detail` district's lots *last*, so hiding 99 districts' buildings is one
assignment to `InstancedMesh.count` — no second mesh, no second draw call, no
allocation, and nothing for `nightlights.ts` to learn, since it holds the same
mesh either way. Landmarks are one mesh each so theirs is a `visible` flag.

The reveal is two tests and needed both. Stand-off alone passes for the drive
chapter, whose camera sits a few tens of metres off the ground half way up the
state while being two hundred kilometres from the nearest building this governs
— measured, it failed `california-drive` on triangles for lots nobody could see.
So detail draws only when the camera is inside `DETAIL_STANDOFF_M` *and* its
**target** is within `DETAIL_REACH_M` of a detail district. The target rather
than the camera, because the target is what is being looked at.

`src/test/unify.test.ts` pins the two non-union merges, the detail marking and
the lattice size. Writing it turned up something worth keeping: **six hills are
named in both the state pack and a metro pack** — Marin Headlands, San Bruno
Mountain, Mount Diablo, Bolinas Ridge, Mount Gleason, Mount Wilson — so the
first version failed on San Francisco's own Marin Headlands, identified as a
state hill by its name. `ladder.ts` hit this with "Whole Board" on two boards.
A name is not an identity; the test keys on the object.

Known and not fixed: mobile draw calls are 428 of 415 and 315 of 280 on the
merged board, from the port, vessel and bridge layers that the state board never
carried before and that no LOD hides yet. That is why this is still a flag.
Default is untouched and the full budget passes with it off.

1,700 tests pass.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Kartios
2026-08-24 02:19:14 -07:00
parent 122497088c
commit 15d7accdbb
6 changed files with 531 additions and 92 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/cities/unify.ts
+236
View File
@@ -0,0 +1,236 @@
/**
* One California, from three packs — as **one pack**, not three boards.
*
* ## Why this exists, and why it is not `reconcile.ts`
*
* `reconcile.ts` makes the three packs *agree*: one projection, one relief-in-
* frame, one road width. It leaves three boards that draw the same California
* and hands the camera between them. That was the answer to "the boards feel
* like three products". It is not the answer to "I want one full California",
* which is this file: a single `City` carrying the state's landform and both
* metros' detail, so the engine builds **one world, one lattice and one terrain
* mesh** and there is no seam anywhere to stitch.
*
* ## Why one pack rather than three scenes nested in each other
*
* The first attempt nested each metro's built scene inside the state board's
* under a similarity transform. The transform was right — measured, both metros
* landed where they belong at the size they should be — but two independently
* built terrains then occupied the same ground and interpenetrated: a block sat
* neatly on a coarse hill in one place and was half-buried in it three hundred
* metres away. That is nested-grid stitching, and the way to not have the
* problem is to not have two grids. One pack has one.
*
* ## The lattice is affordable, and the number that says so was measured
*
* `TODO.md` records a statewide lattice at metro fidelity as 23.7M points and
* dead. That is true at San Francisco's own 45 m cell, because `buildAxis`
* refines per **axis** — a focus region refines its whole row *and* its whole
* column, a plus rather than a box — so two metros at opposite corners refine
* most of the state. The blowup is a function of the fine cell, and it is
* gentle until 45 m:
*
* | fine cell | coarse | lattice | points | memory |
* | --- | --- | --- | --- | --- |
* | 45 m | x16 | 6002 x 7600 | 45.6M | 411 MB |
* | 100 m | x8 | 1676 x 2002 | 3.36M | 30 MB |
* | **150 m** | **x8** | **1120 x 1349** | **1.51M** | **14 MB** |
* | 200 m | x8 | 850 x 1013 | 0.86M | 8 MB |
*
* All three of today's boards together are 0.75M points. So 150 m costs about
* twice the whole product's current terrain and buys ground **23 times finer
* than the state board's 3,473 m cell** everywhere a city stands. No quadtree,
* no per-rectangle refinement, no change to `buildAxis` at all.
*
* ## What this file must do beyond concatenating arrays
*
* Everything in a `City` that describes a place is absolute — hills, districts,
* landmarks, bridges, ports and airports are all lat/lng — so most of the merge
* is a union. Two things are not:
*
* - **Hills sum.** `World.elevationAt` blends every hill that covers a point
* (tallest, plus 35% of the rest), so leaving the state's coarse hills under
* a metro's fine ones *adds* their heights and lifts the whole Bay. The
* state's hills are dropped where a metro replaces them.
* - **Districts overlap.** The state's seventeen districts include coarse
* stand-ins for Los Angeles and San Francisco; the metros carry 99 real
* ones. Both drawn is two cities in one place, so the coarse stand-ins go.
*
* Both filters are by centre-in-bounds, which is honest but not exact: a state
* hill centred outside a metro with a radius reaching into it still contributes.
* At the state's hill radii that is a gentle lift at the edge of a metro rather
* than a doubled mountain, and it is recorded here rather than hidden.
*/
import type { City, District, FocusRegion, Hill, LatLng } from "../engine/types.ts";
import { reconciledCity } from "./reconcile.ts";
import CALIFORNIA from "./california.ts";
import SAN_FRANCISCO from "./sf.ts";
import SOCAL from "./socal.ts";
/**
* The fine cell, in metres, and the factor the rest of the state is drawn at.
*
* **300 m, and it was measured down to that from 150.** The first pass used
* 150 m / x8, which is 1.23M lattice points, and the merged board then rendered
* **1,114,226 triangles at the whole-board pose against a 440,000 cap** — with
* every metro building already hidden by the detail LOD. That number is almost
* entirely *terrain*: hiding 99 districts' worth of lots moved it by 43,000
* triangles and moved draw calls by 111, which is how it was established that
* the buildings were never the problem.
*
* So the fine cell is what a statewide board can afford, and the honest ceiling
* on this engine — with no terrain level of detail, which is the piece that does
* not exist yet — is around 300 m / x16, or 0.18M points. That is **11.6x finer
* than the state pack's 3,473 m cell** and 6.7x coarser than San Francisco's own
* 45 m board.
*
* Closing that last gap is terrain LOD, and `TODO.md` already names its three
* blockers: placement drift (everything is placed once against `groundAt`), the
* shadow caster (15x triangles if selected independently), and determinism (the
* budget harness assumes geometry is not a function of camera path). None of
* them is in this file's way, and all of them are in that one's.
*/
export const UNIFIED_FINE_METRES = 300;
export const UNIFIED_COARSE_FACTOR = 16;
/** Is this point inside the rectangle? */
function within(lat: number, lng: number, r: FocusRegion): boolean {
return lat >= r.minLat && lat <= r.maxLat && lng >= r.minLng && lng <= r.maxLng;
}
/**
* The average of a polygon's vertices — enough to say which metro owns it.
*
* `LatLng` is a `[number, number]` tuple in this codebase and not an object, so
* the destructuring below is the whole of the type story.
*/
function centroid(polygon: readonly LatLng[]): { lat: number; lng: number } {
let lat = 0;
let lng = 0;
for (const [pLat, pLng] of polygon) {
lat += pLat;
lng += pLng;
}
const n = Math.max(1, polygon.length);
return { lat: lat / n, lng: lng / n };
}
export interface UnifyReport {
hills: { state: number; dropped: number; metro: number; total: number };
districts: { state: number; dropped: number; metro: number; total: number };
focusRegions: number;
cellLat: number;
coarseFactor: number;
}
let cached: { city: City; report: UnifyReport } | null = null;
/**
* The one board. Memoised, because `World` builds one per mount and the merge
* walks every district polygon in the product.
*/
export function unifiedCalifornia(): { city: City; report: UnifyReport } {
if (cached !== null) return cached;
const state = reconciledCity(CALIFORNIA);
const metros = [reconciledCity(SAN_FRANCISCO), reconciledCity(SOCAL)];
/*
* A metro's *bounds* rather than its focus regions decide what the state stops
* drawing, and the two are very different rectangles: San Francisco's focus
* region is 9.2% of its own board and its bounds are all of it. The state's
* coarse stand-in for a city covers the whole metro, so the whole metro is
* what has to be cleared — clearing only the focus region would leave a coarse
* Oakland beside a fine San Francisco.
*/
const claimed: FocusRegion[] = metros.map((m) => ({ ...m.bounds }));
const claims = (lat: number, lng: number): boolean =>
claimed.some((r) => within(lat, lng, r));
const stateHills = state.hills.filter((h: Hill) => !claims(h.lat, h.lng));
const metroHills = metros.flatMap((m) => m.hills);
const stateDistricts = state.districts.filter((d: District) => {
const c = centroid(d.polygon);
return !claims(c.lat, c.lng);
});
/*
* Marked `detail`, which is the flag `createBlocks` orders on and `scene.ts`
* reveals by camera stand-off. Without it the merged board measured 1,157,802
* triangles at the whole-board pose against a 440,000 cap, for buildings that
* are sub-pixel at 1,919 m to the unit. The lots exist either way; the flag
* decides when they are drawn.
*/
const metroDistricts: District[] = metros.flatMap((m) =>
m.districts.map((d) => ({ ...d, detail: true as const })),
);
const fine = UNIFIED_FINE_METRES / 111_320;
const city: City = {
...state,
/*
* The state's own id, on purpose. Every consumer that keys off a board — the
* fire gate, the ladder's region table, the budget harness's `data-board`
* assertion, `?city=` — already knows "california", and this *is* California.
* A new id would mean teaching all of them about a fourth board, which is
* the opposite of the point.
*/
id: state.id,
name: state.name,
cellLat: fine,
// The same lat:lng cell ratio the state pack authored, so cells stay square
// on the ground at this latitude rather than becoming letterboxes.
cellLng: fine * (CALIFORNIA.cellLng / CALIFORNIA.cellLat),
coarseFactor: UNIFIED_COARSE_FACTOR,
focusRegions: metros.flatMap((m) => m.focusRegions ?? []),
hills: [...stateHills, ...metroHills],
districts: [...stateDistricts, ...metroDistricts],
landmarks: [
...state.landmarks,
...metros.flatMap((m) => m.landmarks.map((l) => ({ ...l, detail: true as const }))),
],
bridges: [...state.bridges, ...metros.flatMap((m) => m.bridges)],
parks: [...state.parks, ...metros.flatMap((m) => m.parks)],
inlandWater: [...state.inlandWater, ...metros.flatMap((m) => m.inlandWater)],
airports: [...(state.airports ?? []), ...metros.flatMap((m) => m.airports ?? [])],
ports: [...(state.ports ?? []), ...metros.flatMap((m) => m.ports ?? [])],
/*
* Chapters are the state's alone. The metros' twenty-four rungs are poses
* expressed in *their* boards' framing, and `ladder.ts` already presents all
* of them as one list; re-pointing them at this board is its own piece of
* work and a wrong pose is a camera in the ground.
*/
chapters: state.chapters,
/*
* Landmasses are NOT unioned. `isLand` is a point-in-any-polygon test, so a
* metro's finer coastline can only ever add land the state's outline already
* claimed — while costing a polygon test per sample over a 1.5M-point
* lattice. The state's coastline is the state's coastline.
*/
landmasses: state.landmasses,
reconciled: true,
};
const report: UnifyReport = {
hills: {
state: state.hills.length,
dropped: state.hills.length - stateHills.length,
metro: metroHills.length,
total: city.hills.length,
},
districts: {
state: state.districts.length,
dropped: state.districts.length - stateDistricts.length,
metro: metroDistricts.length,
total: city.districts.length,
},
focusRegions: city.focusRegions?.length ?? 0,
cellLat: fine,
coarseFactor: UNIFIED_COARSE_FACTOR,
};
cached = { city, report };
return cached;
}