Skip to content

@bendyline/molen-worldgen/client ​

Molen worldgen capability: data-driven buildings from outlines and prop placement in labeled polygons (kernel) with three.js uploads (client).

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

Classes ​

InteriorStreamer ​

Metric coordinates throughout: floating-origin changes do not reshuffle seeds or residency. Only descriptors and opaque portal covers exist at a distance. Layout/mesh work starts near the camera, yields across frames, and publishes atomically before removing solid covers.

Constructors ​

Constructor ​
ts
new InteriorStreamer(options): InteriorStreamer;
Parameters ​
options ​

InteriorStreamingOptions

Returns ​

InteriorStreamer

Methods ​

among() ​
ts
among(position, margin?): boolean;

Whether position is down among registered buildings: over a region that has sites, and no more than margin above or below the storeys they span. A camera cruising well above the roofs is not; a walker, or anything hovering at street level, is.

Parameters ​
position ​

readonly [number, number, number]

margin? ​

number

Returns ​

boolean

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

void

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

The nearest door within reach of a viewer at position (eyes or feet, metric), in a shown region, and in front of them when facing is given.

Parameters ​
position ​

readonly [number, number, number]

query? ​

InteriorDoorQuery

Returns ​

InteriorDoorState | undefined

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

readonly [number, number, number]

Returns ​

InteriorElevatorStop | undefined

occupied() ​
ts
occupied(position): boolean;

Whether position is inside a published interior: within its walls, between its floors.

Parameters ​
position ​

readonly [number, number, number]

Returns ​

boolean

register() ​
ts
register(
   root, 
   sites, 
   origin?
): void;
Parameters ​
root ​

Object3D

sites ​

readonly InteriorSite[]

origin? ​

Vec2

Returns ​

void

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

Ask a resident tower for a storey. True once it is built and a viewer can be moved there; until then keep asking, because moving first would drop them through a floor that is not yet.

Parameters ​
identity ​

string

level ​

number

Returns ​

boolean

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

Open or shut a door. It opens away from from (where the viewer stands; into the building when omitted), and only onto rooms that are built: asked earlier, it waits for them. False when no shown door has this id, when it is locked, or when shutting it would close it on someone standing in the doorway at from.

Parameters ​
id ​

string

open ​

boolean

from? ​

readonly [number, number, number]

Returns ​

boolean

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

InteriorStreamingStats

unregister() ​
ts
unregister(root): void;
Parameters ​
root ​

Object3D

Returns ​

void

update() ​
ts
update(position): void;
Parameters ​
position ​

readonly [number, number, number]

Returns ​

void


ModelLibrary ​

Caches prepared models by reference; loads glTF scenes through the host's asset loader.

Constructors ​

Constructor ​
ts
new ModelLibrary(
   loadModel?, 
   landmarks?, 
   disposeLoadedScene?, 
   plants?, 
   fonts?, 
   material?
): ModelLibrary;
Parameters ​
loadModel? ​

ModelLoader

landmarks? ​

Readonly<Record<string, LandmarkDoc>>

disposeLoadedScene? ​

boolean

plants? ​

Readonly<Record<string, PlantPreset>>

fonts? ​

FontLibrary

material? ​

Material<MaterialEventMap>

Returns ​

ModelLibrary

Methods ​

acquire() ​
ts
acquire(ref, coarse?): Promise<PreparedModel>;

Hold a prepared model while a consumer uses its geometry.

Parameters ​
ref ​

string

coarse? ​

ModelDetail

Returns ​

Promise&lt;PreparedModel&gt;

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

void

get() ​
ts
get(ref, coarse?): PreparedModel | undefined;

The prepared model, if prepare has completed for the requested detail.

Parameters ​
ref ​

string

coarse? ​

ModelDetail

Returns ​

PreparedModel | undefined

prepare() ​
ts
prepare(ref, coarse?): Promise<PreparedModel>;
Parameters ​
ref ​

string

coarse? ​

ModelDetail

Returns ​

Promise&lt;PreparedModel&gt;

release() ​
ts
release(ref, coarse?): void;

Release prepared geometry when the last consumer drops its reference.

Parameters ​
ref ​

string

coarse? ​

ModelDetail

Returns ​

void


NightWindowLighting ​

One shared emission material per view. The generated overlay owns compact geometry, borrows this material, follows the parent mesh's transforms/LOD and is absent from daytime draws.

Constructors ​

Constructor ​
ts
new NightWindowLighting(): NightWindowLighting;
Returns ​

NightWindowLighting

Properties ​

material ​
ts
readonly material: MeshBasicMaterial;

Methods ​

attachModel() ​
ts
attachModel(scene): void;

Attach before replacing glTF shared surfaces, so source material extras are still present.

Parameters ​
scene ​

Object3D

Returns ​

void

createGeometry() ​
ts
createGeometry(source, ranges): 
  | BufferGeometry<NormalBufferAttributes, BufferGeometryEventMap>
  | undefined;

Indices are source ranges, before material batching reorders them.

Parameters ​
source ​

BufferGeometry

ranges ​

readonly NightWindowRange[]

Returns ​

| BufferGeometry&lt;NormalBufferAttributes, BufferGeometryEventMap&gt; | undefined

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

void

mesh() ​
ts
mesh(geometry): Mesh;
Parameters ​
geometry ​

BufferGeometry

Returns ​

Mesh

setNightFactor() ​
ts
setNightFactor(factor): void;
Parameters ​
factor ​

number

Returns ​

void


ScreenSpaceLod ​

Screen-space error with conservative bounds and 15% hysteresis. No GPU readbacks.

Extends ​

  • LOD

Constructors ​

Constructor ​
ts
new ScreenSpaceLod(policy, radius): ScreenSpaceLod;
Parameters ​
policy ​

ScreenSpaceLodPolicy

radius ​

number

Returns ​

ScreenSpaceLod

Overrides ​
ts
THREE.LOD.constructor

Properties ​

policy ​
ts
readonly policy: ScreenSpaceLodPolicy;
radius ​
ts
readonly radius: number;

Methods ​

addDetail() ​
ts
addDetail(object, errorMeters): this;
Parameters ​
object ​

Object3D

errorMeters ​

number

Returns ​

this

getCurrentLevel() ​
ts
getCurrentLevel(): number;

Get the currently active LOD level

Returns ​

number

Remarks ​

As index of the levels array.

Overrides ​
ts
THREE.LOD.getCurrentLevel
update() ​
ts
update(camera): void;

Set the visibility of each levels | level's THREE.Object3D | object based on distance from the THREE.Camera | camera.

Parameters ​
camera ​

Camera

Returns ​

void

Overrides ​
ts
THREE.LOD.update

StructureLodStreamer ​

Source-derived landmarks: skyline first, bounded residency, stable instances during upgrades.

Implements ​

Constructors ​

Constructor ​
ts
new StructureLodStreamer(
   manifest, 
   load, 
   options?
): StructureLodStreamer;
Parameters ​
manifest ​

(ref) => Promise&lt;StructureLodManifest&gt;

load ​

(ref, level, signal) => Promise&lt;Object3D&lt;Object3DEventMap&gt;&gt;

options? ​

StructureStreamingOptions

Returns ​

StructureLodStreamer

Properties ​

budget ​
ts
readonly budget: StructureStreamingBudget;

Methods ​

acquire() ​
ts
acquire(ref, options?): Promise<StructureModel>;
Parameters ​
ref ​

string

options? ​

StructureAcquireOptions

Returns ​

Promise&lt;StructureModel&gt;

Implementation of ​

StructureModelSource.acquire

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

void

instantiate() ​
ts
instantiate(handle, options?): Object3D;
Parameters ​
handle ​

StructureModel

options? ​

StructureInstanceOptions

Returns ​

Object3D

Implementation of ​

StructureModelSource.instantiate

release() ​
ts
release(ref): void;
Parameters ​
ref ​

string

Returns ​

void

Implementation of ​

StructureModelSource.release

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

StructureStreamingStats

update() ​
ts
update(view): void;
Parameters ​
view ​

StructureStreamingView

Returns ​

void


StructureModelLibrary ​

On-demand static landmark assets. The loader transfers ownership of each returned scene to this library; unlike prop instancing, this path retains UVs, textures and individual materials.

Constructors ​

Constructor ​
ts
new StructureModelLibrary(loadModel, options?): StructureModelLibrary;
Parameters ​
loadModel ​

ModelLoader

options? ​

StructureModelLibraryOptions

Returns ​

StructureModelLibrary

Methods ​

acquire() ​
ts
acquire(ref): Promise<StructureModel>;
Parameters ​
ref ​

string

Returns ​

Promise&lt;StructureModel&gt;

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

void

instantiate() ​
ts
instantiate(model, options?): Object3D;

Clone transforms, retaining the shared immutable geometry and materials.

Parameters ​
model ​

StructureModel

options? ​

StructureInstanceOptions

Returns ​

Object3D

release() ​
ts
release(ref): void;

Pair with each successful acquire, after removing that instance from the scene.

Parameters ​
ref ​

string

Returns ​

void

Interfaces ​

BuildingObjectOptions ​

Properties ​

ground? ​
ts
optional ground?: HeightSampler;
materials ​
ts
materials: WorldgenMaterialSet;
tier? ​
ts
optional tier?: number;

InstancedPlacementLodOptions ​

Properties ​

cellGrid? ​
ts
optional cellGrid?: object;

Bounds the cells to a grid from the set's own lowest corner, cellsPerAxis cells each way: placements past the grid join its edge cells, so a set never yields more than cellsPerAxis² batches whatever frame its coordinates are in.

cellsPerAxis ​
ts
cellsPerAxis: number;
cellSize? ​
ts
optional cellSize?: number;

Local meters per culling cell (default 512); Infinity keeps the whole set in one cell.

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

Distance from a cell's bounds before the medium/far model takes over.

screenSpace? ​
ts
optional screenSpace?: ScreenSpaceLodPolicy;

Projected-detail policy; when supplied it replaces fixed distance thresholds.

vanishPixels? ​
ts
optional vanishPixels?: number;

With screenSpace: hide a batch once its largest instance spans fewer pixels than this from the batch's nearest point (default: drawn at every distance). For small props (signs, benches, hydrants): from a few kilometers they are a pixel or less, yet each batch was still a draw.


InteriorDoorQuery ​

Properties ​

facing? ​
ts
optional facing?: readonly [number, number, number];

The viewer's forward direction; a door behind or beside them is passed over.

reach? ​
ts
optional reach?: number;

Horizontal meters from the position to the doorway (default 1.8).


InteriorDoorState ​

A door near a viewer: see InteriorStreamer.doorAt.

Properties ​

amount ​
ts
amount: number;

How far open: 0 shut, 1 fully open.

distance ​
ts
distance: number;

Horizontal meters from the position asked about to the nearest point of the doorway.

id ​
ts
id: string;

<building identity>#door<n>; pass it to InteriorStreamer.setDoor.

identity ​
ts
identity: string;

Identity of the building it opens into.

locked ​
ts
locked: boolean;

Its rooms could not be built, so it stays shut.

open ​
ts
open: boolean;

Open, or opening; false when closed or closing.

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

Middle of the threshold, at floor height, in the frame of the position asked about.

waiting ​
ts
waiting: boolean;

Asked to open, and waiting for the rooms behind it to be built before it swings.


InteriorElevatorStop ​

The lift a viewer is standing in.

Properties ​

floors ​
ts
floors: number[];

Floor height of each storey the lift serves, in the same frame as the viewer.

identity ​
ts
identity: string;
level ​
ts
level: number;

Site storey the viewer is on.


InteriorStreamingOptions ​

Extends ​

Properties ​

catalog ​
ts
catalog: InteriorCatalogDoc;

The interior catalog, usually the style pack's interiors.

Inherited from ​

InteriorGenerateOptions.catalog

focus? ​
ts
optional focus?: number;

The storey a viewer is on, for a building too tall to build at once: a tower plan covers only the ground floor and the floors around this one (default 0).

Inherited from ​

InteriorGenerateOptions.focus

frameBudgetMs? ​
ts
optional frameBudgetMs?: number;

Cooperative main-thread budget; one indivisible geometry operation may exceed this.

furnish? ​
ts
optional furnish?: (plan, group, origin) => void;

Dress an interior with host content, such as a car park's cars, as it is published. Objects added to group are disposed with it. origin converts site coordinates to the host's.

Parameters ​
plan ​

InteriorPlan

group ​

Group

origin ​

Vec2

Returns ​

void

loadDistance? ​
ts
optional loadDistance?: number;
maxBytes? ​
ts
optional maxBytes?: number;
maxCandidates? ​
ts
optional maxCandidates?: number;
Inherited from ​

InteriorGenerateOptions.maxCandidates

maxFixtures? ​
ts
optional maxFixtures?: number;
Inherited from ​

InteriorGenerateOptions.maxFixtures

maxParkedCars? ​
ts
optional maxParkedCars?: number;

Parked cars across all storeys of one car park (default 1,500; hard ceiling 3,000).

Inherited from ​

InteriorGenerateOptions.maxParkedCars

maxResident? ​
ts
optional maxResident?: number;
now? ​
ts
optional now?: () => number;

Clock for door swings, in milliseconds (default performance.now).

Returns ​

number

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

Builds a finished interior's shaders before it is shown (a renderer's prepareObject), given the region root it will join; the entrance covers stay until it settles. Without it the first frame drawing a new interior built its programs mid-frame, 100 ms or more each.

Parameters ​
object ​

Object3D

signal ​

AbortSignal

parent ​

Object3D

Returns ​

Promise&lt;void&gt;

unloadDistance? ​
ts
optional unloadDistance?: number;

InteriorStreamingStats ​

Properties ​

bytes ​
ts
bytes: number;
evicted ​
ts
evicted: number;
failed ​
ts
failed: number;
generated ​
ts
generated: number;
lastWorkMs ​
ts
lastWorkMs: number;
pending ​
ts
pending: number;
resident ​
ts
resident: number;
sites ​
ts
sites: number;

LoadedStylePack ​

Properties ​

assetIndex ​
ts
assetIndex: Record<string, string>;

Material and asset ids mapped to absolute URLs, for the client asset provider index.

baseUrl ​
ts
baseUrl: string;

Absolute pack directory URL, with a trailing slash.

documents ​
ts
documents: ReadonlyMap<string, string>;

Raw text of every document the load fetched, by absolute URL.

pack ​
ts
pack: ResolvedStylePack;

LoadStylePackOptions ​

Properties ​

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

MDN Reference

Parameters ​
input ​

RequestInfo | URL

init? ​

RequestInit

Returns ​

Promise&lt;Response&gt;

manifest? ​
ts
optional manifest?: string;

Manifest file name inside the pack directory (default stylepack.json).

signal? ​
ts
optional signal?: AbortSignal;

ModelNightLight ​

glTF material extras.molenNightLight. Separate disconnected panes get independent occupancy.

Properties ​

color? ​
ts
optional color?: string;

sRGB light colour; omitted windows vary between warm and neutral white.

kind ​
ts
kind: "window" | "lamp";
occupancy? ​
ts
optional occupancy?: number;

Fraction of panes lit, 0..1 (windows 0.55, lamps 1).


NightWindowRange ​

Properties ​

count ​
ts
count: number;
light? ​
ts
optional light?: ModelNightLight;
start ​
ts
start: number;

PreparedModel ​

Properties ​

bounds ​
ts
bounds: Box3;

Model-space bounds (meters, base at y = 0 for authored models).

builtin ​
ts
builtin: boolean;
geometry ​
ts
geometry: BufferGeometry;
material ​
ts
material: Material;
ref ​
ts
ref: string;

ResolvedMaterialSet ​

Extends ​

Properties ​

failures ​
ts
readonly failures: ReadonlyMap<string, string>;

References that failed to bake (rendered with the flat slot material), with the reason.

nightWindows? ​
ts
optional nightWindows?: NightWindowLighting;

Optional shared nighttime overlay controller; the caller owns its lifetime.

Inherited from ​

WorldgenMaterialSet.nightWindows

textureBytes? ​
ts
readonly optional textureBytes?: number;

Conservative RGBA residency including mipmaps; shared textures counted once.

Methods ​

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

void

Overrides ​

WorldgenMaterialSet.dispose

materialFor() ​
ts
materialFor(slot, materialRef): Material;

Material for a (slot, materialRef) pair; may be shared across groups and batches.

Parameters ​
slot ​

MaterialSlot

materialRef ​

string

Returns ​

Material

Inherited from ​

WorldgenMaterialSet.materialFor

prepare() ​
ts
prepare(refs): Promise<void>;

Bake and cache doc-backed references (matgraph:/pixelgrid:) before rendering; a batch rendered earlier keeps the flat slot material unless progressive materials are enabled.

Parameters ​
refs ​

readonly string[]

Returns ​

Promise&lt;void&gt;


ResolvedMaterialSetOptions ​

Properties ​

concurrency? ​
ts
optional concurrency?: number;
decorate? ​
ts
optional decorate?: BuildingMaterialDecorator;

Adds detail to each building material, e.g. createBuildingWeatheringAsync.

maxTextureBytes? ​
ts
optional maxTextureBytes?: number;

Keep flat placeholders when adding a texture would exceed this shared library budget.

prepareChange? ​
ts
optional prepareChange?: (current, next) => Promise<void>;

Build an upgraded material's shaders before it replaces a progressive placeholder in place, e.g. a renderer's prepareMaterialChange. Without it, every mesh drawing the placeholder built the new shaders in the frame after its bake landed.

Parameters ​
current ​

Material

next ​

Material

Returns ​

Promise&lt;void&gt;

prepareOnUse? ​
ts
optional prepareOnUse?: boolean;

Bake a shared surface when a visible model first requests it.

progressive? ​
ts
optional progressive?: boolean;

Render colors immediately and upgrade the same material objects as textures finish baking.


ScreenSpaceLodPolicy ​

Shared mutable rendering policy. Mutations affect resident LODs without regenerating geometry.

Properties ​

distantShadows? ​
ts
optional distantShadows?: boolean;

Whether an instanced model's distant level casts sun shadows too (default false: only the near levels do; a horizon level never does). From the air the distant level starts a few hundred meters out, well inside the shadow map, and the ground under an aircraft showed a disc of tree shadows that moved with it. A host turns this on where its shadow map can afford to draw every tree out to the horizon level.

horizonPixelError? ​
ts
optional horizonPixelError?: number;

The same budget for the handover to a model's horizon level (default maxPixelError). Both levels there are plain opaque geometry, so a host that relaxes maxPixelError with camera height, to shed leaf cards, keeps this at its base value: an aircraft otherwise sees every conifer below it as the horizon level's single cone.

maxPixelError ​
ts
maxPixelError: number;

Maximum projected geometric/detail error, in rendered pixels.

viewportHeight ​
ts
viewportHeight: number;

Actual drawing-buffer height, not CSS height.


SignAtlasPixels ​

A glyph atlas set's combined page image, as assembleGlyphAtlasPixels returns it.

Properties ​

data ​
ts
data: Uint8Array;
height ​
ts
height: number;
width ​
ts
width: number;

StructureAcquireOptions ​

Properties ​

position? ​
ts
optional position?: readonly [number, number, number];

Metric world coordinates, before renderer floating-origin adjustment.

signal? ​
ts
optional signal?: AbortSignal;

StructureInstanceOptions ​

Properties ​

position? ​
ts
optional position?: readonly [number, number, number];
prepare? ​
ts
optional prepare?: (instance) => Object3D;

Apply placement/clipping to each replacement before its atomic publication.

Parameters ​
instance ​

Object3D

Returns ​

Object3D

scale? ​
ts
optional scale?: number;

StructureLodManifest ​

Properties ​

bounds ​
ts
bounds: AssetBounds;
runtimeLods ​
ts
runtimeLods: AssetRuntimeLods;

StructureModel ​

Properties ​

bounds ​
ts
bounds: Box3;
ref ​
ts
ref: string;
scene ​
ts
scene: Object3D;

Immutable source hierarchy. Instances share its geometry, textures and PBR materials.


StructureModelLibraryOptions ​

Extended by ​

Properties ​

nightWindows? ​
ts
optional nightWindows?: NightWindowLighting;

Night layers for tagged glass/lamp materials. Caller owns the controller.

ownsImageBitmaps? ​
ts
optional ownsImageBitmaps?: boolean | ((scene) => boolean);

The loader transfers its decoded ImageBitmaps too (default false). A predicate can opt in individual freshly parsed scenes after inspecting their image sources. Return false for URI images shared with a host cache; never infer ownership from a cache-enabled snapshot. Borrowed surface images stay external regardless of this option.

resolveSurface? ​
ts
optional resolveSurface?: (surface) => Material<MaterialEventMap> | undefined;

Borrow a shared material owned by the caller. Undefined preserves the GLB's fallback. The returned material must outlive acquired models and may upgrade progressively.

Parameters ​
surface ​

GlbSharedSurface

Returns ​

Material&lt;MaterialEventMap&gt; | undefined


StructureModelRouteOptions ​

Properties ​

isPrimary ​
ts
isPrimary: (ref) => boolean;

Whether a ref is the primary source's. It must answer the same for a ref every time.

Parameters ​
ref ​

string

Returns ​

boolean

keepAliveMs? ​
ts
optional keepAliveMs?: number;

Hold a secondary model this long after it is released, ms (default 5000). When a region is refined, its children take its place a moment after it goes; without the hold a model with no warm cache of its own would be loaded and parsed again for them.

primary ​
ts
primary: StructureModelSource;

The source of the refs isPrimary accepts.

secondary ​
ts
secondary: StructureModelSource;

The source of every other ref.


StructureModelSource ​

Methods ​

acquire() ​
ts
acquire(ref, options?): Promise<StructureModel>;
Parameters ​
ref ​

string

options? ​

StructureAcquireOptions

Returns ​

Promise&lt;StructureModel&gt;

instantiate() ​
ts
instantiate(model, options?): Object3D;
Parameters ​
model ​

StructureModel

options? ​

StructureInstanceOptions

Returns ​

Object3D

release() ​
ts
release(ref): void;
Parameters ​
ref ​

string

Returns ​

void


StructureStreamingBudget ​

Properties ​

concurrency ​
ts
concurrency: number;
frameBudgetMs ​
ts
frameBudgetMs: number;
keepAliveMs ​
ts
keepAliveMs: number;
maxCpuBytes ​
ts
maxCpuBytes: number;
maxDrawCalls ​
ts
maxDrawCalls: number;
maxGpuBytes ​
ts
maxGpuBytes: number;
maxInitialBytes ​
ts
maxInitialBytes: number;

Raw skyline bytes: conservative even when the host does not compress HTTP responses.

maxTextureBytes ​
ts
maxTextureBytes: number;

Separate shared worldgen texture footprint estimate, including GPU mipmaps.

maxTriangles ​
ts
maxTriangles: number;
upgradeDelayMs ​
ts
upgradeDelayMs: number;

StructureStreamingOptions ​

Extends ​

Properties ​

budget? ​
ts
optional budget?: Partial<StructureStreamingBudget>;
clock? ​
ts
optional clock?: () => number;
Returns ​

number

mobile? ​
ts
optional mobile?: boolean;
nightWindows? ​
ts
optional nightWindows?: NightWindowLighting;

Night layers for tagged glass/lamp materials. Caller owns the controller.

Inherited from ​

StructureModelLibraryOptions.nightWindows

ownsImageBitmaps? ​
ts
optional ownsImageBitmaps?: boolean | ((scene) => boolean);

The loader transfers its decoded ImageBitmaps too (default false). A predicate can opt in individual freshly parsed scenes after inspecting their image sources. Return false for URI images shared with a host cache; never infer ownership from a cache-enabled snapshot. Borrowed surface images stay external regardless of this option.

Inherited from ​

StructureModelLibraryOptions.ownsImageBitmaps

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

Prepare replacement GPU resources before publishing; old instances remain visible.

Parameters ​
object ​

Object3D

signal ​

AbortSignal

parent ​

Object3D

Returns ​

Promise&lt;void&gt;

resolveSurface? ​
ts
optional resolveSurface?: (surface) => Material<MaterialEventMap> | undefined;

Borrow a shared material owned by the caller. Undefined preserves the GLB's fallback. The returned material must outlive acquired models and may upgrade progressively.

Parameters ​
surface ​

GlbSharedSurface

Returns ​

Material&lt;MaterialEventMap&gt; | undefined

Inherited from ​

StructureModelLibraryOptions.resolveSurface


StructureStreamingStats ​

Properties ​

assets ​
ts
assets: number;
cpuBytes ​
ts
cpuBytes: number;
drawCalls ​
ts
drawCalls: number;
evicted ​
ts
evicted: number;
failed ​
ts
failed: number;
gpuBytes ​
ts
gpuBytes: number;
levels ​
ts
levels: Record<string, number>;
loading ​
ts
loading: number;
queued ​
ts
queued: number;
reservedCpuBytes ​
ts
reservedCpuBytes: number;
reservedGpuBytes ​
ts
reservedGpuBytes: number;
sharedTextureBytes? ​
ts
optional sharedTextureBytes?: number;
skylineBytes ​
ts
skylineBytes: number;
triangles ​
ts
triangles: number;
upgrades ​
ts
upgrades: number;

StructureStreamingView ​

Properties ​

direction? ​
ts
optional direction?: readonly [number, number, number];
maxPixelError? ​
ts
optional maxPixelError?: number;
position ​
ts
position: readonly [number, number, number];
verticalFov ​
ts
verticalFov: number;

Degrees.

viewportHeight ​
ts
viewportHeight: number;

WorldgenEntityClient ​

The slice of a MolenClient the layer reads.

Properties ​

renderer ​
ts
readonly renderer: object;
worldRoot ​
ts
readonly worldRoot: Object3D;
tick ​
ts
readonly tick: number | undefined;

Methods ​

entities() ​
ts
entities(): string[];
Returns ​

string[]

get() ​
ts
get(id, component): JsonObject | undefined;
Parameters ​
id ​

string

component ​

string

Returns ​

JsonObject | undefined


WorldgenEntityLayer ​

Properties ​

objectCount ​
ts
readonly objectCount: number;

Methods ​

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

void

invalidate() ​
ts
invalidate(): void;

Force a rescan on the next update even if the tick did not advance.

Returns ​

void

update() ​
ts
update(): void;

Rebuild or remove objects to match the client's entities; call once per frame.

Returns ​

void


WorldgenEntityLayerOptions ​

Properties ​

ground? ​
ts
optional ground?: HeightSampler;

Ground in entity-local meters (default flat at y = 0).

materials? ​
ts
optional materials?: WorldgenMaterialSet;
models? ​
ts
optional models?: ModelLibrary;

Prop models; without it roof props are skipped.

pack ​
ts
pack: ResolvedStylePack;

WorldgenMaterialSet ​

Extended by ​

Properties ​

nightWindows? ​
ts
optional nightWindows?: NightWindowLighting;

Optional shared nighttime overlay controller; the caller owns its lifetime.

Methods ​

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

void

materialFor() ​
ts
materialFor(slot, materialRef): Material;

Material for a (slot, materialRef) pair; may be shared across groups and batches.

Parameters ​
slot ​

MaterialSlot

materialRef ​

string

Returns ​

Material

Type Aliases ​

BuildingMaterialDecorator ​

ts
type BuildingMaterialDecorator = (material, slot) => void;

Adds detail to a building material a material set creates (decorate on createResolvedMaterialSet and createVertexColorMaterialSet). Called once per material.

Parameters ​

material ​

THREE.MeshStandardMaterial

slot ​

MaterialSlot

Returns ​

void


ModelDetail ​

ts
type ModelDetail = boolean | "distant" | "horizon";

Which of a model's levels: false near, true medium, 'distant' far, and 'horizon' the level past that. Only conifers have a horizon model of their own (one cone, where the far level keeps three skirts); for every other model it is the far model itself.


ModelLoader ​

ts
type ModelLoader = (ref) => Promise<THREE.Object3D>;

Parameters ​

ref ​

string

Returns ​

Promise&lt;THREE.Object3D&gt;


ScatterMaterial ​

ts
type ScatterMaterial = THREE.MeshStandardMaterial | MeshStandardNodeMaterial;

Scatter material for either the legacy WebGL renderer or the WebGPU node renderer.


SignMaterial ​

ts
type SignMaterial = THREE.MeshStandardMaterial | MeshStandardNodeMaterial;

Sign material for either renderer backend.

Variables ​

SCATTER_CANOPY_ATTRIBUTE ​

ts
const SCATTER_CANOPY_ATTRIBUTE: "canopy";

Per-vertex canopy attribute: 0 for props, 1 + relative height (1 at the base to 2 at the top) for plants. ModelLibrary writes it on every geometry it prepares.


SIGN_INK_ATTRIBUTE ​

ts
const SIGN_INK_ATTRIBUTE: "signInk";

SIGN_LETTER_PIXELS ​

ts
const SIGN_LETTER_PIXELS: 3 = 3;

Letters are drawn while a cap height spans this many pixels; plates while they span this many.


SIGN_PLATE_ATTRIBUTE ​

ts
const SIGN_PLATE_ATTRIBUTE: "signPlate";

Per-vertex plate and letter colors: normalized linear RGB plus padding, four bytes each.


SIGN_PLATE_PIXELS ​

ts
const SIGN_PLATE_PIXELS: 1.5 = 1.5;

TEXTURED_SURFACE_MEAN ​

ts
const TEXTURED_SURFACE_MEAN: 0.65 = .65;

Mean linear base color of the shared tinted material graphs (siding, shingle, brick, render, concrete, membrane: 0.52–0.77, most near 0.65). A flat stand-in for a textured surface multiplies by it, so a building keeps its brightness when its textures finish loading or its level of detail changes; untinted it renders about 1.5 times brighter than up close.

Functions ​

buffersToObject3D() ​

ts
function buffersToObject3D(
   buffers, 
   materials, 
   name?
): Mesh;

One mesh with one geometry group per material; owns its geometry, shares materials.

Parameters ​

buffers ​

MeshBuffers

materials ​

WorldgenMaterialSet

name? ​

string

Returns ​

Mesh


buildingBoxGeometry() ​

ts
function buildingBoxGeometry(modelRef): 
  | BufferGeometry<NormalBufferAttributes, BufferGeometryEventMap>
  | undefined;

The shared stand-in geometry for a box placement set's model, or undefined for other models.

Parameters ​

modelRef ​

string

Returns ​

| BufferGeometry&lt;NormalBufferAttributes, BufferGeometryEventMap&gt; | undefined


createBuildingCellLod() ​

ts
function createBuildingCellLod(
   cell, 
   materials, 
   flatMaterial, 
   policy, 
   name?
): ScreenSpaceLod;

Small admission unit: no triangle partition, remapping, or LOD-index construction here.

Parameters ​

cell ​

PreparedBuildingCell

materials ​

WorldgenMaterialSet

flatMaterial ​

Material

policy ​

ScreenSpaceLodPolicy

name? ​

string

Returns ​

ScreenSpaceLod


createBuildingDetailLod() ​

ts
function createBuildingDetailLod(
   buffers, 
   materials, 
   flatMaterial, 
   policy, 
   name?, 
   cellSize?, 
   prepared?
): Group;

Three detail levels share compact cell-local attributes and full-detail indices.

Parameters ​

buffers ​

MeshBuffers

materials ​

WorldgenMaterialSet

flatMaterial ​

Material

policy ​

ScreenSpaceLodPolicy

name? ​

string

cellSize? ​

number

prepared? ​

readonly PreparedBuildingCell[]

Returns ​

Group


createBuildingObject() ​

ts
function createBuildingObject(
   request, 
   style, 
   pack, 
   options
): Object3D<Object3DEventMap> | undefined;

Returns a mesh (or an instanced box beyond the last detail tier), or undefined when skipped.

Parameters ​

request ​

BuildingRequest

style ​

ArchStyleDoc

pack ​

PackIdentity

options ​

BuildingObjectOptions

Returns ​

Object3D&lt;Object3DEventMap&gt; | undefined


createBuildingWeathering() ​

ts
function createBuildingWeathering(): BuildingMaterialDecorator;

WebGL weathering: shader hooks on the standard material itself.

Returns ​

BuildingMaterialDecorator


createBuildingWeatheringAsync() ​

ts
function createBuildingWeatheringAsync(backend?): Promise<BuildingMaterialDecorator>;

Weathering for an initialized renderer's backend. WebGPU converts standard materials to node materials property by property, so the decorator sets a colorNode on the standard material.

Parameters ​

backend? ​

"webgl" | "webgpu"

Returns ​

Promise&lt;BuildingMaterialDecorator&gt;


createInstancedPlacementLod() ​

ts
function createInstancedPlacementLod(
   set, 
   models, 
   options?, 
   name?
): Group;

No per-frame instance uploads: LOD switches shared models, with 15% transition hysteresis. models are the near, medium and far models and, optionally, a horizon model: see ScreenSpaceLodPolicy.horizonPixelError.

Parameters ​

set ​

PlacementSet

models ​

| readonly [PreparedModel, PreparedModel, PreparedModel] | readonly [PreparedModel, PreparedModel, PreparedModel, PreparedModel]

options? ​

InstancedPlacementLodOptions

name? ​

string

Returns ​

Group


createInstancedPlacements() ​

ts
function createInstancedPlacements(
   set, 
   geometry, 
   material, 
   name?
): InstanceBatch;

One instanced mesh for a placement set; geometry is shared, instance buffers are owned. It is an InstanceBatch, so on WebGPU every set drawn with one material shares one shader build.

Parameters ​

set ​

PlacementSet

geometry ​

BufferGeometry

material ​

Material

name? ​

string

Returns ​

InstanceBatch


createPlantGeometry() ​

ts
function createPlantGeometry(p, detail?): BufferGeometry;

Generated once per model/LOD and shared by all instances.

Parameters ​

p ​

PlantPreset

detail? ​

Detail

Returns ​

BufferGeometry


createResolvedMaterialSet() ​

ts
function createResolvedMaterialSet(resolver, options?): ResolvedMaterialSet;

Textured materials through the app's MaterialResolver: every prepared reference becomes one shared material with vertex colors on (palette tints multiply the texture) and repeat wrapping (generated UVs are in texture repeats). Palette references and unprepared refs fall back to the flat per-slot materials.

Parameters ​

resolver ​

MaterialResolver

options? ​

ResolvedMaterialSetOptions

Returns ​

ResolvedMaterialSet


createScatterMaterial() ​

ts
function createScatterMaterial(): MeshStandardMaterial;

WebGL scatter material: a standard vertex-color material with the detail in its hooks.

Returns ​

MeshStandardMaterial


createScatterMaterialAsync() ​

ts
function createScatterMaterialAsync(backend?): Promise<ScatterMaterial>;

Scatter material for an initialized renderer's backend; WebGPU builds the same as nodes.

Parameters ​

backend? ​

"webgl" | "webgpu"

Returns ​

Promise&lt;ScatterMaterial&gt;


createSignAtlasTexture() ​

ts
function createSignAtlasTexture(pixels): DataTexture;

Upload a glyph atlas image once: single-channel distances, mipmapped. Caller-owned.

Parameters ​

pixels ​

SignAtlasPixels

Returns ​

DataTexture


createSignMaterial() ​

ts
function createSignMaterial(atlas, distanceRange): MeshStandardMaterial;

WebGL sign material: plates in their vertex colors, letters (its twin, see signLettersMaterial) from atlas, a createSignAtlasTexture of a glyph atlas set with that distanceRange. Disposing it disposes the twin; the texture stays the caller's.

Parameters ​

atlas ​

Texture

distanceRange ​

number

Returns ​

MeshStandardMaterial


createSignMaterialAsync() ​

ts
function createSignMaterialAsync(
   backend, 
   atlas, 
   distanceRange
): Promise<SignMaterial>;

Sign material for an initialized renderer's backend; WebGPU builds the same as nodes.

Parameters ​

backend ​

"webgl" | "webgpu"

atlas ​

Texture

distanceRange ​

number

Returns ​

Promise&lt;SignMaterial&gt;


createSignMeshObject() ​

ts
function createSignMeshObject(
   signs, 
   material, 
   policy?, 
   name?
): Object3D;

The sign mesh as a detail switch at its bounds' center: plates and letters, then the plates alone, then nothing. Every level draws a range of the same buffers: the plates are the leading plateIndexCount indices, the letters the rest. Thresholds are in pixels of the smallest name and plate against the policy's viewport, whatever its pixel error. material is a sign material (createSignMaterialAsync); its letters twin draws the letters. Geometry is owned (worldgenOwnedGeometry); the materials are the caller's.

Parameters ​

signs ​

SignMeshBuffers

material ​

Material

policy? ​

ScreenSpaceLodPolicy

name? ​

string

Returns ​

Object3D


createVertexColorMaterialSet() ​

ts
function createVertexColorMaterialSet(options?): WorldgenMaterialSet;

Four-ish shared vertex-colored materials (one per slot). Every material reference collapses onto the slot material, so a batch costs at most one draw call per slot. Pass surfaceMean (usually TEXTURED_SURFACE_MEAN) when the set stands in for textured surfaces.

Parameters ​

options? ​
decorate? ​

BuildingMaterialDecorator

surfaceMean? ​

number

Returns ​

WorldgenMaterialSet


createWorldgenEntityLayer() ​

ts
function createWorldgenEntityLayer(client, options): WorldgenEntityLayer;

Parameters ​

client ​

WorldgenEntityClient

options ​

WorldgenEntityLayerOptions

Returns ​

WorldgenEntityLayer


disposeWorldgenObject() ​

ts
function disposeWorldgenObject(root): void;

Dispose geometry and instance buffers this package created; shared materials survive.

Parameters ​

root ​

Object3D

Returns ​

void


gableBoxGeometry() ​

ts
function gableBoxGeometry(): BufferGeometry;

Shared unit gable house: footprint [-0.5, 0.5]², walls to GABLE_BOX_EAVE, ridge along x at height 1, a small overhang, flat-shaded (each face its own vertices).

Returns ​

BufferGeometry


loadStylePack() ​

ts
function loadStylePack(baseUrl, options?): Promise<LoadedStylePack>;

Parameters ​

baseUrl ​

string | URL

options? ​

LoadStylePackOptions

Returns ​

Promise&lt;LoadedStylePack&gt;


mergeSceneGeometry() ​

ts
function mergeSceneGeometry(root): 
  | BufferGeometry<NormalBufferAttributes, BufferGeometryEventMap>
  | undefined;

Flatten every mesh of a scene into one geometry with baked material colors.

Parameters ​

root ​

Object3D

Returns ​

| BufferGeometry&lt;NormalBufferAttributes, BufferGeometryEventMap&gt; | undefined


routeStructureModels() ​

ts
function routeStructureModels(options): StructureModelSource & object;

Two model sources behind one: each ref goes to the source isPrimary names for it, for its whole life (a model is instantiated and released by the source that acquired it). It lets a streamed catalog and a plain library of a host's own models serve the same placements. dispose drops the releases it is holding; the sources stay the caller's to dispose.

Parameters ​

options ​

StructureModelRouteOptions

Returns ​

StructureModelSource & object


setScatterCanopy() ​

ts
function setScatterCanopy(geometry, plant): void;

Write the canopy attribute: relative height for plants (1 at the base to 2 at the top), 0 for everything else. Every geometry the scatter material draws carries it, so all share a program. A geometry without atlas coordinates also gets the solid uv (see SCATTER_SOLID_UV).

Parameters ​

geometry ​

BufferGeometry

plant ​

boolean

Returns ​

void


signLettersMaterial() ​

ts
function signLettersMaterial(material): Material<MaterialEventMap> | undefined;

The material a sign material draws its letters with (see the module comment).

Parameters ​

material ​

Material

Returns ​

Material&lt;MaterialEventMap&gt; | undefined


structureGeometryBytes() ​

ts
function structureGeometryBytes(roots): object;

Geometry accounting matches Three's actual upload keys, including mixed-type interleaving.

Parameters ​

roots ​

Iterable&lt;Object3D&lt;Object3DEventMap&gt;&gt;

Returns ​

object

cpuBytes ​
ts
cpuBytes: number;
gpuBytes ​
ts
gpuBytes: number;

structureStreamingBudget() ​

ts
function structureStreamingBudget(mobile): StructureStreamingBudget;

Parameters ​

mobile ​

boolean

Returns ​

StructureStreamingBudget


structureStreamingMobile() ​

ts
function structureStreamingMobile(): boolean;

Whether landmarks get the phone budget: a touch-first device (a coarse primary pointer, the test the host binding's memory budget uses) or one reporting 4 GiB or less. A laptop with a touch screen still has a fine primary pointer. Counting any touch point as a phone held such a desktop to the phone draw-call budget, which kept a city's landmarks on their skylines.

Returns ​

boolean


unitBoxGeometry() ​

ts
function unitBoxGeometry(): BoxGeometry;

Shared unit cube with its base at y = 0 and a darker top face baked into vertex colors.

Returns ​

BoxGeometry


withStylePackDocuments() ​

ts
function withStylePackDocuments(provider, loaded): AssetProvider;

Serve documents the pack load already fetched (its material docs) from memory, so a MaterialResolver built on this provider doesn't download them a second time. Everything else, including model bytes, goes to provider.

Parameters ​

provider ​

AssetProvider

loaded ​

Pick&lt;LoadedStylePack, "assetIndex" | "documents"&gt;

Returns ​

AssetProvider

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