Skip to content

@bendyline/molen-ambient/kernel ​

Molen ambient-life capability: transport networks built from roads, rail and paths, with lane-following NPC cars, trains, aircraft and pedestrians spawned around an observer (kernel) and instanced rendering (client).

ts
import { /* … */ } from '@bendyline/molen-ambient/kernel';

Classes ​

LaneGrid ​

Constructors ​

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

LaneGrid

Properties ​

version ​
ts
version: number;

Bumped on every change; lets callers cache derived sums.

Methods ​

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

void

edgesNear() ​
ts
edgesNear(
   x, 
   z, 
   r
): string[];

Distinct edge ids with a span within r (span midpoints, padded by half a span).

Parameters ​
x ​

number

z ​

number

r ​

number

Returns ​

string[]

insert() ​
ts
insert(edge, laneCounts): void;
Parameters ​
edge ​

TransportEdge

laneCounts ​

Readonly<Record<TransportClass, number>>

Returns ​

void

laneMeters() ​
ts
laneMeters(
   x, 
   z, 
   r, 
   cls
): number;

Lane-metres of a class in cells overlapping the disc.

Parameters ​
x ​

number

z ​

number

r ​

number

cls ​

TransportClass

Returns ​

number

remove() ​
ts
remove(edgeId): void;
Parameters ​
edgeId ​

string

Returns ​

void

removeAll() ​
ts
removeAll(edgeIds): void;

Remove edges together, each touched cell's spans filtered once: a tile's edges share its cells, and filtering a dense city cell again for each of its edges held a frame 5 ms as the tile left.

Parameters ​
edgeIds ​

Iterable<string>

Returns ​

void

spansWithin() ​
ts
spansWithin(
   x, 
   z, 
   rMin, 
   rMax
): EdgeSpan[];

Spans whose midpoint lies in the annulus [rMin, rMax].

Parameters ​
x ​

number

z ​

number

rMin ​

number

rMax ​

number

Returns ​

EdgeSpan[]


TransportNetwork ​

Implements ​

  • GraphStore

Constructors ​

Constructor ​
ts
new TransportNetwork(options?): TransportNetwork;
Parameters ​
options? ​

TransportNetworkOptions

Returns ​

TransportNetwork

Properties ​

grid ​
ts
readonly grid: LaneGrid;
traffic ​
ts
readonly traffic: "right" | "left";
Implementation of ​
ts
GraphStore.traffic
version ​
ts
version: number;

Bumped whenever lanes appear, disappear or change.

Methods ​

addDocument() ​
ts
addDocument(doc): void;

Add a transport-network document's ways, stations, signals and aerodromes.

Parameters ​
doc ​

TransportNetworkDocument

Returns ​

void

addPolyline() ​
ts
addPolyline(line): string | undefined;

Add one polyline (scripts); returns the id of the first edge it produced, if any.

Parameters ​
line ​

AmbientPolyline

Returns ​

string | undefined

aerodromes() ​
ts
aerodromes(): WorldPoi[];

Aerodrome POIs (and runway midpoints) across registered tiles.

Returns ​

WorldPoi[]

builds() ​
ts
builds(cls): boolean;

Whether a lane class is being built.

Parameters ​
cls ​

TransportClass

Returns ​

boolean

clear() ​
ts
clear(): void;

Drop everything.

Returns ​

void

crossingsOf() ​
ts
crossingsOf(edgeId): readonly TransportCrossing[];
Parameters ​
edgeId ​

string

Returns ​

readonly TransportCrossing[]

deleteJunction() ​
ts
deleteJunction(id): void;
Parameters ​
id ​

string

Returns ​

void

Implementation of ​
ts
GraphStore.deleteJunction
edge() ​
ts
edge(id): TransportEdge | undefined;
Parameters ​
id ​

string

Returns ​

TransportEdge | undefined

Implementation of ​
ts
GraphStore.edge
edgeList() ​
ts
edgeList(): IterableIterator<TransportEdge>;

Every edge, for export (networkToDocument).

Returns ​

IterableIterator&lt;TransportEdge&gt;

giveWayNear() ​
ts
giveWayNear(
   x, 
   z, 
   radius, 
   layer?
): readonly WorldPoi[];

Stop and yield signs within radius of a point.

Parameters ​
x ​

number

z ​

number

radius ​

number

layer? ​

number

Returns ​

readonly WorldPoi[]

Implementation of ​
ts
GraphStore.giveWayNear
hasTile() ​
ts
hasTile(key): boolean;

Whether a tile key is registered.

Parameters ​
key ​

string

Returns ​

boolean

junction() ​
ts
junction(id): TransportJunction | undefined;
Parameters ​
id ​

string

Returns ​

TransportJunction | undefined

Implementation of ​
ts
GraphStore.junction
junctionList() ​
ts
junctionList(): IterableIterator<TransportJunction>;
Returns ​

IterableIterator&lt;TransportJunction&gt;

lane() ​
ts
lane(id): TransportLane | undefined;
Parameters ​
id ​

string

Returns ​

TransportLane | undefined

Implementation of ​
ts
GraphStore.lane
laneAt() ​
ts
laneAt(
   x, 
   z, 
   opts?
): 
  | {
  distance: number;
  lane: string;
  s: number;
}
  | undefined;

The nearest lane of a class to a point, with the lane coordinate of the closest point.

Parameters ​
x ​

number

z ​

number

opts? ​
class? ​

TransportClass

radius? ​

number

Returns ​

| { distance: number; lane: string; s: number; } | undefined

laneIds() ​
ts
laneIds(): IterableIterator<string>;

Every lane id (registration order).

Returns ​

IterableIterator&lt;string&gt;

lanesOfClass() ​
ts
lanesOfClass(edgeId, cls): number;

How many of an edge's lanes are of cls. A city's spawn ring is tens of thousands of spans, and looking up every lane of each one held a spawning tick near 10 ms.

Parameters ​
edgeId ​

string

cls ​

TransportClass

Returns ​

number

movement() ​
ts
movement(from, to): LaneMovement | undefined;

The movement from from onto to, if one exists.

Parameters ​
from ​

string | undefined

to ​

string

Returns ​

LaneMovement | undefined

node() ​
ts
node(id): TransportNode | undefined;
Parameters ​
id ​

string

Returns ​

TransportNode | undefined

Implementation of ​
ts
GraphStore.node
registerTile() ​
ts
registerTile(input): void;

Build and add one map tile (replacing a previous registration under the same key).

Parameters ​
input ​

AmbientTileInput

Returns ​

void

runways() ​
ts
runways(): TransportRunway[];
Returns ​

TransportRunway[]

sampleLane() ​
ts
sampleLane(
   laneId, 
   s, 
   out?
): LaneSample | undefined;

Sample a lane body at s (clamped to the lane).

Parameters ​
laneId ​

string

s ​

number

out? ​

LaneSample

Returns ​

LaneSample | undefined

setClasses() ​
ts
setClasses(classes): void;

Change which lane classes are built (applies to tiles registered afterwards).

Parameters ​
classes ​

readonly TransportClass[]

Returns ​

void

setJunction() ​
ts
setJunction(junction): void;
Parameters ​
junction ​

TransportJunction

Returns ​

void

Implementation of ​
ts
GraphStore.setJunction
signalNear() ​
ts
signalNear(
   x, 
   z, 
   radius, 
   layer?
): boolean;

Whether a mapped traffic-signal point lies within radius of a point.

Parameters ​
x ​

number

z ​

number

radius ​

number

layer? ​

number

Returns ​

boolean

Implementation of ​
ts
GraphStore.signalNear
sizes() ​
ts
sizes(): Pick<TransportNetworkStats, "tiles" | "nodes" | "edges" | "lanes" | "junctions">;

The network's sizes, without the walks stats() makes.

Returns ​

Pick&lt;TransportNetworkStats, "tiles" | "nodes" | "edges" | "lanes" | "junctions"&gt;

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

TransportNetworkStats

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

string[]

unregisterTile() ​
ts
unregisterTile(key): void;

Remove a tile: its edges, lanes and nodes; stitched neighbours become open ends again.

Parameters ​
key ​

string

Returns ​

void

Interfaces ​

AgentEnv ​

Properties ​

dt ​
ts
dt: number;
net ​
ts
net: TransportNetwork;
policy ​
ts
policy: AmbientPolicy;
snowCover? ​
ts
optional snowCover?: object;

The weather's lying snow: pedestrians wade through it more slowly.

depth? ​
ts
optional depth?: number;
depthGain? ​
ts
optional depthGain?: number;
level ​
ts
level: number;
maxDepth? ​
ts
optional maxDepth?: number;
transition? ​
ts
optional transition?: number;
solids ​
ts
solids: readonly AmbientSolid[];

Solids cars yield to (queried from the world by the caller).

speedScale? ​
ts
optional speedScale?: number;

Internal scale resolved from the world's boost setting by stepAgents.

tick ​
ts
tick: number;
tickRate ​
ts
tickRate: number;

AmbientAgentData ​

Extends ​

  • JsonObject

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

air? ​
ts
optional air?: AmbientAirCorridor;
boosted? ​
ts
optional boosted?: boolean;

Kernel-owned: the lane speed includes the world's 4× travel boost.

carIndex? ​
ts
optional carIndex?: number;
color? ​
ts
optional color?: string;
consist? ​
ts
optional consist?: string;
cruise? ​
ts
optional cruise?: number;

Vessel cruise limit, stored so checkpoint/replay does not depend on a mutable type pool.

hidden? ​
ts
optional hidden?: boolean;
hops ​
ts
hops: number;
kind ​
ts
kind: AmbientKind;
lane ​
ts
lane: string;
length ​
ts
length: number;
next? ​
ts
optional next?: string;
offset? ​
ts
optional offset?: number;

Train cars: distance behind the lead's centre, metres (default from carIndex).

prev? ​
ts
optional prev?: string;
s ​
ts
s: number;
seed ​
ts
seed: number;
served? ​
ts
optional served?: string;
since ​
ts
since: number;
spawnedTick ​
ts
spawnedTick: number;
speed ​
ts
speed: number;
state ​
ts
state: "move" | "wait" | "dwell" | "idle";
trail? ​
ts
optional trail?: string[];
type ​
ts
type: string;
width ​
ts
width: number;

AmbientAirCorridor ​

An aircraft corridor: a straight line flown at linearly varying altitude.

Extends ​

  • JsonObject

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

dx ​
ts
dx: number;
dz ​
ts
dz: number;
length ​
ts
length: number;
x ​
ts
x: number;
y0 ​
ts
y0: number;
y1 ​
ts
y1: number;
z ​
ts
z: number;

AmbientBox ​

An oriented box on the ground (for host collision queries).

Properties ​

center ​
ts
center: readonly [number, number, number];
halfSize ​
ts
halfSize: readonly [number, number, number];

Half extents: x across, y up, z along.

yaw ​
ts
yaw: number;

Yaw about +Y (0 = +Z forward).


AmbientBudget ​

Scale the rings and caps for a density factor and caps from a host budget.

Properties ​

aircraft? ​
ts
optional aircraft?: number;
boats? ​
ts
optional boats?: number;
cars? ​
ts
optional cars?: number;
pedestrianRadius? ​
ts
optional pedestrianRadius?: number;

Outer spawn radius for pedestrians.

pedestrians? ​
ts
optional pedestrians?: number;
radius? ​
ts
optional radius?: number;

Outer spawn radius for cars; trains keep their ratio to it.

trains? ​
ts
optional trains?: number;

AmbientCapabilityOptions ​

Extends ​

Properties ​

carsAt? ​
ts
optional carsAt?: (x, z) => readonly AmbientVehicleType[];

Deterministic local road fleet at a prospective spawn point. An empty list suppresses it.

Parameters ​
x ​

number

z ​

number

Returns ​

readonly AmbientVehicleType[]

Inherited from ​

AmbientOptions.carsAt

ground? ​
ts
optional ground?: (x, z) => number;

Ground height for documents, aircraft and tiles without their own sampler (default 0).

Parameters ​
x ​

number

z ​

number

Returns ​

number

Inherited from ​

AmbientOptions.ground

networks? ​
ts
optional networks?: Readonly<Record<string, TransportNetworkDocument>>;

Networks for ambient.network paths, keyed by the path as written in the scene.

policy? ​
ts
optional policy?: DeepPartial<AmbientPolicy>;

Policy overrides (rings, densities, caps, driver parameters).

Inherited from ​

AmbientOptions.policy

registrationsPerTick? ​
ts
optional registrationsPerTick?: number;

Tile registrations a tick applies, in queue order (removals are not counted); default all. A dense tile's network takes tens of milliseconds to build, so a host streaming many tiles (or one tile in parts, see AmbientTileInput.bounds) passes 1 to keep each tick short.

Inherited from ​

AmbientOptions.registrationsPerTick

removalsPerTick? ​
ts
optional removalsPerTick?: number;

Tile removals a tick applies, in queue order; default all. A tile streamed in parts leaves all at once, and removing every part (rebuilding the junctions they were stitched to) in one tick held it 10 ms.

Inherited from ​

AmbientOptions.removalsPerTick

templates? ​
ts
optional templates?: Partial<Record<AmbientKind, AmbientTemplate | null>>;

Extra components per class; null spawns bare agents (ambientAgent + transform only).

Inherited from ​

AmbientOptions.templates

tunnels? ​
ts
optional tunnels?: "hidden" | "skip";

Tunnels: keep them with hidden agents (default) or drop them.

Inherited from ​

AmbientOptions.tunnels

types? ​
ts
optional types?: Partial<AmbientTypes>;

Vehicle and pedestrian types per class (default: proxy dimensions).

Inherited from ​

AmbientOptions.types

yieldToDriven? ​
ts
optional yieldToDriven?: boolean;

Cars yield to vehicles someone is driving (mounted riders); default true.

Inherited from ​

AmbientOptions.yieldToDriven


AmbientClassPolicy ​

Properties ​

enabled ​
ts
enabled: boolean;
far ​
ts
far: number;

Spawn out to this distance (metres).

keep ​
ts
keep: number;

Remove beyond this distance (metres).

max ​
ts
max: number;

Hard cap on live agents of the class (consists for trains).

near ​
ts
near: number;

Never spawn closer than this (metres).

perLaneKm ​
ts
perLaneKm: number;

Target agents per kilometre of lane within far.


AmbientConsist ​

How a train led by a rail type makes up: units copies of the lead type (multiple-unit locomotives), then length cars drawn in blocks of block alike from cars.

Properties ​

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

Cars of one type in a row, inclusive range (default [1, 1]).

cars ​
ts
cars: AmbientConsistCar[];
length ​
ts
length: [number, number];

Cars after the units, inclusive range.

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

Lead units, inclusive range (default [1, 1]).


AmbientConsistCar ​

A car a AmbientConsist draws from.

Properties ​

colors? ​
ts
optional colors?: string[];
height? ​
ts
optional height?: number;
id ​
ts
id: string;

Content type id.

length ​
ts
length: number;
weight? ​
ts
optional weight?: number;

Relative draw weight (default 1).

width ​
ts
width: number;

AmbientHandle ​

Properties ​

network ​
ts
readonly network: TransportNetwork;
world ​
ts
readonly world: World;

Methods ​

addDocument() ​
ts
addDocument(doc): void;
Parameters ​
doc ​

TransportNetworkDocument

Returns ​

void

addPolyline() ​
ts
addPolyline(line): void;
Parameters ​
line ​

AmbientPolyline

Returns ​

void

agentsNear() ​
ts
agentsNear(
   x, 
   z, 
   radius, 
   kind?
): string[];
Parameters ​
x ​

number

z ​

number

radius ​

number

kind? ​

AmbientKind

Returns ​

string[]

blocks() ​
ts
blocks(box, except?): boolean;

Whether an ambient car overlaps a box (for a host vehicle solver's canOccupy).

Parameters ​
box ​

AmbientBox

except? ​

string

Returns ​

boolean

despawnAll() ​
ts
despawnAll(kind?): void;
Parameters ​
kind? ​

AmbientKind

Returns ​

void

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

void

flush() ​
ts
flush(): void;

Apply queued tile changes now (outside a tick).

Returns ​

void

laneAt() ​
ts
laneAt(
   x, 
   z, 
   opts?
): 
  | {
  distance: number;
  lane: string;
  s: number;
}
  | undefined;
Parameters ​
x ​

number

z ​

number

opts? ​
class? ​

TransportClass

radius? ​

number

Returns ​

| { distance: number; lane: string; s: number; } | undefined

laneSample() ​
ts
laneSample(lane, s): LaneSample | undefined;
Parameters ​
lane ​

string

s ​

number

Returns ​

LaneSample | undefined

policy() ​
ts
policy(): AmbientPolicy;
Returns ​

AmbientPolicy

registerTile() ​
ts
registerTile(tile): void;

Queue a streamed tile (applied at a coming tick, see registrationsPerTick, or by flush()).

Parameters ​
tile ​

AmbientTileInput

Returns ​

void

setBudget() ​
ts
setBudget(budget): void;

Host budget: caps and ring size (not recorded; hosts reapply after a restore).

Parameters ​
budget ​

AmbientBudget

Returns ​

void

setObserver() ​
ts
setObserver(observer): void;
Parameters ​
observer ​

| { forward?: readonly [number, number]; pos: readonly [number, number, number]; } | { entity: string; } | null

Returns ​

void

setPolicy() ​
ts
setPolicy(policy): void;

Persistent policy overrides (recorded in world state).

Parameters ​
policy ​

DeepPartial&lt;AmbientPolicy&gt;

Returns ​

void

setSolids() ​
ts
setSolids(solids): void;

Extra solids cars yield to (e.g. the walking player).

Parameters ​
solids ​

readonly AmbientSolid[]

Returns ​

void

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

AmbientStats

unregisterTile() ​
ts
unregisterTile(key): void;
Parameters ​
key ​

string

Returns ​

void


AmbientObserverData ​

Extends ​

  • JsonObject

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

density? ​
ts
optional density?: number;
despawnRadius? ​
ts
optional despawnRadius?: number;
radius? ​
ts
optional radius?: number;

AmbientObserverState ​

Extends ​

  • JsonObject

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

entity? ​
ts
optional entity?: string;
forward? ​
ts
optional forward?: [number, number];
pos? ​
ts
optional pos?: [number, number, number];
setAtTick ​
ts
setAtTick: number;

AmbientOptions ​

Properties ​

carsAt? ​
ts
optional carsAt?: (x, z) => readonly AmbientVehicleType[];

Deterministic local road fleet at a prospective spawn point. An empty list suppresses it.

Parameters ​
x ​

number

z ​

number

Returns ​

readonly AmbientVehicleType[]

classes? ​
ts
optional classes?: readonly AmbientKind[];

Which classes run (default ['car']).

ground? ​
ts
optional ground?: (x, z) => number;

Ground height for documents, aircraft and tiles without their own sampler (default 0).

Parameters ​
x ​

number

z ​

number

Returns ​

number

policy? ​
ts
optional policy?: DeepPartial<AmbientPolicy>;

Policy overrides (rings, densities, caps, driver parameters).

registrationsPerTick? ​
ts
optional registrationsPerTick?: number;

Tile registrations a tick applies, in queue order (removals are not counted); default all. A dense tile's network takes tens of milliseconds to build, so a host streaming many tiles (or one tile in parts, see AmbientTileInput.bounds) passes 1 to keep each tick short.

removalsPerTick? ​
ts
optional removalsPerTick?: number;

Tile removals a tick applies, in queue order; default all. A tile streamed in parts leaves all at once, and removing every part (rebuilding the junctions they were stitched to) in one tick held it 10 ms.

seed? ​
ts
optional seed?: string | number;

Seed for spawn draws (default: 'ambient').

templates? ​
ts
optional templates?: Partial<Record<AmbientKind, AmbientTemplate | null>>;

Extra components per class; null spawns bare agents (ambientAgent + transform only).

traffic? ​
ts
optional traffic?: "right" | "left";

Which side of the road traffic keeps to (default 'right').

tunnels? ​
ts
optional tunnels?: "hidden" | "skip";

Tunnels: keep them with hidden agents (default) or drop them.

types? ​
ts
optional types?: Partial<AmbientTypes>;

Vehicle and pedestrian types per class (default: proxy dimensions).

yieldToDriven? ​
ts
optional yieldToDriven?: boolean;

Cars yield to vehicles someone is driving (mounted riders); default true.


AmbientPedestrianType ​

Properties ​

preset ​
ts
preset: "human.adult" | "human.elder" | "human.child";
weight? ​
ts
optional weight?: number;

AmbientPolicy ​

Properties ​

aircraft ​
ts
aircraft: AmbientClassPolicy;
boat ​
ts
boat: AmbientClassPolicy;
car ​
ts
car: AmbientClassPolicy;
deadlockSeconds ​
ts
deadlockSeconds: number;

Seconds after which a junction deadlock is broken.

driver ​
ts
driver: DriverParams;
forwardConeCos ​
ts
forwardConeCos: number;

Cosine of the half-angle of the view cone spawns avoid near the observer.

forwardConeReach ​
ts
forwardConeReach: number;

How far ahead (m) the view cone stays free of spawns; beyond it agents fade in.

marine ​
ts
marine: DriverParams;
pedestrian ​
ts
pedestrian: AmbientClassPolicy;
rail ​
ts
rail: DriverParams;
spawnBudget ​
ts
spawnBudget: number;

Spawns per spawner run, across classes.

spawnEveryTicks ​
ts
spawnEveryTicks: number;

Run the spawner every N ticks.

stuckSeconds ​
ts
stuckSeconds: number;

Seconds a stuck agent waits before it is removed (out of sight only).

train ​
ts
train: AmbientClassPolicy;

AmbientPolyline ​

A script-added polyline.

Properties ​

class ​
ts
class: "rail" | "road" | "water" | "path";
drivingSide? ​
ts
optional drivingSide?: "right" | "left";
lanes? ​
ts
optional lanes?: number;
layer? ​
ts
optional layer?: number;
oneway? ​
ts
optional oneway?: boolean;
points ​
ts
points: ([number, number] | [number, number, number])[];

[x, z] or [x, y, z] points in scene metres.

speed? ​
ts
optional speed?: number;
subclass? ​
ts
optional subclass?: string;
width? ​
ts
optional width?: number;

AmbientRoleConsist ​

AmbientRoleData.consist: car types by id, with draw weights and paints.

Extends ​

  • JsonObject

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

block? ​
ts
optional block?: [number, number];
cars ​
ts
cars: object[];
colors? ​
ts
optional colors?: string[];
type ​
ts
type: string;
weight? ​
ts
optional weight?: number;
length ​
ts
length: [number, number];
units? ​
ts
optional units?: [number, number];

AmbientRoleData ​

Extends ​

  • JsonObject

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

cars? ​
ts
optional cars?: number;
colors? ​
ts
optional colors?: string[];
consist? ​
ts
optional consist?: AmbientRoleConsist;

Rail: a mixed train this type leads. Car types come from the same library.

cruise? ​
ts
optional cruise?: number;
height? ​
ts
optional height?: number;
length? ​
ts
optional length?: number;
max? ​
ts
optional max?: number;
role ​
ts
role: "car" | "aircraft" | "boat" | "rail" | "bus" | "ferry";
track? ​
ts
optional track?: "light" | "heavy";

Rail: light (tram, light rail) or heavy track; absent runs on any.

visual? ​
ts
optional visual?: AmbientRoleVisual;
weight? ​
ts
optional weight?: number;
width? ​
ts
optional width?: number;

AmbientRoleVisual ​

Extends ​

  • JsonObject

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

frontWheelNodes? ​
ts
optional frontWheelNodes?: string[];
gearNodes? ​
ts
optional gearNodes?: string[];
paintMaterial? ​
ts
optional paintMaterial?: string;
rotors? ​
ts
optional rotors?: string[];
wheelbase? ​
ts
optional wheelbase?: number;
wheelNodes? ​
ts
optional wheelNodes?: string[];
wheelRadius? ​
ts
optional wheelRadius?: number;

AmbientSolid ​

A solid thing agents must not drive into (the player's car, a parked aircraft).

Properties ​

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

AmbientSpawnInfo ​

The details a template sees when an agent spawns.

Properties ​

color? ​
ts
optional color?: string;
id ​
ts
id: string;
kind ​
ts
kind: AmbientKind;
seed ​
ts
seed: number;
type ​
ts
type: string;

AmbientStateData ​

Extends ​

  • JsonObject

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

despawned ​
ts
despawned: number;
nextSeq ​
ts
nextSeq: number;
observer? ​
ts
optional observer?: AmbientObserverState;
policy? ​
ts
optional policy?: JsonObject;
spawned ​
ts
spawned: number;

AmbientStats ​

Properties ​

agents ​
ts
agents: Record<AmbientKind, number>;
despawned ​
ts
despawned: number;
network ​
ts
network: TransportNetworkStats;
pendingTiles ​
ts
pendingTiles: number;
spawned ​
ts
spawned: number;
waiting ​
ts
waiting: number;

AmbientTileInput ​

One streamed map tile's transport data.

Properties ​

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

Build only this world X/Z part of the tile, [minX, minZ, maxX, maxZ] (default: all of it). A large tile registered as parts, each under its own key, costs a tick a part instead of one long tick; edges stitch across part borders as across tile borders.

drivingSide? ​
ts
optional drivingSide?: "right" | "left";

Regional road driving side; defaults to the network's traffic setting.

features ​
ts
features: readonly TerrainTransportationFeature[];
heightAt? ​
ts
optional heightAt?: (x, z) => number;

Ground height at a world X/Z (default: the network's ground sampler).

Parameters ​
x ​

number

z ​

number

Returns ​

number

key ​
ts
key: string;

Unique tile key, e.g. terrainPyramidTileKey(address).

origin ​
ts
origin: readonly [number, number];

World X/Z of the tile's north-west corner, in metres.

pois? ​
ts
optional pois?: readonly TerrainPoiFeature[];
sidewalks? ​
ts
optional sidewalks?: boolean;

Infer sidewalks along streets without mapped footways (default true).

tileSize ​
ts
tileSize: number;

Tile edge length in metres; feature coordinates are normalized to it.


AmbientTypes ​

Properties ​

aircraft ​
ts
aircraft: AmbientVehicleType[];
boat ​
ts
boat: AmbientVehicleType[];
car ​
ts
car: AmbientVehicleType[];
pedestrian ​
ts
pedestrian: AmbientPedestrianType[];
train ​
ts
train: AmbientVehicleType[];

AmbientVehicleType ​

Properties ​

cars? ​
ts
optional cars?: number;

Rail: cars per consist (every car this type), unless consist makes the train up.

colors? ​
ts
optional colors?: string[];

Body colours to pick from (default: a realistic car palette).

consist? ​
ts
optional consist?: AmbientConsist;

Rail: a mixed train led by this type (its units, then cars drawn from a pool).

cruise? ​
ts
optional cruise?: number;

Preferred cruise speed in m/s (default: the lane's design speed).

height? ​
ts
optional height?: number;
id ​
ts
id: string;

Content type id, or a proxy name.

length ​
ts
length: number;
max? ​
ts
optional max?: number;

Top speed in m/s.

track? ​
ts
optional track?: "light" | "heavy";

Rail: the tracks it runs on. light keeps to tram and light-rail lines, heavy to the rest; absent runs anywhere.

waterway? ​
ts
optional waterway?: "ferry" | "channel";

Vessels: ferry service or general navigation channel.

weight? ​
ts
optional weight?: number;

Relative spawn weight within the class (default 1).

width ​
ts
width: number;

DriverParams ​

Properties ​

accel ​
ts
accel: number;

Maximum acceleration (m/s²).

brake ​
ts
brake: number;

Comfortable braking (m/s²).

gap ​
ts
gap: number;

Minimum standstill gap (m).

headway ​
ts
headway: number;

Time headway (s).


EdgeDraft ​

A polyline awaiting the planar split, in world metres.

Properties ​

bridge ​
ts
bridge: boolean;
bridgeApproachProfile? ​
ts
optional bridgeApproachProfile?: object[];
anchor? ​
ts
optional anchor?: number;
elevation ​
ts
elevation: number;
flatness ​
ts
flatness: number;
ground? ​
ts
optional ground?: number;
point ​
ts
point: Point2;
bridgeConnections? ​
ts
optional bridgeConnections?: object[];
elevation ​
ts
elevation: number;
point ​
ts
point: Point2;
radius ​
ts
radius: number;
class ​
ts
class: TransportClass;
deckElevation? ​
ts
optional deckElevation?: number;
drivingSide? ​
ts
optional drivingSide?: "right" | "left";
heights? ​
ts
optional heights?: number[];

Absolute surface heights per point (documents); otherwise baked from the ground sampler.

kind ​
ts
kind: RoadKind;
lanes ​
ts
lanes: number;

Total lanes across both directions (road), ignored for other classes.

layer ​
ts
layer: number;
ts
link: boolean;
name? ​
ts
optional name?: string;
oneway ​
ts
oneway: boolean;
points ​
ts
points: Point2[];
speed? ​
ts
optional speed?: number;
tunnel ​
ts
tunnel: boolean;
width ​
ts
width: number;

EdgeSpan ​

Properties ​

d0 ​
ts
readonly d0: number;

Edge-path distances bounding the span.

d1 ​
ts
readonly d1: number;
edge ​
ts
readonly edge: string;
lanes ​
ts
readonly lanes: Readonly<Record<TransportClass, number>>;
ref ​
ts
readonly ref: TransportEdge;

The edge itself and its lanes of each class, as inserted: a spawner weighs every span within reach, and looking both up by id for each was most of a run's few milliseconds.

x ​
ts
readonly x: number;

Midpoint, for distance tests.

z ​
ts
readonly z: number;

FleetCatalog ​

Properties ​

description ​
ts
description: string;
fallback ​
ts
fallback: string;
format ​
ts
format: "molen/fleet-catalog@1";
id ​
ts
id: string;
profiles ​
ts
profiles: object[];
extends? ​
ts
optional extends?: string;
id ​
ts
id: string;
title ​
ts
title: string;
weights ​
ts
weights: Record<string, number>;
regions ​
ts
regions: Record<string, string>;
version ​
ts
version: number;

FleetLibrary ​

Properties ​

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

Methods ​

select() ​
ts
select(region?): FleetMix;

Stable bounded shortlist; never depends on camera motion, downloads or wall time.

Parameters ​
region? ​

string

Returns ​

FleetMix


FleetMix ​

Properties ​

profile ​
ts
profile: string;
weights ​
ts
weights: ReadonlyMap<string, number>;

JunctionArm ​

Properties ​

dx ​
ts
readonly dx: number;

Unit direction pointing away from the junction along the edge.

dz ​
ts
readonly dz: number;
edge ​
ts
readonly edge: string;
group ​
ts
group: number;

Signal phase group this arm belongs to.

kind ​
ts
readonly kind: RoadKind;
ts
readonly link: boolean;
node ​
ts
readonly node: string;
width ​
ts
readonly width: number;
yields? ​
ts
optional yields?: boolean;

A stop or yield sign on this arm: its traffic gives way.


LaneMovement ​

A way from the end of one lane onto the start of another, through a connector curve.

Properties ​

crosses? ​
ts
readonly optional crosses?: readonly number[];

Walk movements: the road arms (by index) whose carriageway this connector crosses.

junction? ​
ts
readonly optional junction?: string;

Junction whose core this movement crosses (absent at plain through nodes).

key ​
ts
readonly key: number;

Arm-pair key inArm * armCount + outArm within the junction.

length ​
ts
readonly length: number;
p0 ​
ts
readonly p0: readonly [number, number, number];

Connector: quadratic Bezier from the lane end, via a control point, to the next lane start.

p1 ​
ts
readonly p1: readonly [number, number, number];
p2 ​
ts
readonly p2: readonly [number, number, number];
to ​
ts
readonly to: string;
turn ​
ts
readonly turn: TurnKind;
weight ​
ts
readonly weight: number;

LaneSample ​

A lane-level sample: position, surface height and travel direction.

Properties ​

dx ​
ts
dx: number;

Unit horizontal travel direction.

dz ​
ts
dz: number;
grade ​
ts
grade: number;

Grade (rise per metre travelled).

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

LaneStop ​

Properties ​

d ​
ts
readonly d: number;

Edge-path distance of the stop (convert with laneCoordinate).

dwell? ​
ts
readonly optional dwell?: number;

Stations: dwell time in seconds (default: a seeded 20–40 s).

id ​
ts
readonly id: string;

Station/crossing id, used to remember a served stop.

kind ​
ts
readonly kind: "bus" | "ferry" | "crossing" | "station" | "level-crossing";

ObserverView ​

Properties ​

density ​
ts
density: number;

Density factor from the observer entity's ambientObserver.

fx? ​
ts
optional fx?: number;

Unit horizontal view direction, when known.

fz? ​
ts
optional fz?: number;
keep? ​
ts
optional keep?: number;

Car despawn radius from the observer entity's ambientObserver.

radius? ​
ts
optional radius?: number;

Car spawn radius from the observer entity's ambientObserver.

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

PlanarNode ​

Properties ​

class ​
ts
class: TransportClass;
layer ​
ts
layer: number;
x ​
ts
x: number;
z ​
ts
z: number;

PlanarPiece ​

Properties ​

draft ​
ts
draft: number;
from ​
ts
from: number;
heights? ​
ts
optional heights?: number[];

Absolute heights per point when the draft supplied them.

points ​
ts
points: Point2[];
to ​
ts
to: number;

PlanarResult ​

Properties ​

degraded ​
ts
degraded: boolean;

True when the comparison budget ran out and some crossings were not detected.

nodes ​
ts
nodes: PlanarNode[];
pieces ​
ts
pieces: PlanarPiece[];

SignalTiming ​

Properties ​

cycleTicks ​
ts
cycleTicks: number;
greenTicks ​
ts
greenTicks: number[];
offsetTicks ​
ts
offsetTicks: number;

TransportCrossing ​

A point where a mapped footway crossing or a railway crosses a road edge.

Properties ​

id ​
ts
readonly id: string;
kind ​
ts
readonly kind: "crossing" | "level-crossing";
other ​
ts
readonly other: string;

The crossing edge (walk crossing or rail) and the distance along it.

otherS ​
ts
readonly otherS: number;
road ​
ts
readonly road: string;
roadS ​
ts
readonly roadS: number;

Distance along the road edge's path.

tile ​
ts
readonly tile: string;

TransportEdge ​

A polyline between two nodes. Lanes run along it in either direction.

Properties ​

bridge ​
ts
readonly bridge: boolean;
class ​
ts
readonly class: TransportClass;
drivingSide ​
ts
readonly drivingSide: "right" | "left";

Regional road traffic rule, retained through junction rebuilds and export.

from ​
ts
readonly from: string;
id ​
ts
readonly id: string;
kind ​
ts
readonly kind: RoadKind;
lanes ​
ts
readonly lanes: string[];
layer ​
ts
readonly layer: number;
ts
readonly link: boolean;
name? ​
ts
readonly optional name?: string;

Source feature name, when mapped.

oneway ​
ts
readonly oneway: boolean;
path ​
ts
readonly path: TerrainLinePath;

World metres, [x, z] per vertex, with cumulative distances.

speed ​
ts
readonly speed: number;

Design speed in m/s before per-agent variation.

tile ​
ts
readonly tile: string;
to ​
ts
readonly to: string;
tunnel ​
ts
readonly tunnel: boolean;
width ​
ts
readonly width: number;
ys ​
ts
readonly ys: Float64Array;

Surface height per path vertex (same indexing as path.points).


TransportJunction ​

Properties ​

arms ​
ts
readonly arms: readonly JunctionArm[];
conflicts ​
ts
readonly conflicts: Uint8Array;

conflicts[a * n² + b] for arm-pair keys a and b.

control ​
ts
control: JunctionControl;
groups ​
ts
readonly groups: number;

Number of signal phase groups (≥ 2 when signalised).

id ​
ts
readonly id: string;
nodes ​
ts
readonly nodes: readonly string[];
radius ​
ts
readonly radius: number;

Core radius in metres (lanes are trimmed this far back).

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

TransportLane ​

A directed lane. s runs from 0 at the lane start to length at its end.

Properties ​

class ​
ts
readonly class: TransportClass;
dir ​
ts
readonly dir: -1 | 1;

1 travels the edge path forward (from → to), -1 backward.

edge ​
ts
readonly edge: string;
end ​
ts
readonly end: string;
id ​
ts
readonly id: string;
index ​
ts
readonly index: number;

0 = innermost (leftmost for right-hand one-way roads, rightmost for left-hand).

length ​
ts
length: number;
lift ​
ts
readonly lift: number;

Surface lift above the edge's baked heights (sidewalks sit on the kerb).

next ​
ts
next: LaneMovement[];

Outgoing movements at the lane end.

offset ​
ts
readonly offset: number;

Signed lateral offset from the centreline, positive to the right of travel.

start ​
ts
readonly start: string;

Node the lane starts from and ends at.

stops ​
ts
stops: LaneStop[];

Stop points along the lane: stations, stops, crossings.

trimEnd ​
ts
trimEnd: number;
trimStart ​
ts
trimStart: number;

Edge-path distance trimmed from the start and end (junction cores).

ys? ​
ts
readonly optional ys?: Float64Array<ArrayBufferLike>;

The surface under this lane at each edge path vertex (indexed like the edge's ys), sampled at the lane's own offset. A road draped over a hillside tilts across its width, and lanes at the centreline's height ran half a metre into its uphill side. Absent where the edge's heights were given rather than sampled; the lane then follows ys.


TransportNetworkAerodrome ​

Properties ​

at ​
ts
at: [number, number];
heading? ​
ts
optional heading?: number;

Runway heading in radians about +Y (0 = +Z).

id ​
ts
id: string;
length? ​
ts
optional length?: number;

Runway length in metres (default 2500).


TransportNetworkDocument ​

Properties ​

aerodromes? ​
ts
optional aerodromes?: TransportNetworkAerodrome[];
drivingSide? ​
ts
optional drivingSide?: "right" | "left";
format ​
ts
format: "molen/transport-network@1";
name? ​
ts
optional name?: string;
origin? ​
ts
optional origin?: 
  | {
  latitude: number;
  longitude: number;
}
  | {
  x: number;
  z: number;
};
sidewalks? ​
ts
optional sidewalks?: boolean;

Infer sidewalks (walk lanes) along streets without mapped paths (default false).

signals? ​
ts
optional signals?: TransportNetworkSignal[];
stations? ​
ts
optional stations?: TransportNetworkStation[];
ways ​
ts
ways: TransportNetworkWay[];

TransportNetworkOptions ​

Properties ​

classes? ​
ts
optional classes?: readonly TransportClass[];

Lane classes to build (default all); skipping unused classes makes tiles cheaper.

ground? ​
ts
optional ground?: (x, z) => number;

Ground height used when a tile or document gives none (default 0).

Parameters ​
x ​

number

z ​

number

Returns ​

number

traffic? ​
ts
optional traffic?: "right" | "left";
tunnels? ​
ts
optional tunnels?: "hidden" | "skip";

TransportNetworkSignal ​

Properties ​

at ​
ts
at: [number, number];
kind ​
ts
kind: "light" | "yield" | "stop";

TransportNetworkStation ​

Properties ​

at ​
ts
at: [number, number];
dwell? ​
ts
optional dwell?: number;
id ​
ts
id: string;
kind ​
ts
kind: "rail" | "bus" | "ferry";

TransportNetworkStats ​

Properties ​

degradedTiles ​
ts
degradedTiles: number;
edges ​
ts
edges: number;
junctions ​
ts
junctions: number;
laneKm ​
ts
laneKm: Record<TransportClass, number>;

Lane-kilometres per class.

lanes ​
ts
lanes: number;
nodes ​
ts
nodes: number;
signals ​
ts
signals: number;
tiles ​
ts
tiles: number;

TransportNetworkWay ​

Properties ​

bridge? ​
ts
optional bridge?: boolean;
class ​
ts
class: "rail" | "road" | "air" | "water" | "path";
drivingSide? ​
ts
optional drivingSide?: "right" | "left";

Overrides the document's road driving side.

id? ​
ts
optional id?: string;
lanes? ​
ts
optional lanes?: number;
layer? ​
ts
optional layer?: number;
name? ​
ts
optional name?: string;
oneway? ​
ts
optional oneway?: boolean;
points ​
ts
points: TransportNetworkPoint[];
speed? ​
ts
optional speed?: number;
subclass? ​
ts
optional subclass?: string;
tunnel? ​
ts
optional tunnel?: boolean;
width? ​
ts
optional width?: number;

TransportNode ​

An endpoint or split point shared by edges.

Properties ​

border ​
ts
readonly border: boolean;

True when the node lies on its tile's boundary (a stitching candidate).

class ​
ts
readonly class: TransportClass;
edges ​
ts
readonly edges: string[];

Incident edge ids (both directions).

id ​
ts
readonly id: string;
layer ​
ts
readonly layer: number;
ts
optional link?: string;

The node in a neighbouring tile this border node is stitched to, if any.

tile ​
ts
readonly tile: string;

Owning tile key ('*' for documents and polylines).

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

TransportRunway ​

A mapped runway, kept for aircraft approach corridors.

Properties ​

ax ​
ts
readonly ax: number;
az ​
ts
readonly az: number;
bx ​
ts
readonly bx: number;
bz ​
ts
readonly bz: number;
tile ​
ts
readonly tile: string;
y ​
ts
readonly y: number;

WildlifeAgent ​

Properties ​

anchor ​
ts
anchor: [number, number];
decisions ​
ts
decisions: number;
heading ​
ts
heading: number;
id ​
ts
id: string;
nextDecision ​
ts
nextDecision: number;
phase ​
ts
phase: number;
position ​
ts
position: [number, number, number];
seed ​
ts
seed: number;
since ​
ts
since: number;
species ​
ts
species: string;
speed ​
ts
speed: number;
target ​
ts
target: [number, number];

WildlifeBudget ​

Properties ​

animals ​
ts
animals: number;
density ​
ts
density: number;

0..1 stable thinning. Changing quality keeps existing candidate identities.

radius ​
ts
radius: number;

WildlifeChoice ​

Already selected by the host's regional/range resolver. Density is a visual population prior.

Properties ​

density ​
ts
density: number;
habitats ​
ts
habitats: readonly string[];
species ​
ts
species: WildlifeSpecies;

WildlifeHabitat ​

Properties ​

height ​
ts
height: number;
kind ​
ts
kind: string;

Actual mapped surface, not potential vegetation from a biome map.

overflight? ​
ts
optional overflight?: boolean;

True where a road is all that makes the point unsafe: known, level habitat clear of buildings. Nothing spawns or stands there, but an animal in flight may pass over it. Never true where safe is; a host that cannot tell a road from a building omits it.

safe ​
ts
safe: boolean;

False on roads, buildings, steep terrain, or insufficiently known terrain.

water ​
ts
water: boolean;

WildlifeSpecies ​

Properties ​

body ​
ts
body: object;
accent ​
ts
accent: string;
color ​
ts
color: string;
details ​
ts
details: (
  | "antlers"
  | "palmate"
  | "horns"
  | "straight-horns"
  | "mane"
  | "long-neck"
  | "bushy-tail"
  | "stripes"
  | "spots"
  | "wader"
  | "waterfowl"
  | "raptor"
  | "parrot"
  | "long-tail")[];
family ​
ts
family: 
  | "hopper"
  | "ungulate"
  | "canid"
  | "feline"
  | "rodent"
  | "lagomorph"
  | "elephant"
  | "bird"
  | "reptile"
  | "fish"
  | "insect";
height ​
ts
height: number;
length ​
ts
length: number;
width ​
ts
width: number;
clearance ​
ts
clearance: number;

Height above ground/water for flight; depth below the surface for swimming.

id ​
ts
id: string;
inactiveInWinter? ​
ts
optional inactiveInWinter?: boolean;
margin ​
ts
margin: number;

Body-size clearance from obstacles, meters.

motion ​
ts
motion: WildlifeMotion;
range? ​
ts
optional range?: string;

Identifier in an attributed range document. Named taxa require a range at the Earth binding.

rest ​
ts
rest: number;

Probability of resting at a target. Flying/swimming animals keep moving.

roam ​
ts
roam: number;

Maximum travel from the stable spawn anchor in meters.

speed ​
ts
speed: number;

Meters per second. This is ambient travel, not maximum running speed.

taxon? ​
ts
optional taxon?: string;

Omitted for functional habitat groups that make no precise species claim.

title ​
ts
title: string;
version ​
ts
version: number;
winterColor? ​
ts
optional winterColor?: string;

Coarse seasonal appearance/activity; not a weather or migration model.


WildlifeWorld ​

Methods ​

choices() ​
ts
choices(x, z): readonly WildlifeChoice[];
Parameters ​
x ​

number

z ​

number

Returns ​

readonly WildlifeChoice[]

habitat() ​
ts
habitat(
   x, 
   z, 
   margin
): WildlifeHabitat | undefined;
Parameters ​
x ​

number

z ​

number

margin ​

number

Returns ​

WildlifeHabitat | undefined


WorldPoi ​

POIs in world metres, filtered to the kinds agents care about.

Properties ​

allWay? ​
ts
optional allWay?: boolean;
dwell? ​
ts
optional dwell?: number;

Stations: dwell time in seconds.

kind ​
ts
kind: 
  | "crossing"
  | "station"
  | "ferry_terminal"
  | "tram_stop"
  | "bus_stop"
  | "traffic_signals"
  | "give_way"
  | "aerodrome";
layer? ​
ts
optional layer?: number;
name? ​
ts
optional name?: string;
x ​
ts
x: number;
z ​
ts
z: number;

Type Aliases ​

AmbientKind ​

ts
type AmbientKind = "car" | "pedestrian" | "train" | "aircraft" | "boat";

An ambient NPC class.


AmbientTemplate ​

ts
type AmbientTemplate = (agent) => ComponentMap;

Extra components for a spawned agent (beyond ambientAgent and transform).

Parameters ​

agent ​

AmbientSpawnInfo

Returns ​

ComponentMap


DeepPartial ​

ts
type DeepPartial<T> = { [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K] };

Type Parameters ​

T ​

T


JunctionControl ​

ts
type JunctionControl = "none" | "yield" | "signal";

RoadKind ​

ts
type RoadKind = 
  | "motorway"
  | "trunk"
  | "primary"
  | "secondary"
  | "tertiary"
  | "street"
  | "living"
  | "service"
  | "path"
  | "crossing"
  | "rail"
  | "tram"
  | "channel"
  | "ferry";

Finer classification used for speeds, spawn preferences and routing weights.


SignalColor ​

ts
type SignalColor = "green" | "amber" | "red";

TransportClass ​

ts
type TransportClass = "road" | "rail" | "walk" | "air" | "water";

Which agents a lane serves.


TransportNetworkPoint ​

ts
type TransportNetworkPoint = [number, number] | [number, number, number];

A way's point: [x, z] or [x, y, z] in scene metres.


TurnKind ​

ts
type TurnKind = "straight" | "left" | "right" | "uturn" | "merge";

WildlifeFamily ​

ts
type WildlifeFamily = typeof WILDLIFE_FAMILIES[number];

WildlifeMotion ​

ts
type WildlifeMotion = "walk" | "hop" | "fly" | "swim" | "crawl";

Variables ​

AMBIENT_AGENT_COMPONENT ​

ts
const AMBIENT_AGENT_COMPONENT: "ambientAgent";

AMBIENT_ENTITY ​

ts
const AMBIENT_ENTITY: "$ambient";

The singleton entity holding ambient bookkeeping.


AMBIENT_KINDS ​

ts
const AMBIENT_KINDS: readonly AmbientKind[];

AMBIENT_OBSERVER_COMPONENT ​

ts
const AMBIENT_OBSERVER_COMPONENT: "ambientObserver";

AMBIENT_ROLE_COMPONENT ​

ts
const AMBIENT_ROLE_COMPONENT: "ambientRole";

AMBIENT_STATE_COMPONENT ​

ts
const AMBIENT_STATE_COMPONENT: "ambientState";

AmbientAgent ​

ts
const AmbientAgent: ComponentType<AmbientAgentData>;

AmbientObserver ​

ts
const AmbientObserver: ComponentType<AmbientObserverData>;

AmbientRole ​

ts
const AmbientRole: ComponentType<AmbientRoleData>;

AmbientState ​

ts
const AmbientState: ComponentType<AmbientStateData>;

CAR_COLORS ​

ts
const CAR_COLORS: readonly string[];

Common real-world car body colours, weighted by repetition.


DEFAULT_POLICY ​

ts
const DEFAULT_POLICY: AmbientPolicy;

DEFAULT_TEMPLATES ​

ts
const DEFAULT_TEMPLATES: Readonly<Record<AmbientKind, AmbientTemplate>>;

Built-in templates: vehicles render through ambient-vehicle, pedestrians as figures.


DEFAULT_TYPES ​

ts
const DEFAULT_TYPES: AmbientTypes;

fleetCatalogSchema ​

ts
const fleetCatalogSchema: z.ZodType<FleetCatalog>;

GRID_CELL ​

ts
const GRID_CELL: 64 = 64;

KIND_SPEED ​

ts
const KIND_SPEED: Readonly<Record<RoadKind, number>>;

Design speeds in m/s by kind.


TRANSPORT_NETWORK_EXAMPLE ​

ts
const TRANSPORT_NETWORK_EXAMPLE: TransportNetworkDocument;

TRANSPORT_NETWORK_FORMAT ​

ts
const TRANSPORT_NETWORK_FORMAT: "molen/transport-network@1";

WILDLIFE_CELL_METERS ​

ts
const WILDLIFE_CELL_METERS: 96 = 96;

WILDLIFE_FAMILIES ​

ts
const WILDLIFE_FAMILIES: readonly ["ungulate", "canid", "feline", "rodent", "lagomorph", "hopper", "elephant", "bird", "reptile", "fish", "insect"];

WILDLIFE_TICK_RATE ​

ts
const WILDLIFE_TICK_RATE: 20 = 20;

wildlifeSpeciesSchema ​

ts
const wildlifeSpeciesSchema: z.ZodType<WildlifeSpecies>;

Functions ​

agentRotation() ​

ts
function agentRotation(sample, pitch): Quat;

Rotation for an agent facing along a sample (with pitch unless flat).

Parameters ​

sample ​

LaneSample

pitch ​

boolean

Returns ​

Quat


agentSample() ​

ts
function agentSample(
   net, 
   agent, 
   out
): LaneSample | undefined;

Where an agent is: its lane body, or the connector curve into its lane.

Parameters ​

net ​

TransportNetwork

agent ​

Readonly&lt;AmbientAgentData&gt;

out ​

LaneSample

Returns ​

LaneSample | undefined


allRed() ​

ts
function allRed(
   junction, 
   tick, 
   tickRate, 
   timing?
): boolean;

Whether every group is red at tick (the all-red clearance interval).

Parameters ​

junction ​

TransportJunction

tick ​

number

tickRate ​

number

timing? ​

SignalTiming

Returns ​

boolean


ambientCapability() ​

ts
function ambientCapability(opts?): (world, manifest) => Record<string, object> | undefined;

Build-world capability hook: buildWorld(scene, setup, { capabilities: [ambientCapability()] }).

Parameters ​

opts? ​

AmbientCapabilityOptions

Returns ​

(world, manifest) => Record&lt;string, object&gt; | undefined


ambientOf() ​

ts
function ambientOf(world): AmbientHandle | undefined;

The ambient handle installed on a world, if any.

Parameters ​

world ​

World

Returns ​

AmbientHandle | undefined


ambientScriptApi() ​

ts
function ambientScriptApi(handle): object;

The script-api namespace for ambient life (molen.ambient.*); pass via buildWorld capabilities.

Parameters ​

handle ​

AmbientHandle

Returns ​

object


chooseNext() ​

ts
function chooseNext(
   lane, 
   seed, 
   hops
): string | undefined;

Pick the next lane at a lane's end (seeded by the agent and its hop count).

Parameters ​

lane ​

TransportLane

seed ​

number

hops ​

number

Returns ​

string | undefined


classifyFeature() ​

ts
function classifyFeature(feature): 
  | {
  class: TransportClass;
  kind: RoadKind;
}
  | "runway"
  | undefined;

Classify a mapped feature; undefined for features no agent uses.

Parameters ​

feature ​

TerrainTransportationFeature

Returns ​

| { class: TransportClass; kind: RoadKind; } | "runway" | undefined


clipPolyline() ​

ts
function clipPolyline(
   points, 
   minX, 
   minZ, 
   maxX, 
   maxZ
): Point2[][];

Clip a polyline to an axis-aligned rectangle, returning the visible pieces (a line that leaves and re-enters the tile yields several pieces).

Parameters ​

points ​

readonly Point2[]

minX ​

number

minZ ​

number

maxX ​

number

maxZ ​

number

Returns ​

Point2[][]


createFleetLibrary() ​

ts
function createFleetLibrary(
   documents, 
   available, 
   maxModels?
): FleetLibrary;

Parameters ​

documents ​

readonly FleetCatalog[]

available ​

ReadonlySet&lt;string&gt;

maxModels? ​

number

Returns ​

FleetLibrary


edgeHeight() ​

ts
function edgeHeight(edge, d): number;

Height of the edge surface at an edge-path distance.

Parameters ​

edge ​

TransportEdge

d ​

number

Returns ​

number


featureDrafts() ​

ts
function featureDrafts(input, options): TileDrafts;

Convert a tile's transportation features to clipped world-metre drafts.

Parameters ​

input ​

TileDraftInput

options ​

FeatureDraftOptions

Returns ​

TileDrafts


fmix32() ​

ts
function fmix32(x): number;

murmur3 finalizer: a full-avalanche 32-bit mix.

Parameters ​

x ​

number

Returns ​

number


idmAcceleration() ​

ts
function idmAcceleration(
   v, 
   v0, 
   gap, 
   dv, 
   p
): number;

IDM acceleration. gap is the bumper-to-bumper distance to the leader (Infinity when free), dv the closing speed (own speed minus the leader's).

Parameters ​

v ​

number

v0 ​

number

gap ​

number

dv ​

number

p ​

DriverParams

Returns ​

number


installAmbient() ​

ts
function installAmbient(world, options?): AmbientHandle;

Install the ambient systems (idempotent per world) and return the handle.

Parameters ​

world ​

World

options? ​

AmbientOptions

Returns ​

AmbientHandle


laneCoordinate() ​

ts
function laneCoordinate(
   lane, 
   edge, 
   d
): number;

Lane coordinate of edge-path distance d.

Parameters ​

lane ​

TransportLane

edge ​

TransportEdge

d ​

number

Returns ​

number


laneEdgeDistance() ​

ts
function laneEdgeDistance(
   lane, 
   edge, 
   s
): number;

Edge-path distance of lane coordinate s (clamped to the lane).

Parameters ​

lane ​

TransportLane

edge ​

TransportEdge

s ​

number

Returns ​

number


laneHeight() ​

ts
function laneHeight(
   lane, 
   edge, 
   d
): number;

Height of a lane's own surface at an edge-path distance (see TransportLane.ys).

Parameters ​

lane ​

TransportLane

edge ​

TransportEdge

d ​

number

Returns ​

number


laneSample() ​

ts
function laneSample(): LaneSample;

A fresh sample record.

Returns ​

LaneSample


mergePolicy() ​

ts
function mergePolicy(base, ...overrides): AmbientPolicy;

Merge overrides into a policy (plain objects merge; other values replace).

Parameters ​

base ​

AmbientPolicy

overrides ​

...( | JsonObject | DeepPartial&lt;AmbientPolicy&gt; | undefined)[]

Returns ​

AmbientPolicy


networkToDocument() ​

ts
function networkToDocument(
   network, 
   meta?, 
   options?
): TransportNetworkDocument;

Every road, rail and path edge as a way (with surface heights), plus stations and signals.

Parameters ​

network ​

TransportNetwork

meta? ​

Pick&lt;TransportNetworkDocument, "name" | "origin"&gt;

options? ​
heights? ​

boolean

Returns ​

TransportNetworkDocument


pickWeighted() ​

ts
function pickWeighted<T>(list, u): T | undefined;

Weighted pick from a list using a stateless draw.

Type Parameters ​

T ​

T extends object

Parameters ​

list ​

readonly T[]

u ​

number

Returns ​

T | undefined


planarSplit() ​

ts
function planarSplit(drafts, options?): PlanarResult;

Split drafts into pieces between nodes. Drafts only connect within their class.

Parameters ​

drafts ​

readonly EdgeDraft[]

options? ​

PlanarOptions

Returns ​

PlanarResult


policyForBudget() ​

ts
function policyForBudget(policy, budget): AmbientPolicy;

A policy with a host budget's caps and ring sizes applied.

Parameters ​

policy ​

AmbientPolicy

budget ​

AmbientBudget

Returns ​

AmbientPolicy


pseudoAngle() ​

ts
function pseudoAngle(dx, dz): number;

Monotone stand-in for atan2 in [0, 4): orders directions without transcendental math.

Parameters ​

dx ​

number

dz ​

number

Returns ​

number


registerAmbientSchema() ​

ts
function registerAmbientSchema(): void;

Register the ambient components, renderable kind and format (idempotent).

Returns ​

void


registerFleetSchema() ​

ts
function registerFleetSchema(): void;

Returns ​

void


sampleConnector() ​

ts
function sampleConnector(
   move, 
   t, 
   out
): LaneSample;

Point and tangent on a movement's connector at arc-length fraction t in [0, 1].

Parameters ​

move ​

LaneMovement

t ​

number

out ​

LaneSample

Returns ​

LaneSample


sampleLaneBody() ​

ts
function sampleLaneBody(
   lane, 
   edge, 
   s, 
   out
): LaneSample;

Sample a lane at s within [0, length], writing into out.

Parameters ​

lane ​

TransportLane

edge ​

TransportEdge

s ​

number

out ​

LaneSample

Returns ​

LaneSample


signalColor() ​

ts
function signalColor(
   junction, 
   group, 
   tick, 
   tickRate, 
   timing?
): SignalColor;

The colour shown to arms of phase group group at tick.

Parameters ​

junction ​

TransportJunction

group ​

number

tick ​

number

tickRate ​

number

timing? ​

SignalTiming

Returns ​

SignalColor


signalTiming() ​

ts
function signalTiming(junction, tickRate): SignalTiming;

Timing for a signalised junction: 18–30 s green per phase group, seeded by the junction id.

Parameters ​

junction ​

TransportJunction

tickRate ​

number

Returns ​

SignalTiming


stepAgents() ​

ts
function stepAgents(world, environment): void;

Advance every ambient agent one tick.

Parameters ​

world ​

World

environment ​

AgentEnv

Returns ​

void


stepWildlife() ​

ts
function stepWildlife(
   agents, 
   speciesById, 
   world, 
   tick
): WildlifeAgent[];

Advance one 1/20-second step. A host can snapshot these plain records without hidden state.

Parameters ​

agents ​

readonly WildlifeAgent[]

speciesById ​

ReadonlyMap&lt;string, WildlifeSpecies&gt;

world ​

WildlifeWorld

tick ​

number

Returns ​

WildlifeAgent[]


stoppingDistance() ​

ts
function stoppingDistance(v, b): number;

Distance needed to stop from speed v at deceleration b.

Parameters ​

v ​

number

b ​

number

Returns ​

number


unit01() ​

ts
function unit01(seed, stream): number;

Independent stateless draw in [0, 1) for a (seed, stream) pair.

Parameters ​

seed ​

number

stream ​

number

Returns ​

number


walkBack() ​

ts
function walkBack(
   net, 
   laneId, 
   s, 
   prev, 
   trail, 
   distance
): object;

Step back distance metres from a lane position along the lead's trail.

Parameters ​

net ​

TransportNetwork

laneId ​

string

s ​

number

prev ​

string | undefined

trail ​

readonly string[]

distance ​

number

Returns ​

object

lane ​
ts
lane: string;
prev? ​
ts
optional prev?: string;
s ​
ts
s: number;

wildlifeCandidates() ​

ts
function wildlifeCandidates(
   world, 
   observer, 
   budget, 
   tick?
): WildlifeAgent[];

Stable world-grid candidates, the nearest budget.animals of them. Adding an unrelated species does not reroll an existing one.

Cells are read nearest first and the read stops once the cap is full of animals nearer than any cell left: where animals are many (a town's gardens) a few cells fill it, and reading every cell within the radius cost the same however near the animals stood. The answer is the one a read of every cell gives.

Parameters ​

world ​

WildlifeWorld

observer ​

readonly [number, number, number]

budget ​

WildlifeBudget

tick? ​

number

Returns ​

WildlifeAgent[]

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