Appearance
@bendyline/molen-kernel/vehicles
Molen headless deterministic simulation kernel (no DOM, no three.js).
ts
import { /* … */ } from '@bendyline/molen-kernel/vehicles';Classes
TrackNetwork
Host track network for track-guided vehicles. Positions are absolute metric X/Z; height comes from VehicleEnvironment.groundHeight as for any vehicle.
Implements
Constructors
Constructor
ts
new TrackNetwork(cell?): TrackNetwork;Parameters
cell?
number
Returns
Accessors
size
Get Signature
ts
get size(): number;Lines currently held.
Returns
number
Methods
advance()
ts
advance(
pose,
distance,
prefer
): TrackAdvance | undefined;Walk distance meters (≥ 0) along the track from pose in the direction of its yaw, taking route prefer at facing switches. Undefined when pose is not on a track.
Parameters
pose
distance
number
prefer
Returns
TrackAdvance | undefined
Implementation of
clear()
ts
clear(): void;Remove everything.
Returns
void
delete()
ts
delete(group): void;Remove a group's lines.
Parameters
group
string
Returns
void
has()
ts
has(group): boolean;Whether a group is held.
Parameters
group
string
Returns
boolean
nearest()
ts
nearest(
x,
z,
radius,
accept?
):
| {
distance: number;
pose: TrackNetworkPose;
tags: Readonly<Record<string, string>>;
}
| undefined;The nearest track point within radius of (x, z), optionally only on lines whose tags pass accept; the yaw runs along the line's point order.
Parameters
x
number
z
number
radius
number
accept?
(tags) => boolean
Returns
| { distance: number; pose: TrackNetworkPose; tags: Readonly<Record<string, string>>; } | undefined
set()
ts
set(group, lines): void;Replace a group's lines (an empty list removes the group).
Parameters
group
string
lines
readonly TrackLineInput[]
Returns
void
snap()
ts
snap(pose, radius?): TrackNetworkPose | undefined;The nearest point on a track within radius meters (default 4), keeping the travel sense of pose.yaw (the returned yaw is the track direction closest to it). Undefined off the rails.
Parameters
pose
radius?
number
Returns
TrackNetworkPose | undefined
Implementation of
tagsAt()
ts
tagsAt(pose): Readonly<Record<string, string>> | undefined;Tags of the line under a pose (e.g. a track name), if it is on one.
Parameters
pose
Returns
Readonly<Record<string, string>> | undefined
Interfaces
ConsistCar
A coupled car as the lead's step sees it.
Properties
id
ts
id: string;offset
ts
offset: number;spec
ts
spec: VehicleSpec;CoupledData
A car in a consist, CoupledData.offset meters behind its leader along the track.
Extends
Indexable
ts
[key: string]: JsonValue | undefinedProperties
leader
ts
leader: string;offset
ts
offset: number;MountableData
Extends
Indexable
ts
[key: string]: JsonValue | undefinedProperties
entries?
ts
optional entries?: [number, number, number][];exits
ts
exits: [number, number, number][];reach
ts
reach: number;seats
ts
seats: SeatData[];MountedData
Extends
Indexable
ts
[key: string]: JsonValue | undefinedProperties
seat
ts
seat: string;vehicle
ts
vehicle: string;PowertrainState
Gearbox and engine state carried between steps; every field is in vehicleState.
Properties
engineLoad
ts
engineLoad: number;gear
ts
gear: number;rpm
ts
rpm: number;shift
ts
shift: number;SeatData
Extends
Indexable
ts
[key: string]: JsonValue | undefinedProperties
id
ts
id: string;position
ts
position: [number, number, number];role
ts
role: "driver" | "passenger";TrackAdvance
Where TrackGuide.advance ended up.
Properties
diverged
ts
diverged: boolean;The route taken there was not the straightest.
junction
ts
junction: boolean;A facing switch with a choice of routes was passed on the way.
moved
ts
moved: number;Distance actually travelled: less than asked at the end of the track.
pose
ts
pose: TrackPose;TrackGuide
Host track network for track-guided vehicles. Positions are absolute metric X/Z; height comes from VehicleEnvironment.groundHeight as for any vehicle.
Properties
railTop?
ts
readonly optional railTop?: number;Height of the rail heads above the surface groundHeight reports on the track centreline (ballast between the rails, say), meters. Rail vehicle models stand on the rail heads. Default 0.
Methods
advance()
ts
advance(
pose,
distance,
prefer
): TrackAdvance | undefined;Walk distance meters (≥ 0) along the track from pose in the direction of its yaw, taking route prefer at facing switches. Undefined when pose is not on a track.
Parameters
pose
distance
number
prefer
Returns
TrackAdvance | undefined
snap()
ts
snap(pose, radius?): TrackPose | undefined;The nearest point on a track within radius meters (default 4), keeping the travel sense of pose.yaw (the returned yaw is the track direction closest to it). Undefined off the rails.
Parameters
pose
radius?
number
Returns
TrackPose | undefined
TrackLineInput
One track centreline handed to TrackNetwork.set.
Properties
points
ts
points: readonly readonly [number, number][];Points [x, z] in world meters, at least two.
rank?
ts
optional rank?: number;Detail rank; where copies of a track overlap the highest is followed. Default 0.
tags?
ts
optional tags?: Readonly<Record<string, string>>;Host data read back by TrackNetwork.nearest and TrackNetwork.tagsAt.
TrackNetworkPose
A pose on the network, with the line it is on (see TrackNetwork.advance).
Extends
Indexable
ts
[key: string]: JsonValue | undefinedProperties
ref?
ts
optional ref?: string;The guide's own reference to the track piece under the pose, handed back on the next call.
Overrides
x
ts
x: number;Inherited from
yaw
ts
yaw: number;Inherited from
z
ts
z: number;Inherited from
TrackPose
A point on a track and a direction along it, as a kernel yaw (0 faces +Z).
Extends
Extended by
Indexable
ts
[key: string]: JsonValue | undefinedProperties
ref?
ts
optional ref?: string;The guide's own reference to the track piece under the pose, handed back on the next call.
x
ts
x: number;yaw
ts
yaw: number;z
ts
z: number;VehicleEnvironment
Host collision adapter. All positions are absolute metric coordinates.
Properties
boostMode?
ts
optional boostMode?: boolean;Override the world's boost mode (pure step calls default to false).
time?
ts
optional time?: number;Simulation time in seconds at the start of the step; moves gusts. Default 0.
track?
ts
optional track?: TrackGuide;Track network for vehicles with spec.rail: they follow it (and their coupled cars follow them). Without one a rail vehicle drives straight with locked steering.
weather?
ts
optional weather?: WeatherData;Weather for wet or snowy grip and wind; installVehicles reads the world's weather.
Methods
canExit()?
ts
optional canExit(
position,
actor,
vehicle
): boolean;Parameters
position
[number, number, number]
actor
string
vehicle
string
Returns
boolean
canOccupy()?
ts
optional canOccupy(
position,
yaw,
spec,
entity
): boolean;Parameters
position
[number, number, number]
yaw
number
spec
VehicleSpec
entity
string
Returns
boolean
contacts()?
ts
optional contacts(probes, entity): readonly AircraftContact[];Optional detailed contacts for independent wheels and panels, in world coordinates.
Parameters
probes
readonly AircraftCollisionProbe[]
entity
string
Returns
readonly AircraftContact[]
groundHeight()
ts
groundHeight(
x,
z,
y?
): number | undefined;Surface under X/Z. y is the vehicle's height: stacked decks are told apart by it.
Parameters
x
number
z
number
y?
number
Returns
number | undefined
surface()?
ts
optional surface(
x,
z,
y?
): VehicleSurface | undefined;The surface under X/Z (at the vehicle's height y): grip, drag and roughness relative to dry pavement. Undefined, or no callback, is pavement. Asked once per step for a moving car.
Parameters
x
number
z
number
y?
number
Returns
VehicleSurface | undefined
VehicleInputData
Extends
Indexable
ts
[key: string]: JsonValue | undefinedProperties
actuators?
ts
optional actuators?: ActuatorInputs;brake
ts
brake: boolean;Service brakes on all wheels, anti-lock; holds the car at rest.
handbrake?
ts
optional handbrake?: boolean;Locks the rear wheels so they slide instead of rolling, for handbrake turns.
steering
ts
steering: number;throttle
ts
throttle: number;VehicleStateData
Extends
VehicleDamageState
Indexable
ts
[key: string]: JsonValue | undefinedProperties
actuators?
ts
optional actuators?: ActuatorPositions;assist?
ts
optional assist?: number;0–1: how hard traction or stability control is intervening.
bodyPitch?
ts
optional bodyPitch?: number;Suspension pitch on top of the terrain, nose down positive, and its rate.
bodyPitchRate?
ts
optional bodyPitchRate?: number;bodyRoll?
ts
optional bodyRoll?: number;Suspension roll on top of the terrain, right side down positive, and its rate.
bodyRollRate?
ts
optional bodyRollRate?: number;boosted?
ts
optional boosted?: boolean;Kernel-owned: horizontal speeds include the 4× travel boost.
damage?
ts
optional damage?: Record<string, AircraftPartDamage>;Inherited from
ts
VehicleDamageState.damagedebris?
ts
optional debris?: AircraftDebris[];Inherited from
ts
VehicleDamageState.debrisengineLoad?
ts
optional engineLoad?: number;With a powertrain: 0–1 share of the engine's torque being delivered.
gear?
ts
optional gear?: number;With a powertrain: the selected gear, -1 reverse and 1 upward the forward gears.
grounded
ts
grounded: boolean;kick?
ts
optional kick?: number;Push-powered cycles: 0 riding sideways to 1 turned forward to push off.
lateralSpeed?
ts
optional lateralSpeed?: number;Sideways speed in m/s, positive to the left: the slide.
pedalAngle?
ts
optional pedalAngle?: number;Bicycle crank angle; holds while coasting or braking. On a push-powered cycle, the phase of the current push.
pitch
ts
pitch: number;roll
ts
roll: number;rpm?
ts
optional rpm?: number;With a powertrain: engine speed in rev/min.
shift?
ts
optional shift?: number;With a powertrain: seconds until the gearbox may change gear again.
skid?
ts
optional skid?: number;0–1: how far the tires are past their grip (sliding, wheelspin or locked wheels).
snowDepth?
ts
optional snowDepth?: number;Meters of lying snow under the vehicle; absent on bare ground.
speed
ts
speed: number;steer
ts
steer: number;stuck?
ts
optional stuck?: boolean;Deep snow is holding the vehicle against its own drive.
surfaceGrip?
ts
optional surfaceGrip?: number;Grip of the surface under the wheels relative to dry pavement, when the host reports one.
track?
ts
optional track?: VehicleTrackState;Track-guided vehicles: the rails under it and the route chosen at the next switch.
vy
ts
vy: number;waitingForTerrain
ts
waitingForTerrain: boolean;wheelAngle
ts
wheelAngle: number;yaw
ts
yaw: number;yawRate?
ts
optional yawRate?: number;Yaw rate in rad/s, positive turning left.
VehicleSurface
What the wheels roll on, relative to dry pavement.
Properties
drag
ts
drag: number;Extra rolling resistance in m/s²: soft ground drags at the wheels.
grip
ts
grip: number;Tire friction as a share of the grip on dry pavement.
roughness
ts
roughness: number;0–1 unevenness: shakes the body on its springs as the car moves.
snow?
ts
optional snow?: number;Share of the weather's lying snow left on this surface: 1 on open ground (the default), less on a road that is ploughed and packed down by traffic.
VehicleTrackState
vehicleState.track: the rails under a track-guided vehicle.
Extends
Indexable
ts
[key: string]: JsonValue | undefinedProperties
ended?
ts
optional ended?: boolean;prefer
ts
prefer: TrackRoute;ref?
ts
optional ref?: string;The guide's reference for the track under the head (see TrackPose.ref).
trail
ts
trail: number[];Track centreline newest first, flat x, y, z triples about TRAIL_STEP apart.
Type Aliases
TrackRoute
ts
type TrackRoute = -1 | 0 | 1;Route at the next facing switch: -1 the left-hand route, 0 the straightest, 1 the right.
Variables
Coupled
ts
const Coupled: ComponentType<CoupledData>;IDLE_VEHICLE_INPUT
ts
const IDLE_VEHICLE_INPUT: VehicleInputData;Mountable
ts
const Mountable: ComponentType<MountableData>;Mounted
ts
const Mounted: ComponentType<MountedData>;TRAIL_STEP
ts
const TRAIL_STEP: 2 = 2;Spacing of trail samples, meters.
Vehicle
ts
const Vehicle: ComponentType<VehicleData>;VEHICLE_SURFACES
ts
const VEHICLE_SURFACES: Readonly<Record<string, VehicleSurface>>;Stock surfaces by the names map data uses for roads and land cover. Pavement is the baseline; loose and soft ground grips less, drags more and is rougher.
VehicleInput
ts
const VehicleInput: ComponentType<VehicleInputData>;VehicleState
ts
const VehicleState: ComponentType<VehicleStateData>;Functions
actuatorsSettled()
ts
function actuatorsSettled(
specs,
positions,
inputs
): boolean;Parameters
specs
ActuatorSpecs | undefined
positions
ActuatorPositions | undefined
inputs
ActuatorInputs | undefined
Returns
boolean
carOnTrail()
ts
function carOnTrail(
trail,
offset,
spec
): object;Pose of a car whose centre is offset meters back along the trail: its trucks ride the trail, and the body is the chord between them.
Parameters
trail
readonly number[]
offset
number
spec
VehicleSpec
Returns
object
pitch
ts
pitch: number;pos
ts
pos: [number, number, number];yaw
ts
yaw: number;consistOffsets()
ts
function consistOffsets(specs): number[];Offsets for a train made up front to back: each car's centre behind the first car's, from their coupled lengths.
Parameters
specs
readonly VehicleSpec[]
Returns
number[]
consistTrailLength()
ts
function consistTrailLength(spec, cars): number;Track a consist needs behind the lead's centre: to its last car's rear truck, plus margin.
Parameters
spec
VehicleSpec
cars
readonly ConsistCar[]
Returns
number
driveVehicle()
ts
function driveVehicle(
world,
actor,
input
): boolean;Parameters
world
actor
string
input
Returns
boolean
engineTorqueCurve()
ts
function engineTorqueCurve(curve, x): number;Engine torque at x (engine speed over the peak-power speed), relative to the torque at peak power. A naturally aspirated petrol engine peaks at half that speed; turbocharged and diesel engines hold a plateau low down; an electric motor holds its peak torque from rest up to that speed and constant power beyond it.
Parameters
curve
Curve
x
number
Returns
number
initialVehicleState()
ts
function initialVehicleState(yaw?): VehicleStateData;Parameters
yaw?
number
Returns
installMountedSeats()
ts
function installMountedSeats(world): void;Shared seat following, installed once by either vehicle capability.
Parameters
world
Returns
void
installVehicles()
ts
function installVehicles(world, environment?): void;Parameters
world
environment?
Returns
void
mountEntity()
ts
function mountEntity(
world,
actor,
vehicle,
seatId?
): boolean;Parameters
world
actor
string
vehicle
string
seatId?
string
Returns
boolean
powertrainWheelForce()
ts
function powertrainWheelForce(
powertrain,
wheelRadius,
speed,
gear
): number;Wheel force of each forward gear at full throttle, for tools that plot or check gearing.
Parameters
powertrain
VehiclePowertrainSpec
wheelRadius
number
speed
number
gear
number
Returns
number
railTrackState()
ts
function railTrackState(
pos,
yaw,
spec,
cars,
env,
prefer?
): VehicleTrackState | undefined;Snap a vehicle to the track and lay a trail behind it long enough for its consist, so its coupled cars can be placed. Returns undefined when there is no track under it.
Parameters
pos
readonly [number, number, number]
yaw
number
spec
VehicleSpec
cars
readonly ConsistCar[]
env
RailStepEnv
prefer?
Returns
VehicleTrackState | undefined
refreshRailHeights()
ts
function refreshRailHeights(
world,
leader,
env
): boolean;Read the rail heights under a consist again and stand its cars on them: map heights refine as finer terrain streams in, and a trail laid on coarse heights leaves cars floating or sunk. Returns whether anything moved.
Parameters
world
leader
string
env
Returns
boolean
repairVehicle()
ts
function repairVehicle(world, id): boolean;Repair a stopped road vehicle in place, restoring part geometry and clearing its debris.
Parameters
world
id
string
Returns
boolean
settleRailConsist()
ts
function settleRailConsist(
world,
leader,
env
): boolean;Put a track-guided leader and its coupled cars on the rails: snap the leader to the track under it, lay its trail and stand each car at its offset. Call after spawning a consist (or moving one); returns false when the environment has no track guide or no track is there.
Parameters
world
leader
string
env
Returns
boolean
snowDrag()
ts
function snowDrag(
depth,
wheelRadius,
tread?
): object;Rolling resistance of wheels of wheelRadius through lying snow depth meters deep, in m/s². packed is the drag of a firm snow surface, reached within a few centimeters. deep is the wheels ploughing and the floor dragging: it grows with the square of the depth against the wheel's size, about 3 m/s² where the snow reaches 60% of the wheel's radius, which is past what most cars can push through. tread (a spec's looseSurfaceGrip) wins back 40%.
Parameters
depth
number
wheelRadius
number
tread?
number
Returns
object
deep
ts
deep: number;packed
ts
packed: number;stepActuators()
ts
function stepActuators(
specs,
positions,
inputs,
dt
): ActuatorPositions;Pure snapshot-owned mechanics: no wall clock, renderer state or queued animation clips.
Parameters
specs
ActuatorSpecs
positions
ActuatorPositions | undefined
inputs
ActuatorInputs | undefined
dt
number
Returns
ActuatorPositions
stepPowertrain()
ts
function stepPowertrain(
powertrain,
wheelRadius,
state,
speed,
demand,
direction,
h,
mass?
): object;One substep of the engine and gearbox. speed is the signed road speed in m/s, demand the 0–1 accelerator and direction the way the driver wants to go (1 forward, -1 reverse). Returns the signed force at the driven wheels' contact patches: drive in the direction of the selected gear, less engine braking against the motion (and, given the vehicle's mass, less what it takes to spin the engine up with the car). An automatic picks the gear: it holds low gears to the rev limit under full throttle, short-shifts under a light foot, and kicks down when the pedal goes down.
Parameters
powertrain
VehiclePowertrainSpec
wheelRadius
number
state
speed
number
demand
number
direction
number
h
number
mass?
number
Returns
object
force
ts
force: number;ratio
ts
ratio: number;state
ts
state: PowertrainState;stepRailVehicle()
ts
function stepRailVehicle<S>(
t,
state,
input,
spec,
dt,
env,
cars?
): RailStepResult<S>;One step of a track-guided vehicle and its consist. Throttle drives forward from a stop or while rolling forward and brakes while rolling backward, and the reverse for negative throttle, so S brakes a moving train to a stand and then backs it. Steering picks the route at the next facing switch (held until the train passes one). The track's end stops the train.
Type Parameters
S
S extends RailStepState
Parameters
t
state
S
input
RailStepInput
spec
VehicleSpec
dt
number
env
RailStepEnv
cars?
readonly ConsistCar[]
Returns
RailStepResult<S>
stepVehicle()
ts
function stepVehicle(
t,
state,
input,
spec,
dt,
env,
id?
): object;One car, substepped at 120 Hz or finer: a dynamic bicycle model. Each axle's tires turn slip into side force up to the road's grip and then let go, sharing that grip with drive and brakes (a friction circle), so a car can understeer, oversteer, spin its wheels or slide; a handbrake locks the rear wheels. Braking and acceleration move weight between the axles, and a sprung body rolls and pitches on top of the four-wheel terrain support. Rain and snow lower the grip; wind, including gusts, pushes on the body. Collisions bounce and spin the car by an impulse at the corner that hit. At walking pace the model blends into pure rolling geometry, so a car never turns in place and parks exactly.
Parameters
t
state
input
spec
VehicleSpec
dt
number
env
id?
string
Returns
object
impact
ts
impact: number;impacts
ts
impacts: GlassCrashLoad[];state
ts
state: VehicleStateData;transform
ts
transform: TransformData;trailAt()
ts
function trailAt(trail, s): object;The trail point s meters back from its head, and the forward (toward the head) direction there. Past the tail it continues straight along the last segment.
Parameters
trail
readonly number[]
s
number
Returns
object
x
ts
x: number;y
ts
y: number;yaw
ts
yaw: number;z
ts
z: number;trailLength()
ts
function trailLength(trail): number;Total length of a trail, meters.
Parameters
trail
readonly number[]
Returns
number
unmountEntity()
ts
function unmountEntity(
world,
actor,
env
): boolean;Step actor out of whatever it is mounted in, at the first of the vehicle's exits with ground beside it that env.canExit accepts; the vehicle must be stopped (and an aircraft shut down). Any seat may leave: a passenger leaving does not touch the controls, while the driver leaving idles them (and shuts an aircraft's engine). Returns false when no exit works.
Parameters
world
actor
string
env
Returns
boolean
vehicleLocalPoint()
ts
function vehicleLocalPoint(t, point): [number, number, number];Parameters
t
point
[number, number, number]
Returns
[number, number, number]
vehicleMounts()
ts
function vehicleMounts(spec): MountableData;Parameters
spec
VehicleSpec
Returns
vehiclePartProbes()
ts
function vehiclePartProbes(
t,
spec,
state
): AircraftCollisionProbe[];Parameters
t
spec
VehicleSpec
state
VehicleDamageState & object
Returns
vehicleRotation()
ts
function vehicleRotation(
yaw,
pitch?,
roll?
): [number, number, number, number];Parameters
yaw
number
pitch?
number
roll?
number
Returns
[number, number, number, number]
vehicleSurface()
ts
function vehicleSurface(kind): VehicleSurface | undefined;The stock surface for a map surface name; undefined (pavement) for names it does not know.
Parameters
kind
string | undefined
Returns
VehicleSurface | undefined
weatherGrip()
ts
function weatherGrip(weather): number;Friction left on the road in the weather, as a share of dry grip: a road is wet (or covered) as soon as rain or snow falls, and heavier falls take more. Temperature never turns rain to ice.
Parameters
weather
WeatherData | undefined
Returns
number