Appearance
@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
Returns
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?
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?
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
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?
landmarks?
Readonly<Record<string, LandmarkDoc>>
disposeLoadedScene?
boolean
plants?
Readonly<Record<string, PlantPreset>>
fonts?
FontLibrary
material?
Material<MaterialEventMap>
Returns
Methods
acquire()
ts
acquire(ref, coarse?): Promise<PreparedModel>;Hold a prepared model while a consumer uses its geometry.
Parameters
ref
string
coarse?
Returns
Promise<PreparedModel>
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?
Returns
PreparedModel | undefined
prepare()
ts
prepare(ref, coarse?): Promise<PreparedModel>;Parameters
ref
string
coarse?
Returns
Promise<PreparedModel>
release()
ts
release(ref, coarse?): void;Release prepared geometry when the last consumer drops its reference.
Parameters
ref
string
coarse?
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
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<NormalBufferAttributes, BufferGeometryEventMap> | 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
radius
number
Returns
Overrides
ts
THREE.LOD.constructorProperties
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.getCurrentLevelupdate()
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.updateStructureLodStreamer
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<StructureLodManifest>
load
(ref, level, signal) => Promise<Object3D<Object3DEventMap>>
options?
Returns
Properties
budget
ts
readonly budget: StructureStreamingBudget;Methods
acquire()
ts
acquire(ref, options?): Promise<StructureModel>;Parameters
ref
string
options?
Returns
Promise<StructureModel>
Implementation of
dispose()
ts
dispose(): void;Returns
void
instantiate()
ts
instantiate(handle, options?): Object3D;Parameters
handle
options?
Returns
Object3D
Implementation of
StructureModelSource.instantiate
release()
ts
release(ref): void;Parameters
ref
string
Returns
void
Implementation of
stats()
ts
stats(): StructureStreamingStats;Returns
update()
ts
update(view): void;Parameters
view
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
options?
Returns
Methods
acquire()
ts
acquire(ref): Promise<StructureModel>;Parameters
ref
string
Returns
Promise<StructureModel>
dispose()
ts
dispose(): void;Returns
void
instantiate()
ts
instantiate(model, options?): Object3D;Clone transforms, retaining the shared immutable geometry and materials.
Parameters
model
options?
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
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
group
Group
origin
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<void>
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>;Parameters
input
RequestInfo | URL
init?
RequestInit
Returns
Promise<Response>
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
materialFor()
ts
materialFor(slot, materialRef): Material;Material for a (slot, materialRef) pair; may be shared across groups and batches.
Parameters
slot
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<void>
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<void>
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
Returns
Material<MaterialEventMap> | 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?
Returns
Promise<StructureModel>
instantiate()
ts
instantiate(model, options?): Object3D;Parameters
model
options?
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<void>
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
Returns
Material<MaterialEventMap> | 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
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
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<THREE.Object3D>
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
materials
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<NormalBufferAttributes, BufferGeometryEventMap> | 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
materials
flatMaterial
Material
policy
name?
string
Returns
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
materials
flatMaterial
Material
policy
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
style
pack
options
Returns
Object3D<Object3DEventMap> | undefined
createBuildingWeathering()
ts
function createBuildingWeathering(): BuildingMaterialDecorator;WebGL weathering: shader hooks on the standard material itself.
Returns
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<BuildingMaterialDecorator>
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
models
| readonly [PreparedModel, PreparedModel, PreparedModel] | readonly [PreparedModel, PreparedModel, PreparedModel, PreparedModel]
options?
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
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
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?
Returns
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<ScatterMaterial>
createSignAtlasTexture()
ts
function createSignAtlasTexture(pixels): DataTexture;Upload a glyph atlas image once: single-channel distances, mipmapped. Caller-owned.
Parameters
pixels
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<SignMaterial>
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
material
Material
policy?
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?
surfaceMean?
number
Returns
createWorldgenEntityLayer()
ts
function createWorldgenEntityLayer(client, options): WorldgenEntityLayer;Parameters
client
options
Returns
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?
Returns
Promise<LoadedStylePack>
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<NormalBufferAttributes, BufferGeometryEventMap> | 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
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<MaterialEventMap> | undefined
structureGeometryBytes()
ts
function structureGeometryBytes(roots): object;Geometry accounting matches Three's actual upload keys, including mixed-type interleaving.
Parameters
roots
Iterable<Object3D<Object3DEventMap>>
Returns
object
cpuBytes
ts
cpuBytes: number;gpuBytes
ts
gpuBytes: number;structureStreamingBudget()
ts
function structureStreamingBudget(mobile): StructureStreamingBudget;Parameters
mobile
boolean
Returns
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<LoadedStylePack, "assetIndex" | "documents">
Returns
AssetProvider