The game runtime's API
What @jami3d/three gives a game: the package and its worlds, entities by key, clips, params, actions and events, host targets, instances, time and snapshots, prefabs, ambient sound and credits.
The package and its worlds
The samples on this page name your game's renderer, scene, camera and player, and the pkg and world that the quickstart makes. Their keys (yard, gate, lamp, …) are examples: pkg.worlds, pkg.prefabs and world.find() list your package's own.
loadPackage answers a GamePackage: its id, name, version and licence (terms and holder), its features, its worlds and prefabs (each a key and a name), the tiers it carries and the tier it draws at, credits(), createWorld(key?, { seed?, quality? }), dispose(), and reader: the package's files, for those a game reads itself (README.txt, LICENSE.txt).
console.log(pkg.name, pkg.version, pkg.tier, pkg.tiers, pkg.features);
console.log(`${pkg.licence.terms}, held by ${pkg.licence.holder}`);
for (const { key, name } of pkg.worlds) console.log("world", key, name);
for (const { key, name } of pkg.prefabs) console.log("prefab", key, name);
// Another world of the package, with a seed and a tier of its own.
const yard = await pkg.createWorld("yard", { seed: 7, quality: "medium" });
scene.add(yard.root);
// A file a game reads itself: its README.txt or LICENSE.txt, its bytes checked.
const readme = pkg.reader.file("README.txt");
if (readme !== undefined) {
console.log(new TextDecoder().decode(await pkg.reader.bytes(readme.path)));
}A world (GameWorld) is built under world.root. Everything it shows is a function of its time: clips, living bodies, sky, fog, water, wind and effects. A world carries its scene's seed (world.seed, a string), so its behaviours and effects play as they do in JAMI's Live Room; createWorld(key, { seed }) chooses another, a string or a number. Living bodies are stepped at a fixed 30 Hz on the world's time: your game does not step them.
Entities
const gate = world.entity("gate"); // by key: the entity's alias in JAMI
const trees = world.find({ tags: { all: ["tree"] } });
const nearby = world.find({ within: { around: [0, 0, 0], radiusM: 10 }, facets: ["living"] });
const inside = world.find({ under: "house" }); // everything below an entity
for (const entity of trees) {
console.log(entity.key, entity.name, entity.kind, entity.tags, entity.object.position);
}
if (gate !== undefined) {
gate.object.rotation.y = Math.PI / 2; // its node in world.root: move, turn or hide it
console.log(gate.parent?.key, gate.children.map((child) => child.key));
}An entity's key is its alias in JAMI where it has one, else its name made ASCII with a short code (stone-k7f3) that changes when the entity is renamed. Name entities in your game by their alias, and ask whoever makes the package to give one to every entity your game names.
A GameEntity gives its key, name, kind (its content kind: model, character, light, …), tags, facets (character, prop, living, zone, interactive, …), its object in world.root (move, turn or hide it), parent and children, whether it is living (a living body moves it each frame), its clips, and its controls: params, actions and events. world.find(query) takes tags (all, any, none), facets, keys (ids), a region (within a zone, a box or a sphere) and an ancestor (under); every clause is optional.
Playing clips
const guard = world.entity("guard");
if (guard !== undefined && guard.clips.includes("Wave")) {
const played = guard.play("Wave"); // from now, on the world's time
if (!played.ok) console.warn(played.reason); // not_found, unsupported
}
// A prop, light or group that moves by itself lists one clip, "motion".
const fan = world.entity("fan");
fan?.play(null); // stopped: what it moved is your game's now
fan?.play("motion"); // started again, on the world's timeentity.play(name) plays one of a character's clips from now, on the world's time; play(null) stops it. A character whose performance was composed into one clip at export starts it by itself when it enters the world. A prop, light, group, anchor or camera that moves by itself lists one clip, motion: play(null) stops it and leaves what it moved to your game, and play("motion") starts it again.
Params, actions and events
A package carries what its maker marked for a host in JAMI's interaction graphs: params your game may write, actions it may call, and events it hears. The logic between them stays in JAMI.
const lamp = world.entity("lamp");
if (lamp !== undefined) {
console.log(lamp.params, lamp.param("on"), lamp.actions, lamp.events);
const written = lamp.setParam("on", false);
if (!written.ok) console.warn(written.reason); // not_found, not_allowed, invalid_input
lamp.action("flicker"); // heard as an "event" of type "action"
}
const stopListening = world.on("state", (event) => {
console.log(`${event.entity}.${event.param} = ${String(event.value)} at ${event.atS} s`);
});
world.on("event", (event) => {
if (event.type === "enter") console.log(`${event.other} entered ${event.entity}`);
if (event.type === "exit") console.log(`${event.other} left ${event.entity}`);
});
world.on("error", ({ error }) => console.error(error)); // a listener that threw, a part that did not load
stopListening();Calls made while playing — setParam, action, play, despawn, host.setTarget — answer {ok: true} or {ok: false, reason} with an error code: a refusal never throws. Every write and call is kept by world time, so setTime and snapshots replay them. world.on(name, listener) answers a function that stops listening; world.off does too. A world sends:
| Event | Fields | When |
|---|---|---|
life | type, entity, target?, drive, atS | A living body noticed, caught, escaped, arrived, left or got stuck. For a place it arrived at or left, target is the place's key. |
event | entity, type, name, other?, atS | An action was called, or a trigger zone was entered (enter) or left (exit) by other. |
state | entity, param, value, atS | A param was written. |
degraded | reason, detail, entity? | Something is drawn or run with less than the package holds (what it means). |
deprecation | id, detail | The package uses something a later runtime reads differently. |
error | error | A fault outside a call: a listener that threw, a part that did not load. |
Host targets
A living body's behaviour may aim at a target only your game knows, such as its player: {host: "player"} in JAMI. world.hostTargets lists the names the package's behaviours use. Name each with an Object3D of your scene (followed as it moves), a point [x, y, z], or null (none: a behaviour aiming at it does not run, and the body's other behaviours take over).
// The names the package's behaviours aim at, such as {host: "player"}.
if (world.hostTargets.includes("player")) {
const named = world.host.setTarget("player", player); // an Object3D of yours, followed as it moves
if (!named.ok) console.warn(named.reason);
}
world.on("life", (event) => {
if (event.type === "noticed") console.log(`${event.entity} noticed ${event.target}`);
if (event.type === "caught") console.log(`${event.entity} caught ${event.target}`);
if (event.type === "arrived") console.log(`${event.entity} reached ${event.target}`);
});The runtime reads where each target stands at every update. A trigger zone tells when a living body, a host target or an entity your game spawned enters or leaves it (an event of type enter or exit).
Instances
An instance set draws many copies of one model — grass, rocks, a stand of trees — by stable ids. Promote one to make it an entity of its own (<set>#<id>), drawn by its own node from then on.
const grass = world.instances("grass");
if (grass !== undefined) {
console.log(grass.count, grass.drawn, grass.ids().length);
const place = grass.position(17); // where instance 17 stands, or null
const picked = await grass.promote(17); // now an entity of its own, "grass#17"
picked?.object.scale.setScalar(1.5);
console.log(place);
}Time, snapshots and quality
world.setTime(12.5); // the world as it is 12.5 s in, exactly as playing to it gives
const saved = world.snapshot(); // in memory, in this page only
world.update(1 / 60, camera);
world.restore(saved); // back to it: the same frames follow
await world.setQuality("low"); // another tier the package carries
console.log(world.timeS, world.stats()); // entities, instances drawn, living bodies, collidersworld.setTime(t) jumps to an instant and gives exactly what playing to it gives; world.timeS is the world's time. A snapshot lives in memory, in this page only: it is not a save game, and a copy of it (JSON, a structured clone) is refused invalid_input. To save a game, keep what your game needs (its params, its time) and set it again.
Spawning prefabs
A package exported with prefabs (each kit placed in the scene, as a prefab too) lets your game spawn them by key (pkg.prefabs). A spawned prefab's living bodies live from the moment spawn is called, on the world's navmesh and ground; its effects and water draw too.
const crate = await world.spawn("crate", { position: [2, 0, -4] }); // key "crate", then "crate-2"…
console.log(crate.key, crate.living);
const removed = world.despawn(crate.key); // {ok: true}; not_allowed for what the package placed
if (!removed.ok) console.warn(removed.reason);Ambient sound
A package exported with its scene's ambience loops plays them through your listener, each from its entity, once you hand it one — after a person's gesture, since browsers start sound only then. world.setAudio(null) stops them.
import { AudioListener } from "three";
const listener = new AudioListener();
camera.add(listener);
// Browsers start sound only after a person's gesture.
document.addEventListener("pointerdown", () => void world.setAudio(listener), { once: true });Credits and licence
A package's credits are what its files owe their makers: show them wherever your game shows its credits. Each has a title, an attribution, a licence (an SPDX id where there is one) and, when it has one, a source address; world.credits() gives the same. The package's own terms and holder are pkg.licence, and its LICENSE.txt.
for (const credit of await pkg.credits()) {
const where = credit.source === undefined ? "" : ` (${credit.source})`;
console.log(`${credit.title} — ${credit.attribution}, ${credit.licence}${where}`);
}