Skip to content

@bendyline/molen-ambient/client ​

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/client';

Classes ​

AmbientFigures ​

Constructors ​

Constructor ​
ts
new AmbientFigures(prepare?): AmbientFigures;
Parameters ​
prepare? ​

(object) => void | Promise<void>

Returns ​

AmbientFigures

Properties ​

group ​
ts
readonly group: Group;

Accessors ​

count ​
Get Signature ​
ts
get count(): number;
Returns ​

number

Methods ​

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

void

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

Partial<FigureBudget>

Returns ​

void

update() ​
ts
update(
   walkers, 
   camera, 
   tick, 
   tickRate
): void;

Update every walker for this frame.

Parameters ​
walkers ​

readonly WalkerView[]

camera ​

readonly [number, number, number]

tick ​

number

tickRate ​

number

Returns ​

void


ProxyBatches ​

Constructors ​

Constructor ​
ts
new ProxyBatches(prepare?, initialCapacity?): ProxyBatches;
Parameters ​
prepare? ​

(object) => void | Promise<void>

initialCapacity? ​

number

Returns ​

ProxyBatches

Properties ​

group ​
ts
readonly group: Group;

Accessors ​

meshCount ​
Get Signature ​
ts
get meshCount(): number;

Number of instanced meshes (draw calls when all are populated).

Returns ​

number

Methods ​

add() ​
ts
add(instance): void;
Parameters ​
instance ​

ProxyInstance

Returns ​

void

begin() ​
ts
begin(camera): void;

Start a frame: keep the anchor within a few hundred metres of the camera.

Parameters ​
camera ​

readonly [number, number, number]

Returns ​

void

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

void

end() ​
ts
end(): number;

Finish a frame: upload what changed and cull empty batches from drawing.

Returns ​

number


WildlifeRenderer ​

One opaque skinned draw per visible animal. Geometry is shared and released on disposal.

Constructors ​

Constructor ​
ts
new WildlifeRenderer(prepare?): WildlifeRenderer;

prepare builds an animal's shaders (a renderer's prepareObject). When it returns a promise, a new animal stays hidden until that settles: drawn at once, the first animal of a flight built its skinned program mid-frame, for well over 100 ms.

Parameters ​
prepare? ​

(object) => unknown

Returns ​

WildlifeRenderer

Properties ​

group ​
ts
readonly group: Group;

Accessors ​

count ​
Get Signature ​
ts
get count(): number;
Returns ​

number

triangles ​
Get Signature ​
ts
get triangles(): number;
Returns ​

number

Methods ​

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

void

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

Partial<WildlifeRenderBudget>

Returns ​

void

update() ​
ts
update(
   agents, 
   species, 
   camera, 
   seconds, 
   appearance?
): void;
Parameters ​
agents ​

readonly WildlifeAgent[]

species ​

ReadonlyMap<string, WildlifeSpecies>

camera ​

readonly [number, number, number]

seconds ​

number

appearance? ​

(agent, recipe) => WildlifeSpecies

Returns ​

void

Interfaces ​

AmbientAircraftModels ​

Methods ​

aircraft() ​
ts
aircraft(type): AircraftSpec | undefined;

The aircraft spec (rotor and gear bindings) of a type, if it is an aircraft type.

Parameters ​
type ​

string

Returns ​

AircraftSpec | undefined

load() ​
ts
load(type): Promise<Object3D<Object3DEventMap> | undefined>;
Parameters ​
type ​

string

Returns ​

Promise&lt;Object3D&lt;Object3DEventMap&gt; | undefined&gt;


AmbientRenderBudget ​

Properties ​

detailedBoats? ​
ts
optional detailedBoats?: number;

Full vessel models at most (default 4).

detailedCars ​
ts
detailedCars: number;

Cars drawn with their full model at most.

figureRadius ​
ts
figureRadius: number;

Pedestrians beyond this distance (m) are not drawn.

idleVehicleModels? ​
ts
optional idleVehicleModels?: number;

Idle detailed instances per pool (default 4); active instances have separate caps.

posesPerFrame ​
ts
posesPerFrame: number;

Pedestrian pose evaluations per frame.

skinnedFigures ​
ts
skinnedFigures: number;

Animated (skinned) pedestrians at most.

vehicleLoads? ​
ts
optional vehicleLoads?: number;

Concurrent detailed model loads per pool (default 2).

vehicleModelBytes? ​
ts
optional vehicleModelBytes?: number;

Estimated geometry/texture bytes per detail pool, including active and idle (default 32 MiB).


AmbientRenderer ​

Properties ​

object ​
ts
readonly object: Group;

Methods ​

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

void

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

Partial&lt;AmbientRenderBudget&gt;

Returns ​

void

setVisible() ​
ts
setVisible(visible): void;
Parameters ​
visible ​

boolean

Returns ​

void

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

AmbientRenderStats

update() ​
ts
update(camera, dt): void;

Draw the current world state; camera is the absolute camera position.

Parameters ​
camera ​

readonly [number, number, number]

dt ​

number

Returns ​

void


AmbientRendererOptions ​

Properties ​

admission? ​
ts
optional admission?: SceneAdmission;

Main-thread admission (e.g. renderer.admission) for building aircraft models.

aircraft? ​
ts
optional aircraft?: AmbientAircraftModels;

Aircraft models (absent: proxies only).

budget? ​
ts
optional budget?: Partial<AmbientRenderBudget>;
heights? ​
ts
optional heights?: Readonly<Record<string, number>>;

Body heights by type id, for proxies (the kernel stores length and width only).

parent ​
ts
parent: Object3D;

Parent in absolute world coordinates (e.g. the terrain stream object).

prepare? ​
ts
optional prepare?: (object) => void | Promise<void>;

Shader warm-up for new objects (e.g. renderer.prepareObject).

Parameters ​
object ​

Object3D

Returns ​

void | Promise&lt;void&gt;

railProfiles? ​
ts
optional railProfiles?: Readonly<Record<string, RailVehicleProfile>>;

Rail vehicle silhouettes by type id (spec.rail.profile), for train proxies.

riders? ​
ts
optional riders?: Readonly<Record<string, AmbientRider>>;

Car types ridden in the open, by type id: two-wheelers and auto-rickshaws, whose driver is drawn on the saddle (two-wheelers also lean into their turns and draw as two-wheelers).

vehicles? ​
ts
optional vehicles?: AmbientVehicleModels;

Full vehicle models for nearby cars (absent: proxies only).

world ​
ts
world: World;

AmbientRenderStats ​

Properties ​

aircraft ​
ts
aircraft: number;
boats ​
ts
boats: number;
cars ​
ts
cars: number;
detailedBoats ​
ts
detailedBoats: number;
detailedCars ​
ts
detailedCars: number;
drawBatches ​
ts
drawBatches: number;
figures ​
ts
figures: number;
pedestrians ​
ts
pedestrians: number;
proxies ​
ts
proxies: number;
trains ​
ts
trains: number;

AmbientRider ​

The driver drawn on a two- or three-wheeler in traffic.

Properties ​

seat ​
ts
seat: SeatData;

The driver seat: the pelvis position in model space.

vehicle ​
ts
vehicle: VehicleData;

The vehicle's data; spec.cycle or spec.handlebar places the hands and feet.


AmbientVehicleKindOptions ​

Properties ​

heights? ​
ts
optional heights?: Readonly<Record<string, number>>;

Body heights by type id (default: from the shape).


AmbientVehicleModels ​

Where full vehicle models come from (absent: every car stays a proxy).

Methods ​

load() ​
ts
load(type, signal?): Promise<Object3D<Object3DEventMap> | undefined>;

A fresh model instance for a type, or undefined when the type has no model.

Parameters ​
type ​

string

signal? ​

AbortSignal

Returns ​

Promise&lt;Object3D&lt;Object3DEventMap&gt; | undefined&gt;

vehicle() ​
ts
vehicle(type): VehicleData | undefined;

The vehicle data (wheel nodes, paint material, spec) of a type, if it is a vehicle type.

Parameters ​
type ​

string

Returns ​

VehicleData | undefined


DetailCandidate ​

Properties ​

color ​
ts
color: string;
distance ​
ts
distance: number;
id ​
ts
id: string;
type ​
ts
type: string;

FigureBudget ​

Properties ​

posesPerFrame ​
ts
posesPerFrame: number;

Pose evaluations per frame (nearest first, the rest round-robin).

radius ​
ts
radius: number;

Figures beyond this radius (m) are not drawn.

skinned ​
ts
skinned: number;

Skinned (animated) figures at most.


ProxyDimensions ​

Properties ​

height ​
ts
height: number;
length ​
ts
length: number;
width ​
ts
width: number;

ProxyInstance ​

Properties ​

color ​
ts
color: Color;
dims ​
ts
dims: ProxyDimensions;
pos ​
ts
pos: readonly [number, number, number];
rot ​
ts
rot: readonly [number, number, number, number];
scale ​
ts
scale: number;
shape ​
ts
shape: ProxyShape;

WalkerView ​

Properties ​

anchor? ​
ts
optional anchor?: "origin" | "eye" | "pelvis";

Which point of the body sits at pos: the feet (origin, default) or the eye (eye, the point a vehicle seat names).

figure ​
ts
figure: FigureData;
hidden ​
ts
hidden: boolean;
id ​
ts
id: string;
lookAt? ​
ts
optional lookAt?: readonly [number, number, number];

A world point the head turns toward (within the neck's reach).

mode? ​
ts
optional mode?: "idle" | "walk" | "run" | "sit";

The gait: idle or walk from speed by default, run for the running gait, sit for a seated pose (a passenger). Seated and eye-anchored walkers draw only at the animated detail tiers, since a rigid stand-in cannot sit.

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

World position of the walker's anchor point (its feet unless anchor says otherwise).

riding? ​
ts
optional riding?: object;

Saddle-relative cycle contact points, shared with the kernel pose evaluator.

ik ​
ts
ik: Partial<Record<FigureIkEffector, Vec3>>;
lean ​
ts
lean: number;
level? ​
ts
optional level?: number;

Roll of the vehicle with the ground across it, in radians (right side down positive), which an upright rider stands plumb against: on skis crossing a slope the body stays vertical while the feet follow the skis.

push? ​
ts
optional push?: number;
stance? ​
ts
optional stance?: "seated" | "standing" | "sideways";

Default seated. A standing or sideways rider stands on the idle pose instead of the seated one, the hips raised or lowered to this body's legs; a sideways rider turns across the board, left foot forward, and looks down it.

turn? ​
ts
optional turn?: number;
rot ​
ts
rot: readonly [number, number, number, number];
since ​
ts
since: number;

Tick the current motion began.

speed ​
ts
speed: number;

Planar speed, m/s.


WildlifeGeometry ​

Properties ​

geometry ​
ts
geometry: BufferGeometry;
joints ​
ts
joints: WildlifeJoint[];
triangles ​
ts
triangles: number;

WildlifeRenderBudget ​

Properties ​

animals ​
ts
animals: number;
posesPerFrame ​
ts
posesPerFrame: number;
radius ​
ts
radius: number;

Type Aliases ​

ProxyShape ​

ts
type ProxyShape = 
  | "car"
  | "two-wheeler"
  | "three-wheeler"
  | "bus"
  | "rail"
  | "aircraft"
  | "boat"
  | `rail-${RailVehicleProfile}`;

WildlifeTier ​

ts
type WildlifeTier = 0 | 1 | 2;

Functions ​

ambientVehicleKind() ​

ts
function ambientVehicleKind(options?): RenderableKind;

The ambient-vehicle renderable kind (proxy meshes) for Worker-hosted scenes.

Parameters ​

options? ​

AmbientVehicleKindOptions

Returns ​

RenderableKind


createAmbientRenderer() ​

ts
function createAmbientRenderer(options): AmbientRenderer;

Parameters ​

options ​

AmbientRendererOptions

Returns ​

AmbientRenderer


proxyGeometry() ​

ts
function proxyGeometry(shape, dims): BufferGeometry;

Cached geometry for a shape at given dimensions (rounded to 10 cm). Never dispose it.

Parameters ​

shape ​

ProxyShape

dims ​

ProxyDimensions

Returns ​

BufferGeometry


proxyHeight() ​

ts
function proxyHeight(
   shape, 
   length, 
   width, 
   type
): number;

Default body height for a proxy when the type gives none.

Parameters ​

shape ​

ProxyShape

length ​

number

width ​

number

type ​

string

Returns ​

number


proxyShapeFor() ​

ts
function proxyShapeFor(kind, length): ProxyShape;

The shape to draw for an agent kind and its dimensions.

Parameters ​

kind ​

string

length ​

number

Returns ​

ProxyShape


wildlifeGeometry() ​

ts
function wildlifeGeometry(species, tier): WildlifeGeometry;

+Z is the head/front. All geometry is baked in bind pose and skin weights are rigid.

Parameters ​

species ​

WildlifeSpecies

tier ​

WildlifeTier

Returns ​

WildlifeGeometry

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