Skip to content

Graphics performance controls ​

The client and terrain packages reduce work on both Three.js backends. Backend selection is covered in WebGPU and WebGL. These controls affect presentation; headless simulation, entity IDs and authored geometry remain authoritative.

Static scenes and sparse motion ​

Client delta ingestion stores only changed transforms in a short interpolation history. The frame loop samples active interpolations, applies the final pose once, and then retires them. Static entities retain their last pose. Keyframes, binding replacement, teleports and resync still restore presentation state; full keyframes necessarily visit the full scene.

Opaque primitive and static GLB meshes sharing geometry, material identities, shadow flags and render layers are instanced within spatial cells. Animated, skinned, morph-target, transparent, custom shader/node-material and custom render-callback meshes remain ordinary meshes. An entity that subsequently moves leaves its static batch. The original entity objects retain identity; client.entityForIntersection(hit) (also available on ThreeSceneBackend) maps ray hits to entity IDs. getObject(id) opts that entity out and restores mutable Three transforms for the escape hatch.

ts
const client = await createClient(worker, {
  canvas,
  sceneOptimization: {
    staticInstancing: { cellSize: 32, minInstances: 2 }, // defaults; false disables
    shaderWarmup: true,
    animation: { distantDistance: 80, distantHz: 15, hiddenHz: 5 },
    // maxLocalLights: 16, // optional quality tradeoff; no count cap by default
  },
});
await client.ready();

Smaller instance cells improve culling and larger cells reduce draws. A batch can submit triangles belonging to individually offscreen members, so fewer draws do not guarantee less GPU work. Static local matrices are frozen; floating-origin motion still updates world matrices.

Live animations use the simulation tick at every sampled pose, without clock accumulation. Visible nearby meshes and visible shadow casters retain full-rate sampling. Distant meshes sample at 15 Hz and hidden meshes at 5 Hz by default; returning nearby updates immediately. Use animation: false for full-rate sampling everywhere. Snapshot/capture poses remain exact. Finite local lights whose entire influence sphere lies outside the camera frustum are omitted. An explicit light-count cap ranks remaining lights by intensity/distance and can change images. On WebGPU, capped point lights without shadows use persistent shader slots: moving or turning changes each slot's position, color and intensity instead of compiling a new lighting shader for every selected combination. Unused slots have zero intensity. Shadow-casting lights and spotlights retain their own objects.

Resuming a paused simulation re-anchors the interpolation clock while keeping its pose history. Loading screens and paused manual turns therefore do not leave live motion snapping between simulation ticks while the clock slowly catches up.

Staged preparation and admission ​

Each Renderer owns a FrameAdmissionQueue, configurable with the admission option:

Renderer defaults are 2 ms on WebGL and 8 ms on WebGPU, with 2 MiB and 32 jobs per frame. WebGPU's individual Three node-builder steps commonly exceed 2 ms; the larger budget avoids admitting only one mesh per frame in large worlds. Explicit budgets override these defaults.

ts
const viewer = await createViewer({
  canvas,
  admission: {
    maxMilliseconds: 2, // explicit low-latency budget; WebGPU default is 8
    maxBytes: 2 * 1024 * 1024,
    maxJobs: 32,
    onSample(sample) { /* label, workMs, queueMs, bytes, overBudget, background */ },
  },
});

The queue limits synchronous work started per animation frame. One oversized indivisible job runs alone and is reported as over budget, and the frames after it repay the excess, so the budget holds on average: a 20 ms instanced shader build every third frame rather than every frame at half the frame rate, for the same throughput. The budget is a share of a frame at 60 a second, so a frame that comes slower repays the same share of its own length. Under software rendering, where a frame takes 200 ms or more and one wait on the GPU charges a job for all of it, repaying the fixed budget per frame left the queue idle for minutes. Frames that slow, three in a row (100 ms or more each while work waits), also get that share of themselves as budget: 2 ms of a 450 ms software frame left streaming under half a percent of the time, and a town's semantic layers spent their two-minute deadline in the queue. Interactive rates and a single long frame keep the fixed budget. setLimits changes the budget from the next frame on.

A fixed small budget protects the frame rate of a view that keeps up, and starves one that does not. backlog: { afterMs, maxMilliseconds, maxBytes } (in the options or setLimits) lets the budget grow while work is backing up: once the oldest waiting job outside the background lane has waited afterMs, the frame's time and byte budgets rise with its wait and reach the backlog values at twice that. They fall back as soon as the queue keeps up again, so a view at rest and a slow pan never pay for it. A job's priority is 'normal', 'background' or 'urgent' (ahead of normal jobs, in its own order). Background jobs run in budget normal jobs leave and, once one has waited backgroundWaitMs (default 750), take a turn after every backgroundShare other jobs (default 8): in flight normal work never runs out, and texture upgrades and the levels an object is not yet showing arrived a second late on average and five at worst. Urgent work is how the terrain stream admits ground, and it marks a tile group userData.admissionPriority = 'urgent' so prepareObject queues its upload the same way, because a tile's residency otherwise waited behind every building cell's upload. A root marked 'background' prepares only in budget normal jobs leave: World Explorer's practice aircraft load with the world that way, as in the normal lane their ~200 jobs held terrain and buildings back by most of a minute on a software renderer.

Continuous urgent traffic shares service with normal work: after two urgent jobs, a normal job waiting at least 50 ms gets a turn, including when each urgent job consumes a whole frame. Normal jobs may provide order: () => number (lower first), read at dispatch so a moving camera can reprioritize queued work. After three ordered jobs, the FIFO head gets a turn; shared decodes and unrelated scene work continue to progress. These rules stay within the same frame budgets. Terrain layer contexts scope this live order through generation and assembly; their GPU preparation uses userData.admissionOrder, and publication keeps the same order. Only immediate replacement siblings inherit a parent's priority; a distant ancestor must not give a whole city's leaves the same priority.

Main-thread work that runs as a tile's sources resolve is admitted too, because several tiles arriving together stacked it into one late frame: decoding vector tiles (the package semantic layers' admission option), a worldgen request's own preparation, prop batches, surface results from a worker (their meshes and parked cars), and ambient aircraft models (admission on createAmbientRenderer and EarthAmbient). A worldgen request is three jobs: the tile's content hash, the generator's optional prepare step (its ground grid, sampled once for both of a tile's passes) and the message to a worker; in one piece a dense town tile's took 8-16 ms. A job runs first in a frame however long it takes, but after other work the queue starts a job only when the recent time of its label fits the budget left, so two long jobs never share a frame. Street surfaces (roads, markings, parked cars) are generated by createTerrainSurfaceWorkerPool, which spreads them over the workers it is given. Earth hosts size the world generation pool with generationWorkers() (a quarter of the logical cores, at most two, below 16 cores) and the land cover and surface pools with surfaceWorkers() (one each below 16 cores). On a 12-core laptop four per kind took the cores the frame needs, and a jet's frames drew the same scene up to twice as slowly while a town streamed in; two land cover and two surface workers beside generation still slowed some frames threefold over a dense city, while one of each streamed a low flight just as fast and loaded the first view about a fifth later. A workstation has cores to spare, and there one land cover worker is the bottleneck: from 16 logical cores the pools are three generation and two of each surface kind, from 24 four and three. On 32 cores that cut a tile's land cover from 1.7 s to 0.5 s on average, finished the first view in 13 s instead of 23 s, and missed fewer frames. New kinds of ambient proxy batch stay hidden until their shaders are built, as figures and aircraft do.

A tile observer (observeSemanticTiles) is handed each decoded tile, and what it keeps stays on the main heap that every garbage collection walks, in pauses that land on frames. Keep the fields you read, not the tile: EarthAmbient keeps a tile's roads and places, EarthAudioTerrain only the water of a tile too coarse to choose the ground underfoot, and wildlife compiles its habitat into a few typed arrays and lets the tile go. A renderer that may rebuild a tile later keeps keepTerrainSemanticTile(tile) instead: a call that answers the tile while it lives and otherwise decodes it again from the packet it arrived as. Kept whole, these held 95 decoded tiles over Kyoto, some 1.4 million of the objects each collection walks.

Three updates every object's world matrix each frame, hidden ones included. Hidden terrain tiles, pooled ambient figures (each with its skeleton) and the explorer's parked-aircraft cockpits skip that walk until they show again.

Three also culls one mesh at a time, and only once it has walked to it: for world matrices, for levels of detail and what to draw, and once more for each shadow map. A streamed world keeps most of its tiles outside the view, finished and ready for a turn of the camera. On WebGL the renderer leaves a render group (createRenderGroup, which the terrain stream uses for each tile) out of the scene walk while its bounds lie wholly outside the camera's view, and out of a directional light's shadow map while they lie outside that map; a group the camera cannot see still casts into a map that reaches it. The group is hidden for the render alone, so nothing else sees it change. Its owner states the bounds in userData.renderBounds (RENDER_BOUNDS: a Box3 in the frame of the group's parent, holding everything it draws) and keeps them true: expandRenderBounds measures content from the bounds its meshes carry, and code that adds or replaces geometry inside streamed content later (a landmark's next level of detail) calls markRenderBoundsChanged(object), after which the group is not culled until its owner has measured it again. The terrain stream does all of this for its tiles. Over Seattle at High about half of the tiles on show lay outside the view of a low flight, and leaving them out took the main thread's time in a frame's render from 17-22 ms to 12-13 ms with the same draws. cullRenderGroups: false turns it off (?cull=0 in World Explorer).

An instanced detail switch (the level-of-detail batch for plants and props) chooses its level again only once the camera could have reached a handover: each choice keeps how far the measured distance was from the nearest threshold, and the camera's travel since, with any change in the error budgets, is weighed against that. In flight nearly every batch is well short of its next handover, and choosing again for each of some 2,200 of them every frame was 2.6 ms of a 33 ms frame.

Far detail stops drawing: a surface tile's signs, fixtures, signal lenses, markings and parked cars past their draw distance (updateDetail, see surface rendering) and street props below 1.5 px (vanishPixels, see worldgen); at High over a town that cut a fifth of the draws. A visibility pass makes its first ground cut whatever it costs, but only 4 ms more (TerrainGroundCutoutController.update's budget); the rest keep their current cut until the next frame, so tiles arriving together no longer hold one frame for every cut they need. stream.updateTransitions(nowMs) carries those cuts on every frame, sharing one 4 ms budget a frame with stream.update: hosts update the stream ten times a second while the camera is still, and at one budget an update, ground that a descent had just shown stood uncut over its own harbor for most of a second.

Where the stream's height source can cut off the main thread (TerrainPyramidHeightSource.cutGround, a TerrainGroundCutter; the elevation worker's source has one), the clipping is done there. The controller sends the mesh's arrays as copies, goes on to other ground, and swaps the cut in when it lands, so the frame's budget pays for gathering openings and the swap alone; a cut whose opening goes meanwhile is called off, and one the cutter fails is made on the main thread. A mesh of fewer than 5,000 vertices (cutVertices) is still cut on the main thread, in the pass that first shows it: a few milliseconds, against ground standing uncut for the trip's frames. A tile's land cover over a shoreline is some 38,000 vertices against 50 openings: 46 ms of clipping, of which a low flight over Seattle at High finished 48 in 50 seconds at 4 ms a frame, leaving most ground it passed waiting for its cut. The worker made some 250 in a minute of the same flight, and cutting fell from 7% of the main thread to under 2%.

Earth hosts admit more while frames have time to spare: createEarthAdmissionGovernor(backend) smooths each frame's main-thread work and, through earthAdmission, switches the queue to 8 MiB of uploads a frame (and 4 ms of work on WebGL) below 10 ms of work, back to the renderer's defaults above 13 ms. Each terrain tile and layer passes several admission jobs; at 2 MiB a frame everything behind a building cell's upload waited 30 ms a job, and ground and buildings beneath a jet appeared a second late. A render-bound frame (High detail over a town) loses a sixth of its rate to the larger budget, so it keeps the defaults while it keeps up. Either budget carries a backlog (above) that grows it toward the arrival budget, 8 ms and 16 MiB, once work has waited EARTH_BACKLOG_MS (400 ms): a P-51 at 290 kt over Seattle at High always had busy frames, the 2 ms published a quarter of the layers the flight asked for, each job waited 3 s on average for each of a layer's several turns, and no tile beyond 2 km had all of its layers on show at any point of the flight: bare ground ahead, buildings arriving beneath. Held at 4 ms the same flight kept its 30 frames a second and finished four fifths of the ground within 2 km; at 8 ms it finished nearly all of the view at 22 frames a second, drawing three times the triangles. The backlog moves between the two as the queue needs. This is not a hard GPU/driver time bound. Texture initialization, geometry preparation and async shader compilation use public Three facilities; shared resources share pending preparation promises. A cancelled tile cannot cancel another tile waiting on the same resource; queued work is dropped once every tile waiting for it has cancelled. Prepared static batches replace ordinary meshes only when ready; stale batch results are discarded. When prepareObject receives the parent the object will join, it evaluates LODs for the current camera and waits only for the selected levels. The other levels prepare in the queue's background lane (priority: 'background'), which runs only in budget that normal jobs leave, and are dropped if their mesh or geometry is disposed first. This includes geometry-switch LODs whose current level is empty: invisible ground cover does not delay an aerial tile, and a later approach waits for its preparation before revealing it. Preparation shares the visible-light list instead of walking the whole scene for each mesh, and the walk that finds the lights is made again only when the scene's own children change or a quarter of a second has passed (each frame still checks which of them are on show): once a frame, it was 1.2 ms of every frame of a flight over a city. A mesh that swaps its own material (an instanced detail switch's opaque and shadow-free twins) lists every material in userData.materialVariants, and the renderer sets userData.materialReady(material), which the mesh's owner asks before switching. Until it returns true the owner keeps what it shows; the first question queues that material's build ahead of other work, so variants a mesh never switches to are never built. Shadow flags are part of what a mesh's shaders are built for, so set castShadow and receiveShadow before preparing (the terrain stream marks layers and surfaces first). Resident world-generation quality replacements use the same preparation/publication path when supplied with WorldgenRendererOptions.prepareObject (enabled in World Explorer).

Preparation remembers each material's builds under what a program is built for besides the material: the mesh's instancing, instance colors, skinning, attributes and morph targets, and the scene's lights (which cast shadows), shadow map, fog, environment and output. A material built before the sky's sun or its shadows existed is built again for the next mesh that draws it, instead of counting as prepared and building mid-frame. A material changed in place needs its new program first: await renderer.prepareMaterialChange(current, next) builds next for every kind of prepared mesh that draws current, in the background lane, after which current.copy(next) reuses the shared program. Progressive building materials do this through ResolvedMaterialSetOptions.prepareChange (Earth hosts pass prepareMaterialChange to createEarthWorldgen); upgrading a placeholder as its texture bake landed rebuilt every visible building's shaders in one frame, seconds into a session.

On WebGL a warm-up waits for the programs its own compile built. three.js's compileAsync checks each material's current program, which the next frame resets for whatever it drew last: a material shared with drawn meshes (every building's wall) reported its ready program while the instanced variant was still linking, and that variant's first draw waited for the link, 130 ms in flight. Content that appears beside the viewer is prepared before it shows as well: building interiors (InteriorStreamingOptions.prepare, which the Earth renderers pass their prepareObject; the entrance covers stay until it settles), ambient pedestrians, ambient aircraft and wildlife (when EarthWildlife's prepare returns a promise) stay hidden until their shaders are built, and dioramas are prepared before they join the scene (see Dioramas).

Main-thread work that runs as tiles stream in beneath a fast aircraft is kept small. Ambient aircraft parse and merge each type once into a template, in 3 ms slices, without the cabin (its animated instruments stayed hundreds of moving nodes on every copy). Storefront lettering shares its glyph vertices (MeshBufferBuilder.addFlatMesh). The worldgen tile cache keys a semantic tile by a fast hash of its JSON (the cache never leaves the session) rather than SHA-256, which spent up to 20 ms on a dense town tile. Ground cutouts read positions straight from their arrays and pass over triangles whose corners share a side outside every opening, or that one of a convex opening's edges separates from it, and find the openings near a triangle without building and sorting a set for it. Parked cars bake from their template arrays, and EarthAudioTerrain.sample skips map features whose bounds cannot come nearer than the nearest found. An aircraft's ground probes (a few hundred a tick) find airport pavement among meshes indexed by their bounds once per tagging, not by walking every pavement mesh ever tagged; a tunnel query skips bores whose tile it is outside before looking up their visibility.

For custom streamed geometry, call await renderer.prepareObject(object, signal, parent) before publication. Connect the same queue to terrain, which passes each layer's tile group as parent:

ts
const terrain = await createTerrainPackagePyramidStream(packageDescriptor, {
  admission: viewer.renderer.admission,
  prepareObject: (object, signal, parent) =>
    viewer.renderer.prepareObject(object, signal, parent),
  elevationWorker: new Worker(new URL('./elevation-worker.ts', import.meta.url), { type: 'module' }),
  onElevationTiming: sample => { /* decode, resample, mesh; milliseconds */ },
});

A transformHeightfield replacement (Earth's airport grading) is meshed by the same worker through the source's meshPrepared; meshed on the main thread, each graded tile beside an airport was one admitted job of up to 20 ms. The grading itself finds each sample row's polygon crossings and nearby ground edges once, instead of testing every edge of an airport's grounds for every sample: a tenth of a second a tile over Boeing Field.

Road earthworks (createTerrainRoadGrading's transformHeightfield) are graded in the worker too, where the source has gradeEarthworks. The host sends the tile's field and the road lines that reach it; the worker reads the reference ground from its own decoded tiles, grades, and meshes the result in the same trip, about 30 ms a town tile. On the main thread that was 2 ms slices between frames, outside the frame queue, and 4 to 9% of the thread in a low flight over a city. A reference tile is read as samples (load), without the full-resolution mesh loadPrepared builds for a tile to be drawn. Bridge profiles (gradeTile) are still worked out on the main thread, about 3% of it in that flight: a worker would need the tile's roads and its neighbors' copied across, most of which no bridge is near.

The worker entry calls installTerrainElevationWorker(self), exported from @bendyline/molen-terrain/client (use the worker-scope type cast shown by World Explorer when compiling with DOM rather than WebWorker types). The host reads archive bytes; the worker owns PNG decoding, its decoded tile cache, ancestor resampling, surface meshing, road earthworks and ground cuts. Worker buffers transfer without detaching archive caches or reusable topology. Omitting the worker retains the in-thread path. Worker errors are surfaced; they do not silently trigger duplicate work.

Procedural texture baking can use createMaterialBakeWorkerPool(workers) from @bendyline/molen-materials. Each worker entry calls installMaterialBakeWorker(self). Pass this caller-owned pool as ClientOptions.materialBaker or the second MaterialResolver constructor argument, and dispose the pool when finished. Pixel grids and material graphs return the synchronous baker's exact pixels through transferables. World Explorer uses two startup workers and releases them when its style pack is baked; materialWorker=0 retains synchronous baking for comparisons. Its material-bake timing reports worker CPU time.

withBakedMaterialStore(baker, store) serves bakes from a persistent BakedMaterialStore, such as createIndexedDbMaterialStore() from @bendyline/molen-client, so a later visit reads textures instead of rasterizing them. Keys combine the document's content with a fingerprint of the rasterizers (a tiny bake that exercises every node type), so a changed baker never serves stale pixels and its old entries are pruned. Store failures fall back to baking. createEarthWorldgen and mountEarthView accept the store as materialStore; World Explorer passes the IndexedDB store unless materialCache=0.

Terrain and content bytes persist the same way through a BlockCache from @bendyline/molen-pack/cache, passed to mountEarthView as byteCache (see the Earth view). It saves network and decompression time, not frame time: decoding and meshing still run for every tile the stream loads. Long-horizon byte prefetch reads bytes only. The Earth view also prepares nearby future tiles through the normal construction and GPU queues, so aircraft can arrive over already prepared terrain and layers even without persistent caching.

A generation worker runs one tile at a time; interleaved, every tile in flight finished late, the nearest with the rest. Which tile runs next is decided when a worker frees, not when the tile was requested: the worldgen pool keeps waiting tiles on the main thread (two posted per worker), and the land cover and road surface queues pick their next job the same way, by each layer context's priority() (meters from the camera, ground in view first). Posted in request order, a jet's nearest ground waited a second or more behind ground it had already passed. Layer adapters that pass work to their own workers can read context.priority the same way. It yields to its event loop every 8 ms of work, through a message channel, so a cancel message gets through. It used to yield after every step with a zero setTimeout, which a browser holds for at least 4 ms once timers nest: a dense tile took a second of wall time for a fifth of a second of work. Streaming generators also pass hashOutput: false: the SHA-256 over every output array (WorldgenBatchOutput.hash, for tooling and determinism checks) was a fifth of a dense tile's generation, and nothing reads it there; compare outputs with hashWorldgenOutput.

World-generation workers also prepare building spatial cells and full/structural LOD indices. The renderer requests renderCellsOnly when using cell LODs so it does not retain a redundant canonical building mesh. Per-cell Three object assembly is a separate queue job. Generation and cell-preparation timings are reported separately. Compatible opaque groups are merged by the resolved Three material, including groups with different authored references that resolve to the same material. Transparent group order is preserved.

World props (trees, ground cover, rocks, rooftop and street props) keep one batch per model per coarse terrain tile, and four per finest tile, so near detail stays around the camera's own quarter. On WebGPU, three.js keys an InstancedMesh's node state by the mesh (about 11 ms of main thread for a plant batch, per draw target and material) and declared its matrices as a uniform array sized to the batch and named after its node, so every batch also compiled a GPU pipeline of its own; when a frame created one, it stalled the browser's GPU process, for seconds in fast flight. The WebGPU driver reads instance matrices from one named, runtime-sized storage buffer instead, so a material's batches share one shader and one pipeline. createInstancedPlacementLod accepts any cellSize.

Lights are compiled into every lit shader: a light that joins or leaves the scene rebuilds every object in view at once. Keep a streamed world's light set fixed. Earth hosts mount dioramas with localLights: false, which keeps a diorama's own point and spot lights out of the world scene; a football field's scoreboard glow, loading and unloading as an aircraft passed, froze its takeoff.

Terrain palettes compile once per mesh. Terrain index topology is immutable and shared in a bounded CPU cache; use a copy before editing or transferring it. Grids and building cells use 16-bit indices when eligible. Terrain index arrays can be shared in CPU memory; separate Three attributes can still allocate separate GPU index buffers. Building LODs share their attribute objects and full-detail index where material grouping permits. Three r184 currently promotes unnormalized 16-bit attributes (including indices) to 32-bit storage on its WebGPU path, so the compact-index GPU saving applies to WebGL; worker/cache buffers remain compact on both paths.

Terrain selection and transitions ​

Terrain selection refines the highest projected-error candidate within the leaf budget, instead of retrying complete traversals with progressively relaxed thresholds. A 15% coarsening hysteresis band retains detail near boundaries. Pass previousTiles when using the standalone selector; the stream supplies its previous selection automatically. Pitched views use a conservative field of view to retain ground beneath the camera.

Terrain requests establish coarse coverage first, then prioritize nearby visible ground before distant refinement and the 12-degree turn margin. Ancestors precede equally distant descendants. Distance is measured to tile bounds rather than tile centers, so large tiles do not push nearby ground behind more distant requests. Semantic layers use the same view priority and prepare resident selected leaves before the terrain handoff, even while a slow sibling still holds the parent surface on screen. A replacement family shares its displayed parent's view and distance priority: finishing its siblings releases prepared nearby detail instead of leaving it hidden behind the old parent. Within that priority, the replacement family finishes before finer leaves that it would keep hidden. The existing layer concurrency and residency limits also bound this preparation. Layers that release the existing parent take priority over newly eligible layers, so slow building work cannot occupy all slots ahead of a sibling's ground cover. A layer under way for ground the camera has since left (neither wanted, ahead, displayed nor part of a handoff) finishes into the warm cache without holding a slot, up to twice the layer budget of them: worker queues take the nearest ground first, so after a turn those jobs ran last while new ground waited for the slots they held. Multi-level refinements advance the whole replacement family together; one already prepared fine leaf does not skip that intermediate handoff while its siblings still need it. The previous terrain surface and its layers remain visible until the layers they already display have finished construction and GPU preparation on their replacements. Surfaces and inherited detail then switch together; new terrain cannot occlude the previous detail while its own detail is still loading. This applies to refinement and coarsening, including intermediate fallback tiles. Newly eligible detail, such as buildings absent from a coarse parent, arrives when prepared without holding other tiles' completed detail behind that parent. Cached LODs reuse their prepared geometry.

Previously unvisited ground can show its base surface immediately; its enabled layers appear together once settled. Empty layer results count as ready. Failed replacement layers preserve the old tiles until a later attempt (after failedRetryDelayMs, or retryFailed()) succeeds or the layer is disabled; on cold ground, successful layers can still appear after another layer fails. Hidden layers do not delay a handoff. This stages scene geometry rather than rendering a second full-screen image, and retains old visual coverage under residency pressure until its replacement can safely take over.

stream.update(view, futureViews) additionally prepares the nearest refinement family at each future position at the same selection quality, including semantic layers and GPU resources. Future views are ordered by time; speculative preparation is capped at the larger of 16 tiles or a quarter of maxSelectedTiles, and by spare residency. The 16-tile allowance keeps all four approaching families possible even at the lowest render tier. Earth predicts 2, 4, 8 and 12 seconds ahead, following a smoothed ground-track turn rate through banks. Extrapolated turns stop at 90 degrees and travel at 4 km; teleports and entry animations reset the predictor. With at least three concurrent slots, up to half of each queue's existing capacity keeps future preparation progressing while visible work remains queued. Upcoming tiles already in the normal selection also receive this forward capacity; they need not be new speculative requests. The remaining slots prioritize current coverage, and unused capacity can prepare more of the route. Obsolete surface requests are cancelled on route changes. Redundant hidden ancestors become reclaimable cache once finer terrain is resident; intermediates still needed for the current replacement stay protected. Speculative tiles yield to displayed coverage under memory pressure; oversized speculative tiles back off instead of rebuilding on every update. preloading and preloaded in stream stats distinguish requested and ready leaves.

Independently of those views, the stream builds ahead along the track of the positions passed to update, from spare capacity only (lookAhead, see terrain). For a moving camera, layer work is ordered for where the camera will be when it finishes, and bare ground comes before more detail for ground that has some. At speed, levels whose tiles the camera crosses in under lookAhead.minTileSeconds refine only near the camera (lookAhead.fastDetail), for the current selection and the predicted views alike. Layer work for a tile the camera has left finishes into the warm cache rather than being cancelled: a cancelled request leaves its worker job running with nothing to show for it.

Earth's automatic render tiers retain at least four height and eight layer jobs, including at Minimum: serializing landcover, water and buildings behind one job could never keep up with a jet. Eight layer slots let a four-tile approach family prepare while current coverage advances. Main-thread publication still uses the shared frame admission budget. Both Earth hosts use earthTerrainCacheBudget to retain the device-sized terrain cache across quality changes. AdaptiveQualityController can recover during continuous streaming when sustained frame cadence and measured CPU and GPU work show headroom; loading without those measurements still blocks upgrades. A moving world need not become completely idle before recovering from a costly startup.

Publications share one visibility pass: the tiles and layers admitted in a frame request it, and it runs once after the admission flush, together with eviction. Reads that depend on what is displayed (displayedTiles, sampleHeight, isAreaReady, stats, pressure) run a pending pass first. A fast flight publishes dozens of tiles and layers per frame, and each had run the whole handoff, layer, cutout and byte pass. The warm cache keeps most resident tiles hidden; a hidden tile leaves the scene graph (three walks hidden objects in every world-matrix update and traversal) but keeps its parent, so world matrices still resolve while its layers prepare, and a rebase above it is applied when it shows again. stats() walks every displayed tile's objects for exact byte totals and adds hidden tiles' tracked buffers; a live panel passes { geometry: 'tracked' } for the retained estimate and visible-only counts. Ground cutouts stay on hidden tiles while their openings remain, keep the source grid's indices for triangles away from every opening, and re-count only the tiles whose ground they changed. A cut is its source grid's vertices as they are, then the few made on clipped edges, and the source stays for the next cut; once a cut is applied the source's attributes read from the cut's arrays, so the pair holds its vertices once in main memory. Over Seattle, where most ground meets water somewhere, the second copy was 174 of 1,139 MiB on show at High (the page's array buffers fell from 1,403 to 1,233 MiB without it). The source's GPU buffers stay until its tile goes.

Height queries prefer displayed terrain and fall back to resident heights outside the visible cut. An aircraft's center can pass behind its cockpit camera at a tile boundary; it must not wait indefinitely for already cached ground to become visible before moving again.

morphMilliseconds enables refinement height morphs for bare surfaces; call stream.updateTransitions(nowMs) in the frame loop (it also carries on unfinished ground cuts). Vertices start on the actual parent triangles and finish at their exact target positions with fixed horizontal coordinates. Grounded semantic layers use coverage-preserving atomic replacement and hysteresis instead. Enabling one finishes any surface morph before layer publication. Coarsening does not height-morph. World Explorer uses 180 ms for bare terrain; deterministic freeze captures disable morphing.

Collision neighborhoods ​

WalkCollision from @bendyline/molen-client/navigation gives walkers, driven cars and piloted aircraft a triangle tree of the visible geometry around them. Two costs matter. The scan visits every visible mesh under the root to notice streamed changes; it runs on update only when the subject has left the neighborhood, when rescanIntervalMs has passed (the Earth hosts use 200 ms) or after invalidate(). The rebuild transforms the nearby triangles into the tree; geometries of 4096 triangles or more are walked through a per-geometry XZ index, built on first use and kept with the geometry, so a terrain tile or building cell contributes only the triangles that can reach the neighborhood instead of every triangle it holds.

A scan brings world matrices up to date only for what it visits (the root's chain, then each object as the scan reaches it), and skips any group that declares an X/Z rectangle of its own frame as userData.walkFootprint when the rectangle is out of reach: terrain tiles declare theirs, so a jet that scans many times a second visits the few tiles beneath it rather than everything on screen. Aircraft cabins (the spec's interior nodes) are walkIgnore: nobody walks into a cockpit, and their parts made a walker's tree beside a parked aircraft take a third of a second to build.

A subject that moves tens of meters a second would otherwise recenter the tree every few frames. Vehicles and aircraft use a wider radius with a larger rebuildDistance, and a verticalRadius with update(root, x, z, y) so the ground far below an airframe never enters the tree; while it flies high the tree is empty and rebuilds are free. World Explorer's aircraft use 48 m / 24 m / 40 m, its cars 32 m / 12 m / 24 m; walkers keep the 24 m / 6 m default and the whole column, which their placement ray needs. The kernel's own ground contact (groundHeight) does not depend on this tree. Low over a forest an aircraft's neighborhood still held 100k triangles of crowns and shrubs; with instanceBounds: true each instance of an instanced mesh enters the tree as its bounding box, twelve triangles, which is all an airframe's probes and its chase camera need. Ground cover (plant models drawn only at near detail) is never solid, and the tree splits at each level by selecting a median rather than sorting, so a rebuild of that size takes milliseconds rather than most of a second.

Measurement ​

World Explorer enables elevation workers, shared admission and shader warmup by default. For controlled comparisons, query flags elevationWorker=0, materialWorker=0, admission=0 and warmup=0 disable those individual paths (worker=0 disables all generation workers). The performance HUD's data-graphics JSON contains bounded distributions of decode/resample/mesh, world-generation/preparation, assembly/upload/publication and frame CPU timing, plus admission overrun counts. Queue delay is reported separately from work. Frame CPU does not include all GPU execution; use the backend GPU timer and browser frame intervals as separate metrics.

On a laptop with two GPUs, check which one the browser renders with (the WebGL renderer string, WEBGL_debug_renderer_info). Chrome on Windows may use the integrated GPU whatever a page asks for; on one AMD Radeon 880M it froze presentation for about 200 ms every ten seconds, on an empty page too, while the same machine's discrete GPU drew without a pause. Chrome's #force-high-performance-gpu flag, or the browser's entry in Windows' graphics settings, selects the discrete GPU.

Measure time to coverage, cold/loading and moving p95/p99, steady frame cost, draws, triangles, retained bytes and image parity. Staging trades some time to full detail for smaller individual publication stalls; compiled shaders and GPU buffers must be tested on a cold traversal too.

50 guides · 44 schema formats · 51 API entry points · 11 samples. API, CLI and schema pages are generated from the shipped build.