Appearance
@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>;Parameters
input
RequestInfo | URL
init?
RequestInit
Returns
Promise<Response>
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
entries
ts
readonly entries: readonly StructurePlacement[];Inherited from
rules
ts
readonly rules: readonly StructureMapRule[];Inherited from
Methods
dispose()
ts
dispose(): void;Abort reads owned by this stream and release its parsed catalog cache.
Returns
void
Overrides
isLoaded()
ts
isLoaded(bounds): boolean;False means coverage is not loaded; an empty synchronous query is then incomplete.
Parameters
bounds
Bounds
Returns
boolean
Overrides
query()
ts
query(bounds, options?): StructurePlacement[];Geographic rectangle [west, south, east, north].
Parameters
bounds
readonly [number, number, number, number]
options?
boolean | StructureQueryOptions
Returns
Inherited from
queryAsync()
ts
queryAsync(bounds, options?): Promise<StructurePlacement[]>;Present for regional catalogs. Returned records do not depend on cache residency.
Parameters
bounds
Bounds
options?
Returns
Promise<StructurePlacement[]>
Overrides
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
signal
AbortSignal
Returns
Promise<WorldgenTileOutput | undefined>
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
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
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<Object3DEventMap>
Returns
Promise<void>
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
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
Returns
void
stats()
ts
stats(): WorldgenRenderStats;Returns
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
Returns
void
setLimits()
ts
setLimits(options): void;Trim immediately when the device working-set budget changes.
Parameters
options
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<{ entry: StructurePlacement; signal: AbortSignal; }>
Returns
number | undefined | Promise<number | undefined>
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?
Returns
createStructureStream()
ts
function createStructureStream(
input,
read,
base?,
options?
): StructureStream;Async, bounded regional loading; synchronous queries report resident records only.
Parameters
input
read
(path, signal) => Promise<unknown>
base?
options?
Returns
createWorldgenSemanticRenderers()
ts
function createWorldgenSemanticRenderers(pack, options?): WorldgenSemanticRenderers;Renderers for the classification and human-feature layers of a terrain package.
Parameters
pack
ResolvedStylePack
options?
Returns
createWorldgenTileCache()
ts
function createWorldgenTileCache(options?): WorldgenTileCache;Parameters
options?
Returns
createWorldgenWorkerBridge()
ts
function createWorldgenWorkerBridge(worker, options): WorldgenGenerator;Parameters
worker
options
Returns
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
Returns
loadRegionAtlas()
ts
function loadRegionAtlas(url, options?): Promise<RegionAtlasDoc>;Parameters
url
string | URL
options?
Returns
Promise<RegionAtlasDoc>
outputBytes()
ts
function outputBytes(output): number;Parameters
output
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
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<T> | undefined
options?
Returns
TerrainSemanticTileRenderer
withWorldgenTileCache()
ts
function withWorldgenTileCache(
generator,
cache,
keyOf
): WorldgenGenerator;Serve repeat tiles from the cache; generate (and remember) the rest.
Parameters
generator
cache
keyOf
(request) => string
Returns
worldgenTileCacheKey()
ts
function worldgenTileCacheKey(parts): string;Parameters
parts
Returns
string
References
createRegionResolver
Re-exports createRegionResolver
RegionResolver
Re-exports RegionResolver
RegionResolverOptions
Re-exports RegionResolverOptions