Molen

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 ​

InteriorStreamingOptions

Returns ​

InteriorStreamer

Methods ​

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

void

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

Object3D

sites ​

readonly InteriorSite[]

origin? ​

Vec2

Returns ​

void

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?
): ModelLibrary;
Parameters ​
loadModel? ​

ModelLoader

landmarks? ​

Readonly<Record<string, LandmarkDoc>>

disposeLoadedScene? ​

boolean

Returns ​

ModelLibrary

Methods ​

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

Hold a prepared model while a consumer uses its geometry.

Parameters ​
ref ​

string

coarse? ​

boolean | "distant"

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? ​

boolean | "distant"

Returns ​

PreparedModel | undefined

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

string

coarse? ​

boolean | "distant"

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? ​

boolean | "distant"

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

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): Object3D;

Clone transforms, retaining the shared immutable geometry and materials.

Parameters ​
model ​

StructureModel

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 ​

cellSize? ​
ts
optional cellSize?: number;

Local meters per culling cell (default 512).

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.

InteriorStreamingOptions ​

Extends ​

Properties ​

catalog ​
ts
catalog: InteriorCatalogDoc;

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

Inherited from ​

InteriorGenerateOptions.catalog

frameBudgetMs? ​
ts
optional frameBudgetMs?: number;

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

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

maxResident? ​
ts
optional maxResident?: number;
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;

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.

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 ​

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 ​

maxPixelError ​
ts
maxPixelError: number;

Maximum projected geometric/detail error, in rendered pixels.

viewportHeight ​
ts
viewportHeight: number;

Actual drawing-buffer height, not CSS height.

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 ​

Properties ​

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

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 ​

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 ​

ModelLoader ​

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

Parameters ​

ref ​

string

Returns ​

Promise&lt;THREE.Object3D&gt;

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

createInstancedPlacementLod() ​

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

No per-frame instance uploads: LOD switches shared models, with 15% transition hysteresis.

Parameters ​

set ​

PlacementSet

models ​

readonly [PreparedModel, PreparedModel, PreparedModel]

options? ​

InstancedPlacementLodOptions

name? ​

string

Returns ​

Group

createInstancedPlacements() ​

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

One InstancedMesh for a placement set; geometry is shared, instance buffers are owned.

Parameters ​

set ​

PlacementSet

geometry ​

BufferGeometry

material ​

Material

name? ​

string

Returns ​

InstancedMesh

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

createVertexColorMaterialSet() ​

ts
function createVertexColorMaterialSet(): 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.

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

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

37 guides · 36 schema formats · 41 API entry points · 10 samples. API, CLI and schema pages are generated from the shipped build.

Molen / Bendyline