@gameable/world

Classes

WorldFormatError

A world record that cannot be read. The message is for a person: it says what is wrong and where.

Example

import { readWorld, WorldFormatError } from 'gameable/world';

try {
  readWorld({ version: 2, id: 'attic' });
} catch (error) {
  if (error instanceof WorldFormatError) console.log(error.message);
}

Extends

• Error

Constructors

Constructor

new WorldFormatError(path, message): WorldFormatError;

Parameters

Parameter	Type	Description
path	string	Where in the record.
message	string	What is wrong, in plain words.

Returns

WorldFormatError

Overrides

Error.constructor

Properties

path

readonly path: string;

Where in the record, for example things[2].placement.position.

Interfaces

Breaker

What breaks the things in pieces of one world and makes them whole again.

Methods

breakThing()

breakThing(
   thing, 
   kick?, 
   only?
): readonly number[];

Break a thing: the pieces named come off (all of them when none is named), each where it stands, moving as the thing moves, plus the kick. When only one piece would be left holding, it comes off too.

Parameters

Parameter	Type	Description
thing	number	The thing's place in the list, or a piece's (that piece alone comes off).
kick?	| { x: number; y: number; z: number; } | null	Metres a second added to every piece that comes off, or nothing.
only?	readonly number[]	The pieces' places in the list, to break those alone; left out, all of them.

Returns

readonly number[]

The places in the list of the pieces that came off now; empty when the thing is not in pieces or nothing more of it can come off. The array is reused by the next call.

isBroken()

isBroken(thing): boolean;

Whether anything has come off a thing.

Parameters

Parameter	Type	Description
thing	number	The thing's place in the list.

Returns

boolean

True until it is mended.

isOff()

isOff(piece): boolean;

Whether a piece has come off its thing.

Parameters

Parameter	Type	Description
piece	number	The piece's place in the list.

Returns

boolean

True while it is a body of its own.

mend()

mend(thing?): boolean;

Make a broken thing whole again (its host puts it back where the package had it).

Parameters

Parameter	Type	Description
thing?	number	The thing's place in the list, or a piece's; left out, every broken thing.

Returns

boolean

True when something was mended.

wholeOf()

wholeOf(index): number;

The thing a place in the list belongs to.

Parameters

Parameter	Type	Description
index	number	A thing in pieces, or one of its pieces.

Returns

number

The thing's place in the list, or -1 for anything else.

---

BreakerHost

Who makes what the breaker decides: the module, with the physics and the drawing; a test, with a record of what it was asked.

Methods

free()

free(
   piece, 
   pose, 
   asleep
): void;

Give a piece its own body, and its drawing its own place.

Parameters

Parameter	Type	Description
piece	number	The piece's place in the list.
pose	Float32Array	Where: position (3) and turn (4) of the middle of its box, then its velocity (3) and turning (3). Reused by the next call.
asleep	boolean	True when it should stay exactly there until something touches it.

Returns

void

hold()

hold(thing, pieces): void;

Make the thing's own body of these pieces alone (the ones that still hold together), or of all of it as loaded (null), or take it away (an empty list).

Parameters

Parameter	Type	Description
thing	number	The thing's place in the list.
pieces	readonly number[] | null	The pieces' places in the list, null for the thing whole.

Returns

void

join()

join(piece): void;

Take a piece's own body away and put its drawing back in the thing.

Parameters

Parameter	Type	Description
piece	number	The piece's place in the list.

Returns

void

read()

read(thing, out): void;

Where a thing's body is and how it moves, now: position (3), turn (4, xyzw), velocity (3) and turning (3, radians a second about the world's axes).

Parameters

Parameter	Type	Description
thing	number	The thing's place in the list.
out	Float32Array	Thirteen numbers to fill.

Returns

void

tell()

tell(
   kind, 
   thing, 
   off, 
   gone
): void;

Tell whoever listens.

Parameters

Parameter	Type	Description
kind	"broken" | "mended"	broken or mended.
thing	number	The thing's place in the list.
off	readonly number[]	For broken: the pieces that came off now.
gone	boolean	For broken: true when nothing of the thing holds together any more.

Returns

void

---

BreakerPiece

One piece as the breaker counts it.

Properties

centre

readonly centre: Triple;

The middle of its box in its thing's body frame: pieceCentre.

fixed

readonly fixed: boolean;

True for a piece that stays where it is (a pedestal).

index

readonly index: number;

Its place in the world's list.

---

BreakerThing

One thing in pieces as the breaker counts it.

Properties

index

readonly index: number;

Its place in the world's list.

pieces

readonly pieces: readonly BreakerPiece[];

Its pieces, in the order of its parts.

---

HullSource

What hullSetsOf reads of a file's scene.

Methods

traverse()

traverse(visit): void;

Parameters

Parameter	Type
visit	(node) => void

Returns

void

updateMatrixWorld()

updateMatrixWorld(force?): void;

Parameters

Parameter	Type
force?	boolean

Returns

void

---

LoadedWorld

A world that is in the engine.

Properties

backdrop

readonly backdrop: WorldLayerState | null;

The same for the world's backdrop; null for a world without one.

base

readonly base: string;

The address of the package's folder, with its trailing slash.

complete

readonly complete: Promise<void>;

Resolves when everything is in, the sounds included.

copies

readonly copies: "lite" | "full";

Which copy of each loose thing's model was taken: its lighter one or its full one.

light

readonly light: 
  | {
  ambient: readonly readonly [number, number, number][];
  suns: readonly DirectionalLight[];
}
  | null;

The place's light as live engine lights, or null when the package gives none: its suns and its surrounding light (nine red-green-blue terms, three's light-probe order). It is the shape the character bridge's lighting.set takes, so one line lights exported characters like the place.

list

readonly list: WorldList;

The list of things, kept up to date as loose things move.

places

readonly places: readonly WorldLayerState[];

The places of a world made of several, as they stand now, in the record's order: each one's id, whether it is waiting, loading or in, its points and its file's bytes, and when it was asked for and drawn. Empty for a world of one place.

placesBudget

readonly placesBudget: number;

The points a world made of several places holds at once at most; 0 for a world of one place.

placesIn

readonly placesIn: Promise<void>;

Resolves when every place is in (with a budget too small for all of them: when every place it has room for is in). At once for a world of one place.

plain

readonly plain: boolean;

True for a world with no place (kind: 'object'): a plain world of one colour, a level floor that is solid and takes the things' shadows, no horizon and no walls.

points

readonly points: object;

The loose things' points: how many things the package gives points for, how many points that is, and whether they are drawn inside the place's own object (inPlace: sorted with the place's points, WebGPU and a place made of points) or each as an object of its own (drawn over the place's points, wherever they stand).

inPlace

inPlace: boolean;

things

things: number;

total

total: number;

record

readonly record: WorldRecord;

The record as read.

sounds

readonly sounds: object;

The sounds, as they stand: whether the place's loop is playing, how many of the things' own sounds are in, and how many times one has been played on a knock.

impacts

impacts: number;

played

played: number;

room

room: boolean;

thingsIn

readonly thingsIn: Promise<void>;

Resolves when every loose thing is in: with the load itself, unless the load named thingsFirst (then when the last of the others has landed).

timings

readonly timings: Readonly<Record<string, number>>;

Milliseconds from the call to each part arriving: record, sky, collision, place, things, sounds.

---

MotionStep

What one step found for one thing.

Properties

hit

hit: number;

How hard it was knocked this step, 0 to 1; 0 when it was not.

moved

moved: boolean;

True when it is somewhere new since it was last reported.

---

MotionTracker

Follows the loose things of one world.

Methods

placed()

placed(index, now): void;

A thing was put somewhere by hand (the start, a reset, a move): forget its motion and keep it quiet while it settles.

Parameters

Parameter	Type	Description
index	number	The thing's place in the list.
now	number	Seconds on the simulation's clock.

Returns

void

step()

step(
   index, 
   pose, 
   offset, 
   dt, 
   now
): MotionStep;

Take one thing's pose after a physics step.

Parameters

Parameter	Type	Description
index	number	The thing's place in the list.
pose	ArrayLike<number>	Its position (x, y, z) and turn (x, y, z, w), read at offset.
offset	number	Where in pose the seven numbers start.
dt	number	The step, seconds.
now	number	Seconds on the simulation's clock.

Returns

MotionStep

What happened; the record is reused by the next call.

---

MotionTuning

The tuning of createMotionTracker; every field has a default.

Properties

fullSpeed?

readonly optional fullSpeed?: number;

The velocity change that sounds at full strength, m/s. Default 4.

hitSpeed?

readonly optional hitSpeed?: number;

A velocity change in one step smaller than this is no knock, m/s. Default 0.55.

moveDistance?

readonly optional moveDistance?: number;

A thing counts as somewhere new this far from where it was last reported, metres. Default 0.05.

moveEvery?

readonly optional moveEvery?: number;

While it keeps moving it is reported at most this often, seconds. Default 0.25.

moveTurn?

readonly optional moveTurn?: number;

Or turned this far, as 1 minus the dot of the two turns. Default 0.004 (about 10 degrees).

quiet?

readonly optional quiet?: number;

Seconds a thing keeps quiet after it sounded. Default 0.35.

recover?

readonly optional recover?: number;

Seconds over which a thing's last knock stops counting: until then only a knock twice as hard as the last one sounds, the bar falling back as the time runs. Default 2.

settle?

readonly optional settle?: number;

Seconds a thing keeps quiet after it was put somewhere (the start, a reset). Default 0.6.

---

PlaceSlot

One place as the budget sees it.

Properties

distance

readonly distance: number;

How far it is from the rider now (rankPlaces).

keep?

readonly optional keep?: boolean;

True for a place that is never let go (the one the rider started in is not, while near).

points

readonly points: number;

Points it holds (the copy that would be taken).

state

readonly state: "in" | "waiting" | "loading";

Not asked for, on its way, or drawn.

---

PlaceTransform

Where an object made from one of the place's files stands.

Properties

position

readonly position: Triple;

Metres.

quaternion

readonly quaternion: Quadruple;

The turn, xyzw.

scale

readonly scale: number;

One scale on every axis.

---

PlainWorld

A plain world in the engine.

Properties

colour

readonly colour: Color;

The world's colour, for the scene's background.

floor

readonly floor: Mesh;

The floor: a disc of the world's colour that takes shadows. Add it to the scene.

fog

readonly fog: Fog;

The fog of the world's colour. Set it as the scene's.

Methods

castFrom()

castFrom(sun, mapSize): void;

Have a sun cast the things' shadows on the floor: its shadow covers the things and a few metres round them.

Parameters

Parameter	Type	Description
sun	DirectionalLight	The package's sun.
mapSize	number	The shadow map's side in pixels (2048 on a desk, 1024 on a phone).

Returns

void

dispose()

dispose(): void;

Free the floor's geometry and material.

Returns

void

---

PlainWorldNumbers

The numbers of a plain world.

Properties

centre

readonly centre: readonly [number, number];

The middle of the floor (the walk limit's middle, else the origin).

colour

readonly colour: readonly [number, number, number];

Its colour, linear red, green, blue.

floorFrom

readonly floorFrom: number;

Where the floor starts to fade into the surround and where it is gone, metres from the eye.

floorRadius

readonly floorRadius: number;

How far the drawn floor reaches from the world's middle, metres: past where it is gone for a walker anywhere inside the walk limit.

floorTo

readonly floorTo: number;

fogFar

readonly fogFar: number;

fogNear

readonly fogNear: number;

Where the fog starts and where a thing has become the colour, metres from the eye.

height

readonly height: number;

The floor's height, metres.

shadowCentre

readonly shadowCentre: readonly [number, number, number];

What the sun's shadow must cover: the middle of the loose things' boxes and how far they reach from it, metres.

shadowReach

readonly shadowReach: number;

---

WorldAsset

One file of a world package as a manifest entry.

Properties

id

readonly id: string;

The asset id game code names it by.

src

readonly src: string;

The file's path inside the world's folder.

tags

readonly tags: readonly string[];

world, and world.<world id>.

type

readonly type: "splat" | "gltf" | "audio";

What the engine loads it as.

---

WorldBody

How a thing takes part in the physics.

Properties

hull

readonly hull: string | null;

The simple closed shape's file, when shape is hull.

hulls

readonly hulls: string | null;

The same thing as several closed shapes in one file, each mesh one shape, or null: where it is open (under a table, between a chair's legs) it stays open. The body is built from these when they are there, from hull when not.

kind

readonly kind: "none" | "dynamic" | "static";

dynamic moves, static is solid and never moves, none has no collision.

mass

readonly mass: number;

Kilograms.

material

readonly material: string;

What it is made of, in one word.

shape

readonly shape: "mesh" | "box" | "hull";

A box from size, the thing's simple closed shape (hull), or its own triangles.

---

WorldBox

A box along the world's axes.

Properties

max

readonly max: Triple;

The high corner.

min

readonly min: Triple;

The low corner.

---

WorldBridge

The bridge between a made world and game code.

Methods

dispose()

dispose(): void;

Stop telling the game about the world.

Returns

void

handle()

handle(command): void;

The thing commands' sink: pass it as createEngineAdapter({ thing: bridge.handle }).

Parameters

Parameter	Type	Description
command	ThingCmd	What the game asked of a thing.

Returns

void

---

WorldBridgeOptions

What createWorldBridge needs.

Properties

characters?

readonly optional characters?: WorldRiders;

Who sits a character on a thing when game code says things.getOn: the character bridge. Left out, the ride command is ignored.

events

readonly events: GameEvent[];

The queue of events for the game: the engine adapter's events.

world

readonly world: WorldService;

The world service: engine.get('world').

---

WorldControlRecord

A part the rider works: a lever, a pedal, a twist grip. Its joint follows what the rider asks of the vehicle, so the hand or the foot on it moves with it.

Properties

brake

readonly brake: number;

What the brake fully on adds.

joint

readonly joint: string;

The joint it moves.

steer

readonly steer: number;

What steering fully to the right adds to the joint's rest value (degrees for a hinge, metres for a slide).

throttle

readonly throttle: number;

What full throttle adds (backing up, the other way).

---

WorldFileTransform

What brings the place's own files (points, mesh, collision) to the package's metres with the floor at y = 0: multiply by scale, turn over when flipY (half a turn about x: up becomes up, forward stays in front), then lift by floorOffset metres.

Extended by

• WorldLayerTransform

Properties

flipY

readonly flipY: boolean;

The file's y points down.

floorOffset

readonly floorOffset: number;

Metres to lift, so the floor is at y = 0.

scale

readonly scale: number;

File units to metres.

---

WorldForms

The forms something comes in: either, or both. Nothing is forced to be points or a mesh.

Properties

mesh

readonly mesh: WorldMeshForm | null;

As a mesh, or null.

splat

readonly splat: WorldSplatForm | null;

As points, or null.

---

WorldJointRecord

One joint: where a part turns or slides against its parent.

Properties

at

readonly at: Triple;

A point on the axis, the thing's frame at rest.

axis

readonly axis: Triple;

The axis, of length 1. A positive value turns right-handed about it.

child

readonly child: string;

The part that moves, with everything that hangs from it.

id

readonly id: string;

The joint's id, unique in the thing.

kind

readonly kind: "hinge" | "slide" | "break";

A hinge turns about its axis (degrees); a slide moves along it (metres); a break does not move: it holds two pieces together until the thing is broken.

limits

readonly limits: readonly [number, number] | null;

The range in which nothing passes through anything else, or null for a joint that turns freely.

parent

readonly parent: string;

The part that holds still.

rest

readonly rest: number;

The value the files are drawn at.

---

WorldLabels

The labels of one world.

Properties

visible

visible: boolean;

Whether the labels and boxes are showing.

Methods

dispose()

dispose(): void;

Take the labels off the page and the boxes out of the scene.

Returns

void

update()

update(camera): void;

Put every label over its thing as the camera sees it now. Call once a frame while showing.

Parameters

Parameter	Type	Description
camera	Camera	The camera the scene is drawn with.

Returns

void

---

WorldLayer

A layer of a world made of several places: points in a file of their own, with where the file stands. The world's backdrop (its sky and far distance, always loaded, first) is one.

Extended by

• WorldPlaceLayer

Properties

bounds

readonly bounds: WorldBox | null;

The box of what the file holds, in the world's frame, or null.

fileTransform

readonly fileTransform: WorldLayerTransform;

What brings the file to the world's frame.

forms

readonly forms: object;

The layer as points.

splat

readonly splat: WorldLayerSplat;

---

WorldLayerSplat

One layer's points: the full file and its lighter copy, with what each holds.

Properties

bytes

readonly bytes: number | null;

Its size in bytes, when the package says.

file

readonly file: string;

The file, by its path inside the folder.

lite

readonly lite: string | null;

A lighter copy for phones, or null.

liteBytes

readonly liteBytes: number | null;

The lighter copy's size in bytes, when the package says.

litePoints

readonly litePoints: number | null;

How many points the lighter copy holds, when the package says.

points

readonly points: number | null;

How many points it holds, when the package says.

---

WorldLayerState

One layer of a world made of several places, as it stands now.

Properties

askedMs

askedMs: number | null;

Milliseconds from the load's start to its file being asked for, or null.

bytes

bytes: number;

The file's size in bytes: the record's, then the real one. 0 when the record does not say.

id

readonly id: string;

The place's id; backdrop for the world's backdrop.

inMs

inMs: number | null;

Milliseconds from the load's start to all of it being drawn, or null.

name

readonly name: string;

What a person calls it.

points

points: number;

Points of the copy taken: the record's count, then the file's own once it has arrived.

state

state: "in" | "waiting" | "loading";

Not asked for yet (or let go), on its way, or drawn.

---

WorldLayerTransform

What brings one layer's file (the backdrop, or one of several places) to the world's own frame: the place's WorldFileTransform, then a turn about up and a move.

p = position + Q * ((0, floorOffset, 0) + F(scale * p_file))

F is the half turn about x when flipY; Q is the whole turn (rotation) when the package gives one, else a turn of yaw degrees about y, the same way a thing's yaw turns it. With no position, yaw or rotation it is the place's own transform.

Extends

• WorldFileTransform

Properties

flipY

readonly flipY: boolean;

The file's y points down.

Inherited from

WorldFileTransform.flipY

floorOffset

readonly floorOffset: number;

Metres to lift, so the floor is at y = 0.

Inherited from

WorldFileTransform.floorOffset

position

readonly position: Triple;

Where the file's origin stands in the world, metres.

rotation

readonly rotation: Quadruple | null;

The whole turn, xyzw, when the package gives one (a place may lean a degree so its ground lies on its neighbour's); it then wins over yaw, as a thing's placement.rotation does.

scale

readonly scale: number;

File units to metres.

Inherited from

WorldFileTransform.scale

yaw

readonly yaw: number;

Degrees about y: the heading alone.

---

WorldLight

The place's light, read from its panorama by the maker.

Properties

ambient

readonly ambient: readonly number[] | null;

The surrounding light: the nine terms of a second-order light probe, each as red, green, blue (27 numbers, term by term), or null. The package writes nine numbers per colour; the reader turns them term by term.

sun

readonly sun: 
  | {
  colour: Triple;
  direction: Triple;
  strength: number;
}
  | null;

The strongest light: where it travels (not where it is), its colour and its strength.

---

WorldLoadOptions

What load is asked.

Properties

lite?

readonly optional lite?: boolean;

Take the place's lighter copy when it has one (a phone). Default false.

maxTextureSize?

readonly optional maxTextureSize?: number;

The largest side a thing's textures keep, in pixels; larger ones are made smaller once, on arrival. 0 (the default) keeps them as authored, up to the largest the graphics card takes (8192 on most): a larger one is made that size on arrival, and the console says so.

onProgress?

readonly optional onProgress?: (progress) => void;

Told as each part arrives.

Parameters

Parameter	Type
progress	WorldLoadProgress

Returns

void

placeColorSpace?

readonly optional placeColorSpace?: "linear" | "srgb";

What the place's colour bytes mean when it is points; srgb (the default) for a made place.

placeForm?

readonly optional placeForm?: "mesh" | "splat";

Draw the place in this form when the package has it, instead of the record's use.

placesBudget?

readonly optional placesBudget?: number;

For a world made of several places: the points held at once, its backdrop and its places together. Left out: DESK_PLACES_BUDGET, or PHONE_PLACES_BUDGET with lite. A place beyond it waits, and the farthest one in is let go when a nearer one needs its room; the backdrop and the place the rider starts in are held whatever it says.

roomVolume?

readonly optional roomVolume?: number;

How loud the place's loop plays, 0 to 1. Default 0.5.

shareModels?

readonly optional shareModels?: boolean;

Load each model file once for every thing made from it (shared.ts): each thing draws its own objects and materials, sharing the file's geometry and pictures. Default false: every thing loads its own copy, as always. A game that changes one thing's geometry or pictures in place leaves it off.

splatFreeThings?

readonly optional splatFreeThings?: boolean;

Mark every loose thing's model as holding no splat, so the splat layer's walk of the scene each frame does not look below it (splatFree.ts). A game that hangs a splat inside a loose thing's model must leave this off: the layer would no longer find it. Default false.

stillThings?

readonly optional stillThings?: boolean;

Keep still things out of the per-frame place update: a loose thing that moves only as its body does (no moving parts, no rider's seat, not a vehicle) has its holder placed only when the body moves, and its model's objects worked out once (still.ts). A game that moves an object inside such a model by hand must leave this off: the model would no longer show it. Default false.

thingCopies?

readonly optional thingCopies?: "lite" | "full";

Which copy of each loose thing to draw: lite, its lighter copy for games when the package has one, or full. Left out: the lighter copy, except in a world with no place (kind: 'object') on a desk (lite not set), where the thing is the whole picture and its full copy is taken, textures of 8192 a side and all.

thingsAfter?

readonly optional thingsAfter?: Promise<unknown>;

With thingsFirst: the other things start loading only once this resolves (the game's own first rider standing, say, so they never take the line from it). Left out: at once.

thingsAs?

readonly optional thingsAs?: WorldThingsForm;

Draw every loose thing in this form when the package has it for that thing: its model (mesh) or its points (splat). Left out, the form last asked of drawThingsAs, which starts as record: each thing's own use.

thingsFirst?

readonly optional thingsFirst?: readonly string[];

Things to have in before the world is playable, by id (a game's own player's vehicle, say: games load in order). The load then resolves once the place, its collision and these are in; every other loose thing comes after, each given its body and drawn as it lands (stage: 'thing' goes on being told), and thingsIn says when the last is in. Until a thing is in, the calls that take it do nothing and WorldService.isIn says false. Left out, or naming no thing of the package: every thing is in before playable, as always.

---

WorldLoadProgress

One step of a load.

Properties

done

readonly done: number;

For thing: how many things are in, and how many there are. For place in a world made of several: how many places are in, and how many there are.

ms

readonly ms: number;

Milliseconds since load was called.

place?

readonly optional place?: string;

For place in a world made of several: the id of the place that came (or went).

stage

readonly stage: 
  | "collision"
  | "sounds"
  | "backdrop"
  | "place"
  | "thing"
  | "record"
  | "sky"
  | "playable";

What just arrived. In a world made of several places backdrop is told once and place once for each place as it is drawn (and again when one is let go), before and after playable.

total

readonly total: number;

---

WorldMeshForm

A thing or a place as a mesh.

Properties

file

readonly file: string;

The file, by its path inside the folder.

lite

readonly lite: string | null;

A lighter copy for games, or null.

liteTextureSide

readonly liteTextureSide: number | null;

The same for the lighter copy (liteTextures), when the package says.

liteTriangles

readonly liteTriangles: number | null;

How many triangles the lighter copy holds, when the package says (liteTriangles).

textureSide

readonly textureSide: number | null;

The longest side, in pixels, of the full file's largest texture, when the package says (textures). A made model's colour texture may be 8192 a side or more: a desk's card takes it, a phone takes the lighter copy.

triangles

readonly triangles: number | null;

How many triangles the full file holds, when the package says.

---

WorldModuleOptions

Options for world.

Properties

motion?

readonly optional motion?: MotionTuning;

How a knock and a move are told from a thing's motion.

order?

readonly optional order?: number;

Where the module runs among the others; after physics. Default 10.

settle?

readonly optional settle?: boolean;

Let every loose thing drop and settle the moment the world loads. Off by default: a thing stays exactly where the package placed it, asleep, until something touches it.

---

WorldNotice

What the world tells whoever listens. The record is reused: read it, do not keep it.

Properties

joint

joint: number;

For joint: the joint's place in the thing's list of joints.

kind

kind: 
  | "joint"
  | "broken"
  | "mended"
  | "loaded"
  | "hit"
  | "moved"
  | "unloaded"
  | "held"
  | "freed";

loaded, hit (a loose thing was knocked), moved (a loose thing is somewhere new), unloaded, joint (a joint with limits of a thing with moving parts stands somewhere new), broken (pieces came off a thing in pieces), mended (it is whole again), held (a loose thing is held asleep where it is until the ground under it is in: isHeld) or freed (its ground is in and it goes on as it was going).

list

list: WorldList | null;

The world's list, for loaded.

pieces?

optional pieces?: readonly WorldThing[];

For broken: the pieces that came off; for mended: the ones that went back.

strength

strength: number;

For hit: how hard, 0 to 1. For joint: the joint's value. For broken: 1 when nothing of the thing holds together.

thing

thing: WorldThing | null;

The thing, for hit, moved, joint, broken and mended.

---

WorldPartRecord

One rigid part of a thing.

Properties

about

readonly about: string;

A few words about it; empty when the package says nothing.

box

readonly box: WorldBox | null;

Its own box, the thing's frame at rest, or null.

fixed

readonly fixed: boolean;

For a piece of a thing in pieces: true when it stays where it is as the others come off.

hull

readonly hull: string | null;

Its own simple closed shape's file, or null.

hulls

readonly hulls: string | null;

Its own shape as several closed shapes in one file (a table's legs, not the block round them), or null.

id

readonly id: string;

The part's id, unique in the thing.

impact

readonly impact: readonly string[];

The sounds it makes on its own when it hits something; empty to use the thing's.

joint

readonly joint: string | null;

The joint between it and its parent, or null for the root.

label

readonly label: string;

What a person calls it.

mass

readonly mass: number;

Kilograms.

node

readonly node: string;

The name of its node in the thing's model file.

parent

readonly parent: string | null;

The part it hangs from, or null for the root.

---

WorldPiece

One piece of a thing in pieces, by where it is in the record and in the list.

Properties

id

readonly id: string;

<thing id>.<part id>: what its files' asset ids are made from.

index

readonly index: number;

The piece's own place in the world's list: after the package's things, in their order.

part

readonly part: number;

The piece's place among the thing's parts.

thing

readonly thing: number;

The thing's place in the record's things (and in the list).

---

WorldPlace

The place: what you see, what stops you, where you start.

Properties

background

readonly background: Triple | null;

The colour of a world with no place, linear red, green, blue: its floor and everything all round. Null for a world that has a place.

bounds

readonly bounds: WorldBox | null;

The place's box, or null.

collision

readonly collision: WorldCollision;

What stops a body.

eyeHeight

readonly eyeHeight: number;

A standing person's eye height, metres.

fileTransform

readonly fileTransform: WorldFileTransform;

What brings the place's files to metres.

forms

readonly forms: WorldForms;

The place as points, as a mesh, or both; neither in a world with no place (kind: 'object').

light

readonly light: WorldLight | null;

The light, or null (things are then lit by the panorama).

panorama

readonly panorama: string | null;

The view all round from the origin (the sky and the far distance), or null.

picture

readonly picture: string | null;

The starting picture, or null.

spawn

readonly spawn: object;

Where the player starts, on the floor, and which way they face (degrees about y).

facing

readonly facing: number;

position

readonly position: Triple;

use

readonly use: "mesh" | "splat" | null;

Which form a game draws by default, or null in a world with no place.

walk

readonly walk: WorldWalkRecord;

How far the player may walk.

---

WorldPlaceLayer

One of a world's several places: a layer with a name and the ground it is the one to show on.

Extends

• WorldLayer

Properties

bounds

readonly bounds: WorldBox | null;

The box of what the file holds, in the world's frame, or null.

Inherited from

WorldLayer.bounds

fileTransform

readonly fileTransform: WorldLayerTransform;

What brings the file to the world's frame.

Inherited from

WorldLayer.fileTransform

forms

readonly forms: object;

The layer as points.

splat

readonly splat: WorldLayerSplat;

Inherited from

WorldLayer.forms

good

readonly good: readonly readonly readonly [number, number][][];

The ground this place is the one to show on: rings of corners, each [x, z], in the world's frame (the record's good.points, then each of good.more). Empty when the package gives none. The fade at its edges is in the file's own points; a game fades nothing.

id

readonly id: string;

The package's id for it, unique among the world's places.

name

readonly name: string;

What a person calls it.

priority

readonly priority: number;

Lower loads earlier among places equally far.

---

WorldRecord

A whole world package's record.

Properties

about

readonly about: string;

One or two plain sentences.

backdrop

readonly backdrop: WorldLayer | null;

The world's sky and far distance as points, always loaded and first; null when it has none.

id

readonly id: string;

The package's id.

kind

readonly kind: "object" | "room" | "open";

room: walls all round. open: a field, a street. object: no place at all, a thing standing by itself on a level floor in a plain world of one colour.

name

readonly name: string;

Its name, for a page.

place

readonly place: WorldPlace;

The place.

places

readonly places: readonly WorldPlaceLayer[];

The places of a world made of several, each a layer of points in the world's own frame; empty for a world of one place. The world's own facts (its collision, light, sky, start) are then in place, which has no points of its own.

room

readonly room: readonly string[];

Loops for the place.

routes

readonly routes: readonly WorldRoute[];

Lines through the world, in its own frame; empty when the package gives none.

things

readonly things: readonly WorldThingRecord[];

Every thing, loose or fixed.

version

readonly version: 1;

The format.

---

WorldRide

Where a rider meets a thing: an object at each of its rider spots, in the scene, moving with the part the spot is on (a grip turns with the handlebars). Each object's own +z is the way a character there faces, its +y up, its +x the character's left; a grip's +x runs along its bar. It is the shape the character bridge's seat takes, so one line sits a character on the thing: characters.seat(entity, world.rideOf(thing)).

Properties

feet

readonly feet: readonly [Object3D<Object3DEventMap> | null, Object3D<Object3DEventMap> | null];

The foot rests, left then right (the top of each); null for one the package does not name.

floor

readonly floor: Object3D;

The middle of the thing's base: what stands on the floor under the seat.

hands

readonly hands: readonly [Object3D<Object3DEventMap> | null, Object3D<Object3DEventMap> | null];

The grips, left then right; null for one the package does not name.

seat

readonly seat: Object3D;

The seat: the top of its surface.

spots

readonly spots: ReadonlyMap<string, Object3D<Object3DEventMap>>;

Every spot by its name in the package (seat, gripLeft, gripRight, footLeft, footRight).

Methods

refresh()

refresh(alpha): void;

Bring the thing's drawing, and so its spots, to where they stand this frame (the service's present); the character bridge calls it before it reads the objects.

Parameters

Parameter	Type	Description
alpha	number	The frame's interpolation factor between the last two fixed steps.

Returns

void

---

WorldRiders

Who can sit a character on a thing: the character bridge of gameable/host/characters is one (its seat).

Methods

seat()

seat(entity, ride): boolean;

Sit a character on a thing's spots, or stand it up again.

Parameters

Parameter	Type	Description
entity	number	The character's entity.
ride	WorldRide | null	The thing's spots, or null to get off.

Returns

boolean

False when the character cannot be seated.

---

WorldRiderSpot

A named place where a rider meets the thing.

Properties

along

readonly along: Triple | null;

The way a grip's bar runs outward, or null.

forward

readonly forward: Triple | null;

The way a seat or a foot rest faces, or null.

name

readonly name: string;

seat, gripLeft, gripRight, footLeft, footRight, or another name.

part

readonly part: string;

The part it is on: it moves with that part.

position

readonly position: Triple;

Where, the thing's frame at rest.

up

readonly up: Triple;

Up at the spot.

---

WorldRoute

A line through the world: a lap, a path.

Properties

id

readonly id: string;

The package's id for it.

name

readonly name: string;

What a person calls it.

points

readonly points: readonly readonly [number, number, number, number][];

Its points, in order: x, y, z in the world's frame, and the width there in metres.

surface

readonly surface: string;

What it runs on, in one word, or empty.

---

WorldService

What engine.get('world') returns.

Properties

current

readonly current: LoadedWorld | null;

The world in the engine now, or null.

labels

labels: boolean;

Each thing's name over it and its box round it; a page's switch.

lightGain

lightGain: number;

A multiplier on the light the package gives (its sun and its surrounding light). 1, the default, is the package's own numbers.

rideSpeed

rideSpeed: number;

The fastest a thing that drives goes, metres a second: past it the throttle is let go. 10 by default; a page sets it to suit the room a world has.

things

readonly things: readonly WorldThing[];

Every thing of the current world, loose or fixed; empty with none.

thingsAs

readonly thingsAs: WorldThingsForm;

The form the loose things are drawn in now (drawThingsAs changes it).

Methods

balance()

balance(thing, on): boolean;

Whether a thing that drives is held upright as a rider holds it (true, the default) or left to fall over and slide (nobody aboard: its rider was thrown off).

Parameters

Parameter	Type	Description
thing	WorldThing	The thing.
on	boolean	Held upright.

Returns

boolean

False for a thing that does not drive.

breakThing()

breakThing(thing, options?): readonly WorldThing[];

Break a thing in pieces (thing.pieces): each piece becomes a body of its own where it stands, with its own collision and weight, moving as the thing moved; a piece the package marks fixed stays an immovable body. Until then the thing is one body, drawn whole. reset makes it whole again. Tells broken.

Parameters

Parameter	Type	Description
thing	WorldThing	The thing, or one of its pieces (that piece alone comes off).
options?	{ kick?: PointLike; parts?: readonly string[]; }	parts: the ids of the pieces to break off, all of them when left out. kick: metres a second added to every piece that comes off.
options.kick?	PointLike	-
options.parts?	readonly string[]	-

Returns

readonly WorldThing[]

The pieces that came off; empty for a thing that is not in pieces.

collision()

collision(): CollisionPiecesState | null;

How the collision by piece stands: tiles and pieces in, pieces waiting, the longest build.

Returns

CollisionPiecesState | null

The numbers, or null in a world whose collision is one piece.

drawThingsAs()

drawThingsAs(form): Promise<void>;

Draw the loose things as their models, as their points, or each as the package says. A thing that lacks the form asked for keeps the one it has. The files a form needs are brought in the first time it is asked for; the choice holds for the worlds loaded after.

Parameters

Parameter	Type	Description
form	WorldThingsForm	mesh (models), splat (points) or record (each thing's own use).

Returns

Promise<void>

Resolves when every thing is drawn in the form.

drive()

drive(
   thing, 
   throttle, 
   right, 
   brake?
): boolean;

Drive a thing that can be driven: the rider's wish, held until the next call. The thing's wheels, arms and handlebars follow what the physics does.

Parameters

Parameter	Type	Description
thing	WorldThing	The thing.
throttle	number	From -1 (back) to 1 (forward).
right	number	Steering, from -1 (left) to 1 (right).
brake?	number	The brakes, from 0 to 1.

Returns

boolean

True when the thing drives.

find()

find(words): WorldThing | null;

The thing some words name ("the trunk"), or null.

Parameters

Parameter	Type	Description
words	string	What was said.

Returns

WorldThing | null

isHeld()

isHeld(thing): boolean;

Whether a loose thing is held asleep where it is because the ground under it is not in yet (a world made of several places brings its collision in by piece as things come near; a thing that gets ahead of it waits, with the speed it had, and never falls through). A game reads it to decide what a machine nobody steers does meanwhile; held and freed are told too.

Parameters

Parameter	Type	Description
thing	WorldThing	The thing.

Returns

boolean

True while it waits.

isIn()

isIn(thing): boolean;

Whether a loose thing is in: loaded, drawn and given its body. False for one still coming after the things a load named first (thingsFirst), or for a thing not of this world.

Parameters

Parameter	Type	Description
thing	WorldThing	The thing.

Returns

boolean

True once it is in.

jointOf()

jointOf(thing, joint): number;

Where a joint of a thing stands now.

Parameters

Parameter	Type	Description
thing	WorldThing	The thing.
joint	string | number	The joint's name or its place in the thing's list of joints.

Returns

number

Degrees for a hinge, metres for a slide; NaN when the thing has no such joint.

limit()

limit(
   x, 
   z, 
   velocity
): void;

Keep a walker inside the world's walk limit: changes velocity in place.

Parameters

Parameter	Type	Description
x	number	Where the walker is, x.
z	number	Where the walker is, z.
velocity	{ x: number; y: number; z: number; }	The velocity asked for.
velocity.x	number	-
velocity.y	number	-
velocity.z	number	-

Returns

void

load()

load(address, options?): Promise<LoadedWorld>;

Load a world package and make it playable. A world already in is taken out first.

Parameters

Parameter	Type	Description
address	string	The package's world.json, or its folder.
options?	WorldLoadOptions	The lighter copies, the form, the progress.

Returns

Promise<LoadedWorld>

The world, once it is playable: the place drawn, the collision and every thing in. The sounds may still be arriving; complete says when they are in.

move()

move(thing, point): void;

Put a loose thing somewhere, upright and at rest: the middle of its base at this point.

Parameters

Parameter	Type	Description
thing	WorldThing	The thing.
point	PointLike	Where.

Returns

void

near()

near(point, radius): readonly WorldThing[];

What is near a point, the nearest first. The array is reused by the next call.

Parameters

Parameter	Type	Description
point	PointLike	The point.
radius	number	Metres.

Returns

readonly WorldThing[]

onNotice()

onNotice(listener): () => void;

Hear what the world does.

Parameters

Parameter	Type	Description
listener	(notice) => void	Called with a record that is reused.

Returns

Call it to stop listening.

() => void

players()

players(eyes, within?): void;

Name the players' eyes, in a world whose collision comes by piece: a thing that drives further than 60 m from every eye (a machine a game drives out of sight) gets only a narrow band of ground, about its own width and 2 m each side, where a near one gets 12 m round it; it widens as it comes within 60 m. Call it once, or every frame as the players move. With none named, every machine is near.

Parameters

Parameter	Type	Description
eyes	readonly object[] | null	Where each player looks from, or null for none.
within?	number	How near an eye a machine counts as near, metres; 60 when left out (further than a game shows a machine clearly: the wide band is in before it is).

Returns

void

present()

present(alpha): void;

Put every loose thing's drawing where it stands at a point between the last two fixed steps. The module does this in its own update; whoever reads a thing's drawing earlier in the frame (a character seated on it) calls it first with the frame's factor.

Parameters

Parameter	Type	Description
alpha	number	The interpolation factor, 0 to 1.

Returns

void

push()

push(thing, impulse): void;

Shove a loose thing: an impulse at its middle, newton-seconds.

Parameters

Parameter	Type	Description
thing	WorldThing	The thing.
impulse	PointLike	The impulse.

Returns

void

reset()

reset(thing?): void;

Put a loose thing back where the package had it; with no thing, all of them.

Parameters

Parameter	Type	Description
thing?	WorldThing	The thing, or nothing for every loose thing.

Returns

void

rideOf()

rideOf(thing): WorldRide | null;

Where a rider meets a thing: an object at each of its rider spots (the seat, the grips, the foot rests), moving with the thing and with the part each spot is on.

Parameters

Parameter	Type	Description
thing	WorldThing	The thing.

Returns

WorldRide | null

The spots, or null for a thing whose package names no seat.

setJoint()

setJoint(
   thing, 
   joint, 
   value
): number;

Set one joint of a thing with moving parts: the part it moves, and every part that hangs from that one, turn or slide to the value. Held to the joint's limits.

Parameters

Parameter	Type	Description
thing	WorldThing	The thing.
joint	string | number	The joint's name in the package, or its place in the thing's list of joints.
value	number	Degrees for a hinge, metres for a slide.

Returns

number

The value the joint now stands at, or NaN when the thing has no such joint.

speedOf()

speedOf(thing): number;

How fast a thing that drives is going along its own front, metres a second.

Parameters

Parameter	Type	Description
thing	WorldThing	The thing.

Returns

number

Metres a second; 0 for a thing that does not drive.

standFor()

standFor(thing, from?): WorldStand;

Where to stand to use a thing. The record is reused by the next call.

Parameters

Parameter	Type	Description
thing	WorldThing	The thing.
from?	PointLike | null	Where the asker is, to stand on the nearest side.

Returns

WorldStand

unload()

unload(): void;

Take the current world out: its objects, bodies, lights and sounds.

Returns

void

---

WorldSplatForm

A thing or a place as points.

Properties

file

readonly file: string;

The file, by its path inside the folder.

light

readonly light: string | null;

How the points are lit, when the package says: place for a thing whose points already carry the place's light (the maker worked it out per point), so they are drawn as they are.

lite

readonly lite: string | null;

A lighter copy for phones, or null.

points

readonly points: number | null;

How many points the full file holds, when the package says.

---

WorldThingRecord

One thing: its own object (loose) or part of the place (fixed).

Properties

about

readonly about: string;

One sentence about it.

body

readonly body: WorldBody;

How it takes part in the physics.

box

readonly box: WorldBox;

Its box along the world's axes, as made.

forms

readonly forms: WorldForms;

The forms it comes in; both null for a fixed thing.

id

readonly id: string;

The package's id for it, unique in the world.

impact

readonly impact: readonly string[];

The sounds it makes when it hits something.

joints

readonly joints: readonly WorldJointRecord[];

The joints between its parts; empty for a thing that is one piece.

kind

readonly kind: string;

One plain noun.

label

readonly label: string;

What a person calls it.

parts

readonly parts: readonly WorldPartRecord[];

Its rigid parts, the root first; empty for a thing that is one piece.

placement

readonly placement: object;

Where the middle of its base is, how it is turned, and its scale.

position

readonly position: Triple;

rotation

readonly rotation: Quadruple | null;

The whole turn, when the package gives one; it then wins over yaw.

scale

readonly scale: number;

A multiplier on the thing's own files; 1 for a file in metres.

yaw

readonly yaw: number;

Degrees about y.

rests

readonly rests: string;

What it rests on.

rider

readonly rider: readonly WorldRiderSpot[];

Where a rider meets it; empty when the package names no spots.

size

readonly size: Triple;

Width, height, depth in metres.

stand

readonly stand: 
  | {
  facing: number;
  position: Triple;
}
  | null;

Where a character stands to use it, or null.

state

readonly state: "loose" | "fixed";

loose: its own object. fixed: part of the place and of its collision.

use

readonly use: "mesh" | "splat" | null;

Which form a game draws by default, or null when it has none.

vehicle

readonly vehicle: WorldVehicleRecord | null;

The numbers a vehicle needs, or null for a thing that does not drive.

---

WorldVehicleRecord

The few numbers a vehicle needs.

Properties

controls

readonly controls: readonly WorldControlRecord[];

The parts the rider works, each following what is asked of the vehicle; may be empty.

kind

readonly kind: string;

motorbike (two wheels in line, the front one steers) or monowheel (one wheel the whole thing stands in: it balances, and leans to steer).

lean

readonly lean: number;

How far it leans into a turn at most, degrees; 0 leaves it to the kind's own.

mass

readonly mass: number;

Kilograms, all of it.

steeringLimit

readonly steeringLimit: number;

How far it steers each way, degrees; 0 for a thing that leans to steer.

tread

readonly tread: number;

The share of each tyre's width that stands flat on the ground, 0.2 to 1 (1: all of it). A two-wheeled thing rolls onto its tyres' shoulders to lean, so a narrower tread leans further: on tyres half a metre wide a heavy machine leaned 12 degrees in a hard turn on a tread of 1, 18 on 0.7 and 24 on 0.5.

wheelbase

readonly wheelbase: number;

The distance between the axles, metres; 0 for one wheel.

wheels

readonly wheels: readonly WorldWheelRecord[];

The wheels, the front one first.

---

WorldWheelRecord

One wheel of a vehicle.

Properties

axle

readonly axle: Triple;

The middle of its axle at rest, the thing's frame.

down

readonly down: number;

How far it sinks at the lower limit, metres.

driven

readonly driven: boolean;

True when the engine drives it.

part

readonly part: string;

The part that is the wheel.

radius

readonly radius: number;

The tyre's radius, metres.

spin

readonly spin: string | null;

The joint it turns on, or null.

steer

readonly steer: string | null;

The joint that steers it, or null.

steerAlso

readonly steerAlso: readonly string[];

The other joints that turn by the same angle when it steers (the handlebars of a bike whose front wheel turns inside an arm of its own); empty when steer turns everything.

travel

readonly travel: string | null;

The joint its springing moves, or null.

up

readonly up: number;

How far the axle rises at the travel joint's upper limit, metres.

width

readonly width: number;

The tyre's width, metres.

Type Aliases

Matrix16

type Matrix16 = Float64Array | number[];

A 4 x 4 as three keeps it: sixteen numbers, column after column.

---

PlaceStep

type PlaceStep = 
  | {
  load: number;
}
  | {
  drop: number;
  for: number;
}
  | null;

What to do next: bring a place in, let one go, or nothing.

---

Quadruple

type Quadruple = readonly [number, number, number, number];

A turn as a quaternion, xyzw.

---

Triple

type Triple = readonly [number, number, number];

Three numbers: a point, a size or a colour.

---

WorldCollision

type WorldCollision = 
  | {
  file: string;
  lines?: unknown;
  shape: "mesh";
  tiles?: WorldCollisionTiles;
}
  | {
  cell: number;
  columns: number;
  file: string;
  origin: Triple;
  rows: number;
  shape: "heightfield";
}
  | {
  height: number;
  shape: "plane";
}
  | {
  shape: "none";
};

What stops a body in the place.

Union Members

Type Literal

{
  file: string;
  lines?: unknown;
  shape: "mesh";
  tiles?: WorldCollisionTiles;
}

file

readonly file: string;

lines?

readonly optional lines?: unknown;

The lines a game's own drivers follow (place.collision.lines), as the maker wrote them: for a game, carried untouched (a game reads them on the loaded world's record).

shape

readonly shape: "mesh";

tiles?

readonly optional tiles?: WorldCollisionTiles;

The same collision as files of its own, one for each square of the world's frame that has any, already cut into meshes under a cap of triangles: fetched as something comes near, never all at once. Left out when the package has only the one file (it is then cut as it loads).

---

Type Literal

{
  cell: number;
  columns: number;
  file: string;
  origin: Triple;
  rows: number;
  shape: "heightfield";
}

cell

readonly cell: number;

Metres between samples.

columns

readonly columns: number;

Samples along x.

file

readonly file: string;

origin

readonly origin: Triple;

Where the first sample is.

rows

readonly rows: number;

Samples along z.

shape

readonly shape: "heightfield";

---

Type Literal

{
  height: number;
  shape: "plane";
}

height

readonly height: number;

The floor's height, metres.

shape

readonly shape: "plane";

A level floor without end: what a world with no place stands on.

---

Type Literal

{
  shape: "none";
}

---

WorldThingsForm

type WorldThingsForm = "record" | "mesh" | "splat";

Which form the loose things are drawn in: each thing's own use, models, or points.

---

WorldWalkRecord

type WorldWalkRecord = 
  | {
  shape: "inside-collision";
}
  | {
  centre: Triple;
  fadeFrom: number;
  radius: number;
  shape: "radius";
};

How far the player may walk.

Variables

DESK_PLACES_BUDGET

const DESK_PLACES_BUDGET: 12000000 = 12_000_000;

Points a world of several places holds at once on a desk, by default: its backdrop and its places together. Twelve million holds a world of three or four made places whole (the first of them, three places and a backdrop, is 9.6 million), and is about 0.8 GB on the card.

Example

import { DESK_PLACES_BUDGET } from 'gameable/world';

await engine.get('world').load('/worlds/estate/', { placesBudget: DESK_PLACES_BUDGET / 2 });

---

FIT_AGREE

const FIT_AGREE: 0.25 = 0.25;

How far apart two sides' fits may be and still agree: a quarter, as the loader's own warning.

---

PACKAGE

const PACKAGE: "@gameable/world";

Package identity marker for gameable/world.

Example

import { PACKAGE } from 'gameable/world';

console.log(PACKAGE); // 'gameable/world'

---

PHONE_PLACES_BUDGET

const PHONE_PLACES_BUDGET: 1500000 = 1_500_000;

The same on a phone (a load with lite: true), where each layer's lighter copy is taken.

Example

import { PHONE_PLACES_BUDGET } from 'gameable/world';

console.log(PHONE_PLACES_BUDGET); // 1500000

---

WORLD_BODY_BASE

const WORLD_BODY_BASE: 1100000 = 1_100_000;

The first physics body id the world module uses: the place's collision is this id, and thing i of the list is this id plus one plus i. Game code mints its own bodies from 1 up, so the two never meet.

Example

import { WORLD_BODY_BASE } from 'gameable/world';

const trunkBody = WORLD_BODY_BASE + 1 + trunk.index;

---

WORLD_FORMAT

const WORLD_FORMAT: 1 = 1;

The format this engine reads. A package of a newer one is refused.

Functions

applyFileTransform()

function applyFileTransform(transform, positions): void;

Bring points from one of the place's files to the package's metres, in place.

Parameters

Parameter	Type	Description
transform	WorldFileTransform	The record's place.fileTransform.
positions	Float32Array	Points, three numbers each; changed in place.

Returns

void

Nothing.

Example

import { applyFileTransform } from 'gameable/world';

const points = new Float32Array([0, 1, 2]);
applyFileTransform({ scale: 2, flipY: true, floorOffset: 0.5 }, points);
console.log([...points]); // [0, -1.5, -4]

---

axleRise()

function axleRise(
   joint, 
   axle, 
   value
): number;

How far a wheel's axle rises when its travel joint is at a value: the height of the axle turned about the joint, less its height at rest.

Parameters

Parameter	Type	Description
joint	Pick<WorldJointRecord, "kind" | "at" | "axis">	The travel joint.
axle	Triple	The axle at rest.
value	number	The joint's value.

Returns

number

Metres, up positive.

Example

import { axleRise } from 'gameable/world';

const rise = axleRise(travelJoint, wheel.axle, 8); // 0.045: 8 degrees lift the axle 4.5 cm

---

controlValue()

function controlValue(
   control, 
   joint, 
   throttle, 
   right, 
   brake
): number;

Where a control's joint stands for what the rider asks: its rest value and each share, held to the joint's limits.

Parameters

Parameter	Type	Description
control	WorldControlRecord	The control.
joint	Pick<WorldJointRecord, "rest" | "limits">	Its joint.
throttle	number	From -1 (back) to 1.
right	number	From -1 (left) to 1.
brake	number	From 0 to 1.

Returns

number

The joint's value.

Example

import { controlValue } from 'gameable/world';

const lever = { joint: 'left-lever', steer: 12, throttle: 6, brake: -4 };
controlValue(lever, joint, 0, 1, 0); // 12 more than its rest: pushed forward for a right turn

---

createBreaker()

function createBreaker(things, host): Breaker;

The breaker of one world's things in pieces.

Parameters

Parameter	Type	Description
things	readonly BreakerThing[]	The things in pieces, each with its pieces.
host	BreakerHost	Who makes the bodies and the drawing, and tells the game.

Returns

Breaker

The breaker.

Example

import { createBreaker } from 'gameable/world';

const breaker = createBreaker([{ index: 0, pieces: [
  { index: 1, fixed: true, centre: [0, -0.3, 0] },
  { index: 2, fixed: false, centre: [0, 0.35, 0] },
] }], host);
breaker.breakThing(0, { x: 0, y: 0, z: 3 }); // the bowl flies off, the pedestal stays
breaker.mend(0);

---

createMotionTracker()

function createMotionTracker(count, tuning?): MotionTracker;

Follow the loose things of a world: knocks and moves from their poses.

Parameters

Parameter	Type	Description
count	number	How many things the world has.
tuning	MotionTuning	Thresholds; the defaults suit a room of furniture.

Returns

MotionTracker

The tracker. Its step allocates nothing.

Example

import { createMotionTracker } from 'gameable/world';

const tracker = createMotionTracker(1);
const pose = new Float32Array([0, 1, 0, 0, 0, 0, 1]);
tracker.placed(0, 0);
const result = tracker.step(0, pose, 0, 1 / 60, 1);
console.log(result.hit, result.moved); // 0 false: it has not moved

---

createPlainWorld()

function createPlainWorld(numbers): PlainWorld;

Make a plain world's floor, fog and colour.

Parameters

Parameter	Type	Description
numbers	PlainWorldNumbers	The numbers, from plainWorldOf.

Returns

PlainWorld

The floor to add to the scene, the fog and the background colour to set on it.

Example

import { createPlainWorld, plainWorldOf, readWorld } from 'gameable/world';

const numbers = plainWorldOf(readWorld(json));
if (numbers !== null) {
  const plain = createPlainWorld(numbers);
  scene.add(plain.floor);
  scene.fog = plain.fog;
  scene.background = plain.colour;
}

---

createWorldBridge()

function createWorldBridge(options): WorldBridge;

Wire a made world to game code: its events in, the game's thing commands out.

Make it after the engine adapter and before the world loads, or the game misses the loaded event; a world already in when the bridge is made is told at once.

Parameters

Parameter	Type	Description
options	WorldBridgeOptions	The world service and the adapter's event queue.

Returns

WorldBridge

The bridge.

Example

import { createWorldBridge } from 'gameable/world';

let bridge: WorldBridge | null = null;
const adapter = createEngineAdapter(engine, {
  modules,
  thing: (command) => bridge?.handle(command),
});
bridge = createWorldBridge({ world: engine.get('world'), events: adapter.events });
await engine.get('world').load('/worlds/forgotten-attic/');

---

createWorldLabels()

function createWorldLabels(
   things, 
   scene, 
   parent?
): WorldLabels;

Make the labels and boxes for a world's things.

Parameters

Parameter	Type	Default value	Description
things	readonly WorldThing[]	undefined	The world's things; each label follows its thing as it moves.
scene	Object3D	undefined	Where the boxes are drawn.
parent	HTMLElement	document.body	The element the labels are put in; defaults to the page's body.

Returns

WorldLabels

The labels, hidden until visible is set.

Example

import { createWorldLabels } from 'gameable/world';

const labels = createWorldLabels(list.things, engine.scene);
labels.visible = true;
engine.events.on('engine:frame', () => labels.update(engine.camera));

---

createWorldLights()

function createWorldLights(light): Light[];

The lights for a place's record.

Parameters

Parameter	Type	Description
light	WorldLight	The record's place.light.

Returns

Light[]

The lights to add to the scene: a directional light for the sun (standing 20 m up its direction, aimed at the origin) and a light probe for the surrounding light.

Example

import { createWorldLights } from 'gameable/world';

const lights = createWorldLights({
  sun: { direction: [0.1, -0.5, -0.86], colour: [1, 0.82, 0.62], strength: 2.4 },
  ambient: null,
});
console.log(lights.length); // 1

---

fitOf()

function fitOf(
   size, 
   measured, 
   fallback
): number;

The one number a thing's model is scaled by to stand at the size its record gives.

A model may come in any unit, so the loader measures it (after its nodes' own transforms) and fits it. Its height is the measure, as it always was, with one exception: when the height alone disagrees with BOTH other sides, and those two agree with each other, the model is missing its tallest parts (a lighter copy cut down from the full one keeps the full one's size in the record), and the fit is the width's and the depth's. Court-v1.2's road edge, 6 Oct 2026: its lighter copy is 2.456 m tall without its cypresses, the record says 9.351 m from the full copy, and fitting the height drew it 3.81 times too large over the court.

Parameters

Parameter	Type	Description
size	readonly [number, number, number]	The record's size: width (x), height (y), depth (z), metres.
measured	readonly [number, number, number]	The model's own size, measured the same way.
fallback	number	The scale to use when the model has no height to measure.

Returns

number

The scale.

Example

import { fitOf } from 'gameable/world';

fitOf([93.196, 9.351, 81.464], [93.196, 2.456, 81.464], 1); // 1, not 3.81
fitOf([2, 1, 2], [1, 0.5, 1], 1); // 2: a model in half metres

---

heightsToMesh()

function heightsToMesh(heights, map): object;

Open ground's height map as triangles, facing up, in metres.

The map is rows rows of columns heights, row by row; sample (column, row) stands at origin + (column * cell, height, row * cell).

Parameters

Parameter	Type	Description
heights	Float32Array	The heights, columns * rows of them.
map	{ cell: number; columns: number; file: string; origin: Triple; rows: number; shape: "heightfield"; }	The record's place.collision for a height map.
map.cell	number	Metres between samples.
map.columns	number	Samples along x.
map.file	string	-
map.origin	Triple	Where the first sample is.
map.rows	number	Samples along z.
map.shape	"heightfield"	-

Returns

object

Points and triangle indices for a static collision mesh.

indices

indices: Uint32Array;

positions

positions: Float32Array;

Throws

When there are fewer heights than the record says.

Example

import { heightsToMesh } from 'gameable/world';

const mesh = heightsToMesh(new Float32Array([0, 0, 0, 1]), {
  shape: 'heightfield', file: 'place/heights.bin', columns: 2, rows: 2, cell: 1, origin: [0, 0, 0],
});
console.log(mesh.positions.length / 3, mesh.indices.length / 3); // 4 points, 2 triangles

---

hullSetsOf()

function hullSetsOf(root): Float32Array<ArrayBufferLike>[];

The points of each closed shape in a file of several: one array for each mesh under the object, in the object's own frame after its nodes' transforms. A hulls file has one mesh for each shape; a hull file has one.

Parameters

Parameter	Type	Description
root	HullSource	The file's scene: anything with traverse, whose meshes carry a position attribute and a world matrix (a three.js object).

Returns

Float32Array<ArrayBufferLike>[]

The shapes' points, stride 3, each array its own.

---

insideRings()

function insideRings(
   x, 
   z, 
   rings
): boolean;

Whether a point on the ground is inside a place's rings (inside an odd number of them, so a ring inside a ring is a hole).

Parameters

Parameter	Type	Description
x	number	The point, x.
z	number	The point, z.
rings	readonly Ring[]	The rings.

Returns

boolean

True when the point is inside.

Example

import { insideRings } from 'gameable/world';

console.log(insideRings(1, 1, [[[0, 0], [4, 0], [4, 4], [0, 4]]])); // true

---

isInPieces()

function isInPieces(thing): boolean;

Whether a thing is in pieces: loose, at least two parts, and every joint between them of kind break.

Parameters

Parameter	Type	Description
thing	WorldThingRecord	The thing's record.

Returns

boolean

True when breaking it gives pieces.

Example

import { isInPieces, readWorld } from 'gameable/world';

const record = readWorld(json);
console.log(record.things.filter(isInPieces).map((thing) => thing.id)); // ['side-table', 'stone-urn']

---

jointMatrix()

function jointMatrix(
   joint, 
   value, 
   out
): Matrix16;

The move a joint makes at a value, as a matrix in the thing's frame: a hinge turns value degrees right-handed about the line through at along axis, a slide moves value metres along axis.

Parameters

Parameter	Type	Description
joint	Pick<WorldJointRecord, "kind" | "at" | "axis">	The joint.
value	number	Degrees for a hinge, metres for a slide.
out	Matrix16	Sixteen numbers to write, column after column (three's layout).

Returns

Matrix16

out.

Example

import { jointMatrix } from 'gameable/world';

const lid = { kind: 'hinge', at: [0, 1, 0], axis: [1, 0, 0] } as const;
const m = jointMatrix(lid, 90, new Float64Array(16));
// a point one metre in front of the hinge goes down: (0, 1, 1) lands on (0, 0, 0)

---

jointsOver()

function jointsOver(
   parts, 
   joints, 
   part
): number[];

The joints that move a part, the nearest to the part first: the part's own joint, then its parent's, up to the root.

Parameters

Parameter	Type	Description
parts	readonly WorldPartRecord[]	The thing's parts.
joints	readonly WorldJointRecord[]	The thing's joints.
part	string	The part's id.

Returns

number[]

Each joint's place in joints; empty for the root part or a part that is not there.

Example

import { jointsOver } from 'gameable/world';

console.log(jointsOver(thing.parts, thing.joints, 'handlebars')); // [0]: the steering

---

layerMatrixOf()

function layerMatrixOf(transform): number[];

The same transform as one matrix, sixteen numbers column by column (three's order): what takes a point of a layer's file to the world's frame. A layer's points are put through it once, when they arrive, so every layer of a world is in one frame and sorts as one.

Parameters

Parameter	Type	Description
transform	WorldFileTransform & Partial<Pick<WorldLayerTransform, "rotation" | "position" | "yaw">>	A layer's fileTransform (or the place's own).

Returns

number[]

The matrix.

Example

import { layerMatrixOf } from 'gameable/world';

const m = layerMatrixOf({ scale: 2, flipY: false, floorOffset: 0, position: [10, 0, 0], yaw: 90 });
// the file's (0, 0, 1) stands at (12, 0, 0) in the world: +z turned to +x, twice as far, moved
console.log(m[8] + m[12], m[9] + m[13], m[10] + m[14]);

---

materialOf()

function materialOf(material): object;

How a material slides and bounces.

Parameters

Parameter	Type	Description
material	string	The thing's body.material.

Returns

object

Friction and restitution, each 0 to 1; a material the engine does not know is taken as wood.

friction

friction: number;

restitution

restitution: number;

Example

import { materialOf } from 'gameable/world';

console.log(materialOf('glass')); // { friction: 0.3, restitution: 0.15 }

---

nextPlaceStep()

function nextPlaceStep(places, room): PlaceStep;

The next step for a world's places within a budget of points: bring the nearest waiting place in when there is room; when there is not, let go the farthest place that is in, if it is clearly farther than the one waiting (ten metres and a quarter more) and letting such places go makes the room; else that place waits, and the next nearest is looked at the same way. One place is on its way at a time.

Parameters

Parameter	Type	Description
places	readonly PlaceSlot[]	Every place: its points, its state, how far it is.
room	number	Points the budget still has free (the budget, less the backdrop and every place in or on its way).

Returns

PlaceStep

The step, or null for nothing to do now.

Example

import { nextPlaceStep } from 'gameable/world';

const step = nextPlaceStep(
  [
    { points: 2_500_000, state: 'in', distance: 140 },
    { points: 2_300_000, state: 'waiting', distance: 12 },
  ],
  500_000,
);
console.log(step); // { drop: 0, for: 1 }: the far place makes room for the near one

---

nextSound()

function nextSound(
   count, 
   last, 
   random
): number;

Which of a thing's sounds to play next: any but the one it played last.

Parameters

Parameter	Type	Description
count	number	How many sounds the thing has.
last	number	The one it played last, or -1.
random	number	A number in [0, 1).

Returns

number

The sound's place among them, or -1 when it has none.

Example

import { nextSound } from 'gameable/world';

console.log(nextSound(4, 2, 0.5)); // 1: one of the three others

---

orderParts()

function orderParts(parts): WorldPartRecord[];

The parts with every parent before its children.

Parameters

Parameter	Type	Description
parts	readonly WorldPartRecord[]	The parts as the record lists them.

Returns

WorldPartRecord[]

The same parts, ordered.

Throws

When a part names a parent that is not there, or the parts make a ring.

Example

import { orderParts } from 'gameable/world';

const ordered = orderParts(thing.parts);
console.log(ordered[0]?.parent); // null: the root comes first

---

pieceCentre()

function pieceCentre(thing, part): Triple;

The middle of a piece's box in its thing's body frame: the thing's own frame (metres, the origin at the middle of its base) moved down half the thing's height, since a body's origin is the middle of the thing.

Parameters

Parameter	Type	Description
thing	WorldThingRecord	The thing's record.
part	WorldPartRecord	The piece.

Returns

Triple

The point, or the body's own middle for a piece with no box.

---

pieceRecord()

function pieceRecord(thing, part): WorldThingRecord;

One piece as a thing of its own: where it stands in the world as the package placed its thing, its own size, its own body (its hull or hulls, its weight, fixed or not) and its own sounds when it has any. It has no form of its own to draw: it is drawn by its node of the thing's model.

Parameters

Parameter	Type	Description
thing	WorldThingRecord	The thing's record.
part	WorldPartRecord	The piece.

Returns

WorldThingRecord

The piece's record, named <thing id>.<part id> and labelled <thing>: <piece>.

Example

import { pieceRecord, readWorld } from 'gameable/world';

const urn = readWorld(json).things[0];
console.log(pieceRecord(urn, urn.parts[1]).label); // 'stone urn: bowl'

---

piecesOf()

function piecesOf(record): WorldPiece[];

Every piece of a world, in the order the list holds them: the things in pieces in the package's order, each one's parts in their order, numbered on from the package's things.

Parameters

Parameter	Type	Description
record	WorldRecord	The world's record.

Returns

WorldPiece[]

The pieces; empty for a world with no thing in pieces.

Example

import { piecesOf, readWorld } from 'gameable/world';

const record = readWorld(json);
for (const piece of piecesOf(record)) console.log(piece.index, piece.id); // 3 'stone-urn.pedestal' ...

---

placeDistance()

function placeDistance(
   place, 
   x, 
   z
): number;

How far a point on the ground is from a place: from the ground it is the one to show on (good), or from its box when the package gives no such ground.

Parameters

Parameter	Type	Description
place	Pick<WorldPlaceLayer, "good" | "bounds">	The place.
x	number	The point, x.
z	number	The point, z.

Returns

number

Metres; 0 on the place's own ground.

Example

import { placeDistance, readWorld } from 'gameable/world';

const [court] = readWorld(json).places;
console.log(placeDistance(court, 70, 94)); // 0 when the point is on the court

---

placeTransformOf()

function placeTransformOf(transform): PlaceTransform;

Where the place's files stand, from the record's fileTransform:

p = (0, floorOffset, 0) + R (scale * p_file), R = half a turn about x when flipY

A half turn about x is how a file whose y points down is stood up: up becomes up and what was in front stays in front (z changes sign with y), so nothing is mirrored.

A layer of a world made of several places (backdrop, each of places) also turns and moves: p = position + Q * ((0, floorOffset, 0) + R (scale * p_file)), Q the layer's rotation when it has one, else a turn of yaw degrees about y.

Parameters

Parameter	Type	Description
transform	WorldFileTransform & Partial<Pick<WorldLayerTransform, "rotation" | "position" | "yaw">>	The record's place.fileTransform, or a layer's.

Returns

PlaceTransform

The position, turn and scale to give the object.

Example

import { placeTransformOf } from 'gameable/world';

const t = placeTransformOf({ scale: 1.0856, flipY: true, floorOffset: 0.6354 });
console.log(t.position, t.quaternion, t.scale); // [0, 0.6354, 0] [1, 0, 0, 0] 1.0856

---

plainWorldOf()

function plainWorldOf(record): PlainWorldNumbers | null;

The numbers of a plain world, from the record of a world with no place.

The fog starts where the walk limit ends (never nearer than 12 m, so a thing near the start is seen in its own colours from anywhere a walker stands by it) and ends 60 m further. The floor is whole within 8 m of the eye (so a thing's shadow is whole from anywhere a walker stands by it) and gone at 60 m: for a standing person that is from 11 degrees under eye level to 1.5, faded evenly over that angle, so no line shows where it ends.

Parameters

Parameter	Type	Description
record	WorldRecord	The record, from readWorld.

Returns

PlainWorldNumbers | null

The numbers, or null when the world has a place.

Example

import { plainWorldOf, readWorld } from 'gameable/world';

const plain = plainWorldOf(readWorld(json));
console.log(plain?.colour, plain?.fogNear, plain?.fogFar); // [1, 1, 1] 17 77

---

rankPlaces()

function rankPlaces(
   places, 
   x, 
   z, 
   route?
): object[];

The places of a world in the order they should come, for a rider at a point: the place the rider is on first, then each by how far along the route the rider reaches it (route; a place the route never reaches, or a world with no route, by how far it is in a straight line). Among places equally far the lower priority comes first, then the record's order.

Parameters

Parameter	Type	Default value	Description
places	readonly Pick<WorldPlaceLayer, "bounds" | "priority" | "good">[]	undefined	The record's places.
x	number	undefined	The rider, x.
z	number	undefined	The rider, z.
route	WorldRoute | null	null	The way the rider will go (the record's first route), or null.

Returns

object[]

Each place's index and its distance in metres, the first to come first.

Example

import { rankPlaces, readWorld } from 'gameable/world';

const record = readWorld(json);
const { position } = record.place.spawn;
const order = rankPlaces(record.places, position[0], position[2], record.routes[0] ?? null);
console.log(order.map((entry) => record.places[entry.index]?.id));

---

rankPlacesAhead()

function rankPlacesAhead(
   places, 
   path, 
   route?
): object[];

rankPlaces for a rider that is moving: the place under the rider is under it, and any other is as near as the rider's way over the next seconds comes to it (ridePath: the points after the first). So the place ahead is asked for before the rider is on it, and a place just left is already as far as the first point ahead is from it: under a budget the place let go is the one behind.

Parameters

Parameter	Type	Default value	Description
places	readonly Pick<WorldPlaceLayer, "bounds" | "priority" | "good">[]	undefined	The record's places.
path	readonly readonly [number, number][]	undefined	Where the rider is now, then where it will be (ridePath).
route	WorldRoute | null	null	The way the rider will go, or null.

Returns

object[]

Each place's index and its distance in metres, the first to come first.

Example

import { rankPlacesAhead, ridePath } from 'gameable/world';

const path = ridePath(rider.x, rider.z, speed.x, speed.z, 4, record.routes[0] ?? null);
const [next] = rankPlacesAhead(record.places, path, record.routes[0] ?? null);

---

readWorld()

function readWorld(doc): WorldRecord;

Read a world package's record: world.json, already parsed.

Every default is filled in, fields the reader does not know are ignored, and a record it cannot honour is refused in plain words: a package of a newer format ("made for a newer engine"), a file outside the folder, a thing with no id or nowhere to be.

Parameters

Parameter	Type	Description
doc	unknown	The parsed JSON.

Returns

WorldRecord

The record.

Throws

When the record cannot be read.

Example

import { readWorld } from 'gameable/world';

const record = readWorld(await (await fetch('/worlds/forgotten-attic/world.json')).json());
console.log(record.name, record.things.length);

---

ridePath()

function ridePath(
   x, 
   z, 
   vx, 
   vz, 
   seconds, 
   routes?
): [number, number][];

Where a rider will be over the next few seconds, as points on the ground: where it is now, then points along the way it goes. Near one of the world's routes (within fifteen metres of it) and moving along it (within about 35 degrees of its line, either way) the way is that route's; elsewhere, or across a route, it is a straight line along the rider's own movement. A rider that is nearly still is only where it is.

Parameters

Parameter	Type	Default value	Description
x	number	undefined	The rider, x.
z	number	undefined	The rider, z.
vx	number	undefined	Its speed along x, metres a second.
vz	number	undefined	Its speed along z.
seconds	number	undefined	How far ahead to look.
routes	| WorldRoute | readonly WorldRoute[] | null	null	The world's routes (or one of them), or null.

Returns

[number, number][]

The points, the first where the rider is now; a tenth of the way looked ahead apart (ten metres at least on a straight line), twelve at most.

Example

import { ridePath } from 'gameable/world';

console.log(ridePath(0, 0, 20, 0, 4)); // from [0, 0] to [80, 0], ten metres apart

---

spotFrame()

function spotFrame(spot): object;

A rider spot's own frame: the way a character there faces (forward), up, and the character's left, each of length 1 and square to the others. A seat and a foot rest say forward; a grip says along (the way its bar runs outward), so its left is along the bar toward the thing's left (+x) and its forward is the way the knuckles point.

Parameters

Parameter	Type	Description
spot	WorldRiderSpot	The spot.

Returns

object

The three directions, in the thing's own frame at rest.

forward

forward: Triple;

left

left: Triple;

up

up: Triple;

Example

import { spotFrame } from 'gameable/world';

const { forward, up, left } = spotFrame(thing.rider[0]);
console.log(forward); // [0, 0, 1] for a seat that faces the thing's front

---

startPlace()

function startPlace(record): number;

The place a rider starts in: the one whose own ground holds the start, else the nearest.

Parameters

Parameter	Type	Description
record	Pick<WorldRecord, "places" | "place">	The world's record.

Returns

number

The place's index among places, or -1 for a world with none.

Example

import { readWorld, startPlace } from 'gameable/world';

const record = readWorld(json);
console.log(record.places[startPlace(record)]?.id); // 'house-front'

---

steerShown()

function steerShown(
   joint, 
   steeringLimit, 
   angle
): number;

What a steering joint shows when the thing steers by angle: the angle itself, or, for a joint with less room than the thing's steering limit (a wheel that turns inside a housing and steers mostly by leaning), its share of the turn, so the joint reaches its own limit as the steering reaches its end and never stops short of the turn.

Parameters

Parameter	Type	Description
joint	Pick<WorldJointRecord, "limits">	The steering joint.
steeringLimit	number	How far the thing steers each way, degrees.
angle	number	How far it is steered now, degrees.

Returns

number

The joint's value, degrees.

Example

import { steerShown } from 'gameable/world';

// a wheel with 6 degrees of room on a thing that steers 18: a third of the turn shows
const shown = steerShown({ limits: [-6, 6] }, 18, 9); // 3

---

travelFor()

function travelFor(
   joint, 
   axle, 
   rise
): number;

The travel joint's value that lifts a wheel's axle by rise, inside the joint's limits: the springing's length turned back into the arm's angle.

Parameters

Parameter	Type	Description
joint	WorldJointRecord	The travel joint.
axle	Triple	The axle at rest.
rise	number	Metres, up positive.

Returns

number

The joint's value, held to its limits.

Example

import { travelFor } from 'gameable/world';

const degrees = travelFor(travelJoint, wheel.axle, 0.02); // the arm's angle with the wheel 2 cm up

---

turnOf()

function turnOf(thing): Quadruple;

How a thing is turned as made: its whole turn when the package gives one, else its yaw.

Parameters

Parameter	Type	Description
thing	WorldThingRecord	The thing's record.

Returns

Quadruple

The quaternion, xyzw, of unit length.

---

world()

function world(options?): EngineModule;

The made-world EngineModule.

Register it after physics(), audio() and splat(); its service is engine.get('world').

Parameters

Parameter	Type	Description
options	WorldModuleOptions	How a knock is told from a thing's motion, and the module's order.

Returns

EngineModule

The module, to be passed in createEngine({ modules }).

Example

import { audio } from 'gameable/audio';
import { createEngine } from 'gameable/core';
import { physics } from 'gameable/physics';
import { splat } from 'gameable/splat';
import { world } from 'gameable/world';

const engine = await createEngine({
  canvas,
  manifest,
  modules: [physics(), audio(), splat(), world()],
});
const made = await engine.get('world').load('/worlds/forgotten-attic/');
console.log(made.list.name, engine.get('world').find('the trunk')?.position);
engine.start();

---

worldAssetId()

function worldAssetId(
   world, 
   owner, 
   part, 
   index?
): string;

The asset id of one file of a world: the world's id, whose it is and which part, joined with dots.

The engine's ids are lower-case letters, digits, dots, dashes and underscores, 64 at most, so a slash never appears; an id that would run over is shortened to the world's id, t<index> and the part.

Parameters

Parameter	Type	Default value	Description
world	string	undefined	The world's id.
owner	string	undefined	A thing's id, place, backdrop, places.<place id>, or sounds.
part	string	undefined	Which file: mesh, mesh-lite, splat, splat-lite, hull, collision, impact-1, room-1 ...
index	number	0	The thing's place in the list, used only to shorten a long id.

Returns

string

The id.

Example

import { worldAssetId } from 'gameable/world';

console.log(worldAssetId('forgotten-attic', 'steamer-trunk', 'mesh')); // 'forgotten-attic.steamer-trunk.mesh'

---

worldAssets()

function worldAssets(record): WorldAsset[];

Every file of a world a game might name, as manifest entries.

The place's panorama, its pictures and a height map are not here: nothing in game code names them, and the loader fetches them itself.

Parameters

Parameter	Type	Description
record	WorldRecord	The world's record.

Returns

WorldAsset[]

The entries, each src a path inside the world's folder.

Example

import { readWorld, worldAssets } from 'gameable/world';

const entries = worldAssets(readWorld(json));
console.log(entries.map((entry) => entry.id)); // ['forgotten-attic.place.splat', ...]

---

worldListOf()

function worldListOf(record, bodyOf?): WorldList;

The list a game asks questions of, from a world's record.

Parameters

Parameter	Type	Description
record	WorldRecord	The record, from readWorld.
bodyOf	(index) => number	The physics body the host gives each thing, by its place in the list; 0 for none.

Returns

WorldList

The list: the start, the walk limit, and every thing where the package put it.

Example

import { findThing } from 'gameable';
import { readWorld, worldListOf } from 'gameable/world';

const list = worldListOf(readWorld(json));
console.log(findThing(list.things, 'the trunk')?.position);

---

worldSphere()

function worldSphere(record): object;

A sphere that holds every layer of a world there will ever be, from the record's own boxes: the backdrop's, each place's, the world's own and every thing's. The joined places' depth order is built from it, so it is known before anything has arrived.

Parameters

Parameter	Type	Description
record	Pick<WorldRecord, "places" | "backdrop" | "place" | "things">	The world's record.

Returns

object

The sphere's middle and radius, metres; a wide one round the start when the record gives no box at all.

center

center: [number, number, number];

radius

radius: number;

Example

import { readWorld, worldSphere } from 'gameable/world';

const { center, radius } = worldSphere(readWorld(json));
console.log(center, radius);

---

yawToQuaternion()

function yawToQuaternion(degrees): Quadruple;

A turn about y as a quaternion.

Parameters

Parameter	Type	Description
degrees	number	Degrees about y, counter-clockwise seen from above.

Returns

Quadruple

The quaternion, xyzw.

Example

import { yawToQuaternion } from 'gameable/world';

console.log(yawToQuaternion(180)); // [0, 1, 0, ~0]