Skip to content

@bendyline/molen-worldgen-earth/client ​

Earth binding for Molen worldgen: terrain-semantics adapter, OSM label mapping, and lon/lat region atlas (kernel) with terrain tile renderers (client).

ts
import { /* … */ } from '@bendyline/molen-worldgen-earth/client';

Interfaces ​

InThreadGeneratorOptions ​

Properties ​

atlas? ​
ts
optional atlas?: RegionAtlasDoc;
environment? ​
ts
optional environment?: RegionalEnvironment;
places? ​
ts
optional places?: PlacesContent;

Landmarks and business identities for mapped places (none when omitted).

regions? ​
ts
optional regions?: RegionResolver;
yieldEveryBuildings? ​
ts
optional yieldEveryBuildings?: number;

Buildings generated between cooperative yields (default 48).


LoadRegionAtlasOptions ​

Properties ​

fetch? ​
ts
optional fetch?: (input, init?) => Promise<Response>;

MDN Reference

Parameters ​
input ​

RequestInfo | URL

init? ​

RequestInit

Returns ​

Promise&lt;Response&gt;

signal? ​
ts
optional signal?: AbortSignal;

MapOverrideRendererOptions ​

Properties ​

metersPerUnit? ​
ts
optional metersPerUnit?: number;

cos(center latitude) factor of the terrain package (default: the tile pyramid's, else 1).


StructureStream ​

Extends ​

Properties ​

cells ​
ts
readonly cells: ReadonlyMap<string, readonly StructurePlacement[]>;
Inherited from ​

StructureIndex.cells

entries ​
ts
readonly entries: readonly StructurePlacement[];
Inherited from ​

StructureIndex.entries

rules ​
ts
readonly rules: readonly StructureMapRule[];
Inherited from ​

StructureIndex.rules

Methods ​

dispose() ​
ts
dispose(): void;

Abort reads owned by this stream and release its parsed catalog cache.

Returns ​

void

Overrides ​

StructureIndex.dispose

isLoaded() ​
ts
isLoaded(bounds): boolean;

False means coverage is not loaded; an empty synchronous query is then incomplete.

Parameters ​
bounds ​

Bounds

Returns ​

boolean

Overrides ​

StructureIndex.isLoaded

query() ​
ts
query(bounds, options?): StructurePlacement[];

Geographic rectangle [west, south, east, north].

Parameters ​
bounds ​

readonly [number, number, number, number]

options? ​

boolean | StructureQueryOptions

Returns ​

StructurePlacement[]

Inherited from ​

StructureIndex.query

queryAsync() ​
ts
queryAsync(bounds, options?): Promise<StructurePlacement[]>;

Present for regional catalogs. Returned records do not depend on cache residency.

Parameters ​
bounds ​

Bounds

options? ​

StructureLoadOptions

Returns ​

Promise&lt;StructurePlacement[]&gt;

Overrides ​

StructureIndex.queryAsync

stats() ​
ts
stats(): object;
Returns ​

object

cachedBytes ​
ts
cachedBytes: number;
cachedShards ​
ts
cachedShards: number;
pending ​
ts
pending: number;

StructureStreamOptions ​

Properties ​

concurrency? ​
ts
optional concurrency?: number;
maxCacheBytes? ​
ts
optional maxCacheBytes?: number;

Retained serialized bytes; parsed JS object overhead is additional. Default 4 MiB.

maxShards? ​
ts
optional maxShards?: number;

WorkerLike ​

Methods ​

addEventListener() ​
ts
addEventListener(type, listener): void;
Parameters ​
type ​

"message"

listener ​

(event) => void

Returns ​

void

postMessage() ​
ts
postMessage(message, transfer?): void;
Parameters ​
message ​

unknown

transfer? ​

Transferable[]

Returns ​

void

removeEventListener()? ​
ts
optional removeEventListener(type, listener): void;
Parameters ​
type ​

"message"

listener ​

(event) => void

Returns ​

void

terminate()? ​
ts
optional terminate(): void;
Returns ​

void


WorldgenBuildingHit ​

A mapped building or placed landmark near a point: see WorldgenSemanticRenderers.buildingsNear.

Properties ​

anchor? ​
ts
optional anchor?: [number, number];

For a landmark: where it is anchored, [longitude, latitude].

bounds ​
ts
bounds: [number, number, number, number];

World X/Z [minX, minZ, maxX, maxZ].

class? ​
ts
optional class?: string;

What the map says it is: a building's finer class when it has one.

distance ​
ts
distance: number;

World units from the point to its outline; 0 inside.

height? ​
ts
optional height?: number;

World units.

id ​
ts
id: string;

The map feature's id, or the landmark placement's.

kind ​
ts
kind: "building" | "landmark";
levels? ​
ts
optional levels?: number;
name? ​
ts
optional name?: string;
outlines ​
ts
outlines: [number, number][][];

World X/Z outer rings, one per mapped piece; a landmark's is its extent as a rectangle.

override? ​
ts
optional override?: string;

For a building a host placed: the id of the map override it came with.


WorldgenGenerateRequest ​

Properties ​

budgets? ​
ts
optional budgets?: Partial<WorldgenBudgets>;
buildingInfill? ​
ts
optional buildingInfill?: boolean | BuildingInfillOptions;
buildingInfillExclusions? ​
ts
optional buildingInfillExclusions?: TerrainSemanticPolygon[];
features? ​
ts
optional features?: object;
buildings? ​
ts
optional buildings?: boolean;
interiors? ​
ts
optional interiors?: boolean;
scatter? ​
ts
optional scatter?: boolean;
focus? ​
ts
optional focus?: readonly [number, number];

A viewer on the ground, in world X/Z: the buildings nearest it are detailed first.

geom ​
ts
geom: TileGeometry;
ground ​
ts
ground: HeightSampler;

World-space ground of the tile (a terrain heightfield).

keep? ​
ts
optional keep?: number;

Extra keep multiplier on the plant scatter (default 1).

priority? ​
ts
optional priority?: () => number;

How soon the view needs the tile, lower first, read when a worker frees (the terrain layer context's priority). A pool starts the most urgent waiting tile next.

Returns ​

number

renderCellsOnly? ​
ts
optional renderCellsOnly?: boolean;

Renderer requests compact cells instead of retaining a second canonical vertex copy.

resolution ​
ts
resolution: number;

Samples per tile edge for the transferable height grid (the terrain tile resolution).

tierOffset? ​
ts
optional tierOffset?: number;
tile ​
ts
tile: TerrainSemanticTile;

WorldgenGenerator ​

Produces tile output somewhere: in a worker, in-thread, or from a cache in front of either.

Methods ​

dispose() ​
ts
dispose(): void;
Returns ​

void

generate() ​
ts
generate(request, signal): Promise<WorldgenTileOutput | undefined>;
Parameters ​
request ​

WorldgenGenerateRequest

signal ​

AbortSignal

Returns ​

Promise&lt;WorldgenTileOutput | undefined&gt;

prepare()? ​
ts
optional prepare(request): void;

Main-thread work generate would otherwise do first (the tile's ground grid), for a host that meters main-thread work to run as its own step. Optional; generate works without it.

Parameters ​
request ​

WorldgenGenerateRequest

Returns ​

void


WorldgenRendererOptions ​

Properties ​

atlas? ​
ts
optional atlas?: RegionAtlasDoc;
budgets? ​
ts
optional budgets?: Partial<WorldgenBudgets>;
buildingInfill? ​
ts
optional buildingInfill?: boolean | BuildingInfillOptions;

Opt-in synthetic homes; seed/density are forwarded to either generation path and cache.

cache? ​
ts
optional cache?: WorldgenTileCache;

CPU-side cache of generated tiles keyed by pack, atlas, quality, and address.

compact? ​
ts
optional compact?: boolean;

A compact scene for renderers without the WebGPU path's draw optimizations, such as WebGL: High's building geometry at its compact budget (under half) and half the plant scatter.

distantBuildings? ​
ts
optional distantBuildings?: boolean;

Bounded coarse building silhouettes below the detailed generation range. Opt-in.

environment? ​
ts
optional environment?: RegionalEnvironment;

Must match a supplied worker's environment; content participates in tile cache keys.

generator? ​
ts
optional generator?: WorldgenGenerator;

Where tiles are generated (default: on this thread); e.g. createWorldgenWorkerBridge.

interiors? ​
ts
optional interiors?: boolean | Omit<InteriorStreamingOptions, "catalog">;

Real openings and bounded lazy interiors, including residential upstairs (opt in). They are laid out by the style pack's interior catalog; a pack without one generates no interiors.

landcover? ​
ts
optional landcover?: TerrainSemanticMeshOptions;

Options forwarded to the default land surface (colors default to the scatter surface colors).

landcoverGenerator? ​
ts
optional landcoverGenerator?: TerrainLandcoverGenerator;

Optional worker-backed land-cover surface draping. Caller owns its lifetime.

lodPolicy? ​
ts
optional lodPolicy?: ScreenSpaceLodPolicy;

Shared screen-space policy for resident building and vegetation LODs.

materialDecorator? ​
ts
optional materialDecorator?: BuildingMaterialDecorator;

Detail for the building materials this layer creates itself (its default and distant-level sets), e.g. createBuildingWeatheringAsync; pass the same one to a supplied materials set.

materials? ​
ts
optional materials?: WorldgenMaterialSet;
metersPerUnit? ​
ts
optional metersPerUnit?: number;

cos(center latitude) factor of the terrain package (1 for local packages).

models? ​
ts
optional models?: ModelLibrary;

Prepared prop models; without it the classification layer keeps the default tree cones.

onTileStats? ​
ts
optional onTileStats?: (output, generateMs) => void;
Parameters ​
output ​

WorldgenTileOutput

generateMs ​

number

Returns ​

void

places? ​
ts
optional places?: PlacesContent;

Landmarks and business identities for mapped places; without them businesses are not recognized and street furniture is not placed. With a worker generator, pass the worker the same content; tile cache keys include its hashes.

prepareObject? ​
ts
optional prepareObject?: (object, signal, parent?) => Promise<void>;

Prepare replacement architecture before a resident quality change becomes visible. parent is the layer object the replacement will join.

Parameters ​
object ​

Object3D

signal ​

AbortSignal

parent? ​

Object3D&lt;Object3DEventMap&gt;

Returns ​

Promise&lt;void&gt;

propLod? ​
ts
optional propLod?: boolean;

Camera-distance vegetation LOD and spatial culling (default true).

quality? ​
ts
optional quality?: WorldgenQualityPreset;
regions? ​
ts
optional regions?: RegionResolver;
roads? ​
ts
optional roads?: TerrainSemanticMeshOptions;

Shared surface styles/controller for roads, parking areas, markings and fixtures.

sampleStructureTerrain? ​
ts
optional sampleStructureTerrain?: StructureTerrainSampler;

Fine or cross-tile ground samples; undefined coverage leaves the procedural fallback.

signMaterial? ​
ts
optional signMaterial?: Material<MaterialEventMap>;

Material for storefront signs that show mapped names (places.signs), usually createSignMaterialAsync from @bendyline/molen-worldgen/client over the places' glyph atlas, for the renderer's backend. Caller-owned. Without it, places that set names generate signs nothing draws: pass places built with signNames: 'generic' instead.

structureModels? ​
ts
optional structureModels?: ModelLibrary;

Streamed geographic models; defaults to models when no separate library is supplied.

structureObjects? ​
ts
optional structureObjects?: StructureModelSource;

Full glTF hierarchy and PBR materials for authored structures; preferred over flattened props.

structures? ​
ts
optional structures?: StructureIndex;

Authored geographic structures, indexed by geohash for tile lookup.

viewerFocus? ​
ts
optional viewerFocus?: boolean;

With interiors: once the position passed to updateInteriors is down among the buildings and moving at a walk, regenerate the finest tiles round it with their buildings queued nearest first, so the ones a walker can reach are the detailed, enterable ones (default true). A tile is replaced some seconds after the viewer arrives: turn it off where a frame must not change under a still camera, as in a render test.

viewingDate? ​
ts
optional viewingDate?: string;

Explicit YYYY-MM-DD date for archival landmarks; omitted keeps them unloaded.

yieldEveryBuildings? ​
ts
optional yieldEveryBuildings?: number;

Buildings generated between cooperative yields (default 48, in-thread only).


WorldgenRenderStats ​

Properties ​

boxes ​
ts
boxes: number;
buildings ​
ts
buildings: number;
cache? ​
ts
optional cache?: object;
bytes ​
ts
bytes: number;
hits ​
ts
hits: number;
misses ​
ts
misses: number;
size ​
ts
size: number;
generateMs ​
ts
generateMs: object;
last ​
ts
last: number;
max ​
ts
max: number;
mean ​
ts
mean: number;
geometryBytes ​
ts
geometryBytes: number;
interiors? ​
ts
optional interiors?: InteriorStreamingStats;
props ​
ts
props: number;
skippedByOwnership ​
ts
skippedByOwnership: number;
tiles ​
ts
tiles: number;

WorldgenSemanticRenderers ​

Properties ​

classification ​
ts
classification: TerrainSemanticTileRenderer;
humanFeatures ​
ts
humanFeatures: TerrainSemanticTileRenderer;

Methods ​

buildingsNear() ​
ts
buildingsNear(
   x, 
   z, 
   radius?
): WorldgenBuildingHit[];

Mapped buildings and placed landmarks within radius world units of a point (default 30), nearest first, from the detailed tiles in memory. It reads the tiles' kept map data, which may be decoded afresh: for a key press or a slow poll, not every frame.

Parameters ​
x ​

number

z ​

number

radius? ​

number

Returns ​

WorldgenBuildingHit[]

dispose() ​
ts
dispose(): void;
Returns ​

void

doorAt() ​
ts
doorAt(position, query?): InteriorDoorState | undefined;

The nearest building door within reach of a viewer, in front of them with facing.

Parameters ​
position ​

readonly [number, number, number]

query? ​

InteriorDoorQuery

Returns ​

InteriorDoorState | undefined

elevatorAt() ​
ts
elevatorAt(position): InteriorElevatorStop | undefined;

The lift a viewer at this position is standing in.

Parameters ​
position ​

readonly [number, number, number]

Returns ​

InteriorElevatorStop | undefined

requestStorey() ​
ts
requestStorey(identity, level): boolean;

Ask a tower for a storey; true once it is built and a viewer can be moved there.

Parameters ​
identity ​

string

level ​

number

Returns ​

boolean

setCacheBudget() ​
ts
setCacheBudget(maxBytes): void;
Parameters ​
maxBytes ​

number

Returns ​

void

setDoor() ​
ts
setDoor(
   id, 
   open, 
   from?
): boolean;

Open or shut a building door, away from a viewer at from. False when there is no such door, it is locked, or shutting it would close it on someone standing in the doorway.

Parameters ​
id ​

string

open ​

boolean

from? ​

readonly [number, number, number]

Returns ​

boolean

setQuality() ​
ts
setQuality(quality): void;

Rebuild resident architecture cooperatively, keeping the previous geometry until ready.

Parameters ​
quality ​

WorldgenQualityPreset

Returns ​

void

stats() ​
ts
stats(): WorldgenRenderStats;
Returns ​

WorldgenRenderStats

supersede() ​
ts
supersede(bounds): void;

Say that the tiles overlapping a world X/Z rectangle [minX, minZ, maxX, maxZ] are about to be built again from changed map data (see withMapOverrides), before asking the stream to. Their replacements are then generated without the landmark footprints the outgoing tiles still hold, which would take a host's building for a landmark's own and drop it until the old tile was gone.

Parameters ​
bounds ​

readonly [number, number, number, number]

Returns ​

void

updateInteriors() ​
ts
updateInteriors(position): void;

Call before walking collision with the camera in metric world coordinates.

Parameters ​
position ​

readonly [number, number, number]

Returns ​

void


WorldgenTileCache ​

Properties ​

bytes ​
ts
readonly bytes: number;
evictions ​
ts
readonly evictions: number;
hits ​
ts
readonly hits: number;
misses ​
ts
readonly misses: number;
size ​
ts
readonly size: number;

Methods ​

clear() ​
ts
clear(): void;
Returns ​

void

delete() ​
ts
delete(key): boolean;
Parameters ​
key ​

string

Returns ​

boolean

get() ​
ts
get(key): WorldgenTileOutput | undefined;
Parameters ​
key ​

string

Returns ​

WorldgenTileOutput | undefined

set() ​
ts
set(key, output): void;
Parameters ​
key ​

string

output ​

WorldgenTileOutput

Returns ​

void

setLimits() ​
ts
setLimits(options): void;

Trim immediately when the device working-set budget changes.

Parameters ​
options ​

WorldgenTileCacheOptions

Returns ​

void


WorldgenTileCacheKeyParts ​

Properties ​

atlasHash? ​
ts
optional atlasHash?: string;
features ​
ts
features: object;
buildings ​
ts
buildings: boolean;
scatter ​
ts
scatter: boolean;
level ​
ts
level: number;
packHash ​
ts
packHash: string;
quality ​
ts
quality: string;
variant? ​
ts
optional variant?: string;

Effective generation settings, when they differ within one named quality preset.

x ​
ts
x: number;
z ​
ts
z: number;

WorldgenTileCacheOptions ​

Properties ​

maxBytes? ​
ts
optional maxBytes?: number;

Bytes of mesh and instance data kept (default 256 MiB).

maxEntries? ​
ts
optional maxEntries?: number;

Entries kept (default 256).


WorldgenWorkerBridgeOptions ​

Properties ​

atlas? ​
ts
optional atlas?: RegionAtlasDoc;
environment? ​
ts
optional environment?: RegionalEnvironmentDocs;
metersPerUnit ​
ts
metersPerUnit: number;
ownsWorker? ​
ts
optional ownsWorker?: boolean;

Terminate the worker on dispose (default true).

pack ​
ts
pack: ResolvedStylePack;
places? ​
ts
optional places?: PlacesContentDocs;

Places content documents to generate with (none when omitted). Give the renderer the same content as places so its tile cache keys match what the worker generates.

Type Aliases ​

StructureTerrainSampler ​

ts
type StructureTerrainSampler = (coordinate, request) => number | undefined | Promise<number | undefined>;

Heights use the same metres and vertical reference as the host's terrain geometry.

Parameters ​

coordinate ​

readonly [number, number]

request ​

Readonly&lt;{ entry: StructurePlacement; signal: AbortSignal; }&gt;

Returns ​

number | undefined | Promise&lt;number | undefined&gt;

Functions ​

createInThreadWorldgenGenerator() ​

ts
function createInThreadWorldgenGenerator(pack, options?): WorldgenGenerator;

Generate on the calling thread, yielding to the host between chunks and honouring aborts.

Parameters ​

pack ​

ResolvedStylePack

options? ​

InThreadGeneratorOptions

Returns ​

WorldgenGenerator


createStructureStream() ​

ts
function createStructureStream(
   input, 
   read, 
   base?, 
   options?
): StructureStream;

Async, bounded regional loading; synchronous queries report resident records only.

Parameters ​

input ​

StructureDirectory

read ​

(path, signal) => Promise&lt;unknown&gt;

base? ​

StructureIndex

options? ​

StructureStreamOptions

Returns ​

StructureStream


createWorldgenSemanticRenderers() ​

ts
function createWorldgenSemanticRenderers(pack, options?): WorldgenSemanticRenderers;

Renderers for the classification and human-feature layers of a terrain package.

Parameters ​

pack ​

ResolvedStylePack

options? ​

WorldgenRendererOptions

Returns ​

WorldgenSemanticRenderers


createWorldgenTileCache() ​

ts
function createWorldgenTileCache(options?): WorldgenTileCache;

Parameters ​

options? ​

WorldgenTileCacheOptions

Returns ​

WorldgenTileCache


createWorldgenWorkerBridge() ​

ts
function createWorldgenWorkerBridge(worker, options): WorldgenGenerator;

Parameters ​

worker ​

WorkerLike

options ​

WorldgenWorkerBridgeOptions

Returns ​

WorldgenGenerator


createWorldgenWorkerPool() ​

ts
function createWorldgenWorkerPool(workers, options): WorldgenGenerator;

Several identically configured workers behind one generator: each tile goes to the worker with the fewest tiles in flight. Generation is deterministic per tile, so which worker builds it does not change the output; a city's first view no longer waits on one worker's queue.

Tiles wait here, not in the workers, and a free worker takes the most urgent (see WorldgenGenerateRequest.priority; request order among equals). Posted at once, a jet's tiles queued in each worker in request order: by their turn it had flown on, and the nearest ground waited a second or more behind ground it had passed. Each worker keeps a second tile posted, so it starts that one as soon as it finishes the first.

Parameters ​

workers ​

readonly WorkerLike[]

options ​

WorldgenWorkerBridgeOptions

Returns ​

WorldgenGenerator


loadRegionAtlas() ​

ts
function loadRegionAtlas(url, options?): Promise<RegionAtlasDoc>;

Parameters ​

url ​

string | URL

options? ​

LoadRegionAtlasOptions

Returns ​

Promise&lt;RegionAtlasDoc&gt;


outputBytes() ​

ts
function outputBytes(output): number;

Parameters ​

output ​

WorldgenTileOutput

Returns ​

number


tileHeightGrid() ​

ts
function tileHeightGrid(
   ground, 
   geom, 
   resolution
): HeightGrid;

Sample a tile's ground into the grid both generation paths use. Each call returns its own heights, which the worker bridge transfers away; a recent tile's samples are reused.

Parameters ​

ground ​

HeightSampler

geom ​

TileGeometry

resolution ​

number

Returns ​

HeightGrid


withMapOverrides() ​

ts
function withMapOverrides<T>(
   renderer, 
   set, 
   options?
): TerrainSemanticTileRenderer;

Wrap a semantic tile renderer so each tile is built as set's overrides leave it. Put it outside whatever observes tiles (traffic, sound, wildlife), so they read the edited tile, and inside a wrapper that adds its own features over the map, such as airports. The set is read when a tile is built: after it changes, the tiles its change names must be built again (the terrain stream's refreshLayers). Without a set the renderer is returned as it is.

Type Parameters ​

T ​

T extends MapOverride

Parameters ​

renderer ​

TerrainSemanticTileRenderer

set ​

MapOverrideSet&lt;T&gt; | undefined

options? ​

MapOverrideRendererOptions

Returns ​

TerrainSemanticTileRenderer


withWorldgenTileCache() ​

ts
function withWorldgenTileCache(
   generator, 
   cache, 
   keyOf
): WorldgenGenerator;

Serve repeat tiles from the cache; generate (and remember) the rest.

Parameters ​

generator ​

WorldgenGenerator

cache ​

WorldgenTileCache

keyOf ​

(request) => string

Returns ​

WorldgenGenerator


worldgenTileCacheKey() ​

ts
function worldgenTileCacheKey(parts): string;

Parameters ​

parts ​

WorldgenTileCacheKeyParts

Returns ​

string

References ​

createRegionResolver ​

Re-exports createRegionResolver


RegionResolver ​

Re-exports RegionResolver


RegionResolverOptions ​

Re-exports RegionResolverOptions

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