Table Scripting (Surface A)
Types
The fourteen ambient declarations a table script compiles against - Vec3, ObjectKind, the action unions, SpawnObjectOptions, DiceRollSummary, declareVariables.
On this page40 sections
- The core types
- Members, one row each
- What is not here
- See also
- Vec3
- ObjectKind
- ObjectAction
- ObservedObjectAction
- ObjectDestroyedReason
- ObjectClickContext
- HighlightStyle
- HighlightTarget
- HighlightOptions
- ClearHighlightsOptions
- ObjectMenuItemRegistration
- match is data, not a callback
- TextLabelOptions
- TooltipVariableValue
- TooltipData
- TooltipOptions
- ObjectActionOptions
- ContainerItem
- CoinObject
- TableFurnitureObject
- ButtonObject
- SpawnObjectOptions
- SeatZoneInfo
- SnapPointInfo
- DealToOptions
- DiceRollSummary
- RollRequestDie
- RollRequestSpec
- RollRequestResult
- PlayerInfo
- TurnInfo
- BotDifficultyInfo
- UiWidgetPatch
- ScriptVariableSpec
- ScriptVariableValue
- declareVariables
The declared types a table script meets that are not World, ObjectHandle or ObjectData, plus the one
ambient call that is not a method on any of them, declareVariables. Some are unions or
aliases used as values; others are records handed to you by a call. None of them is constructed — you write
object literals and tuples, and the editor checks them against these declarations.
Three of them are worth reading before you write anything. Vec3 is a tuple, not an {x, y, z}
object, and its units are feet — that is the single most common surprise for anyone who has written a mod
first. ObjectKind names all eleven kinds the engine has, and then accepts any
other string as well. And there are two action types, not one:
ObjectAction is what a script may request and
ObservedObjectAction is what an event delivers.
The core types#
| Type | Kind | What it is for |
|---|---|---|
Vec3 |
type alias | [x, y, z] in feet for a position, degrees for a rotation. Every coordinate in table scripting. |
ObjectKind |
union | What an entity is — the required field of a spawn, and the filter getAllObjects narrows on. |
ObjectAction |
union | The 13 action names a script may request, and the vocabulary behind the nine mutator methods. |
ObservedObjectAction |
union | The 27 names an action event can deliver — every engine action: the 13 above plus lift, flick, press, toss, peek, the three search*, the three reveal-*, tip-out, empty and clear-source. |
ObjectDestroyedReason |
union | The four ways an entity can leave the table, on EventContext.reason. Only one of them is a deletion. |
ButtonObject |
interface | The handle a button narrows to — eventName and the onPressed delegate. |
TableFurnitureObject |
interface | The handle a table narrows to. Adds nothing to ObjectHandle; declared so a table's own script has a type. |
CoinObject |
interface | The handle a coin narrows to — the onTossed delegate, raised at the throw. |
SpawnObjectOptions |
interface | The whole description of a new entity: one required field and the optional rest. |
PlayerInfo |
interface | One connected peer — id, name, seat, team, host flag. |
TurnInfo |
interface | Whether turn order is on, and whose turn it is. |
DiceRollSummary |
interface | One finished batch dice roll — the roller, the notation, every face, the total, and how many were unreadable. |
declareVariables |
const | The one call that declares the typed slots a script needs filled in from the entity inspector. |
ScriptVariableSpec |
union | One declared slot — its type, and the kind/tag filters the inspector enforces. |
ScriptVariableValue |
conditional type | What each declared slot reads back as, and when it reads null. |
The generated declarations below this intro are the authoritative list; a few smaller records
(ObjectActionOptions, SeatZoneInfo, DealToOptions) are documented there too, as is
TextLabelOptions — everything world.setTextLabel
takes to draw text flat on the table.
Members, one row each#
| Member | Type | What it is for |
|---|---|---|
SpawnObjectOptions.kind |
ObjectKind |
Required. A non-empty string, or the spawn resolves null. |
SpawnObjectOptions.name |
string |
Sets the entity's label — its slug — not its human name. |
SpawnObjectOptions.position |
Vec3 |
Where it appears. Defaults to [0, 1, 0], one foot up. |
SpawnObjectOptions.rotation |
Vec3 |
Starting Euler angles. Dropped rather than defaulted when malformed. |
SpawnObjectOptions.presetId |
string |
A standard-library preset, for the model and a die's collision hull. |
SpawnObjectOptions.metadata |
Record<string, unknown> |
Freeform data, copied shallowly, write-once from a script. |
SpawnObjectOptions.tags |
string[] |
The only spawn field world.getAllObjects can filter on. |
PlayerInfo.peerId |
string |
The identity. Key everything on this. |
PlayerInfo.displayName |
string | null |
The name to print. Optional, not unique. |
PlayerInfo.seat |
string | null |
Their seat, or null for a spectator. |
PlayerInfo.team |
string | null |
Their team, or null — the default at most tables. |
PlayerInfo.isHost |
boolean |
true on exactly one row — the machine the scripts run on. |
TurnInfo.enabled |
boolean |
Whether turn order is running at all. |
TurnInfo.activePeerId |
string | null |
Whose turn it is. null has two causes. |
DiceRollSummary.rollId |
string |
Identifies the throw. The dice from it carry the same id. |
DiceRollSummary.actorPeerId |
string |
Who rolled. Always present — key on this. |
DiceRollSummary.actorName |
string |
Their display name, frozen at emit. Not unique. |
DiceRollSummary.seat |
string | null |
Their seat, or null — a seatless player can still roll. |
DiceRollSummary.target |
"tray" | "table" |
Their own bounded region, or the shared table. |
DiceRollSummary.notation |
string |
3d6+1d20, grouped by face count, not by preset. |
DiceRollSummary.dice |
ReadonlyArray<…> |
Per die: objectId, preset, sides, and the face or null. |
DiceRollSummary.total |
number |
Sum of the readable faces only. |
DiceRollSummary.cocked |
number |
How many dice reported no face. Read it before trusting total. |
What is not here#
ObjectData, ObjectHandle and their ten fields live on
ObjectHandle. EventContext and ScriptDelegate live on
Events, with the delegates that use them.
The mod surface has its own, differently shaped versions of several of these — Vector3 is an object, not a
tuple, and TableObjectKind names all eleven kinds. They are documented on api and
are not interchangeable with anything on this page.
See also#
World— the calls that take and return these types.ObjectHandle—ObjectData's ten fields, documented there.- Events —
EventContext,ScriptDelegate, and every delegate's payload. - Action vocabularies — the authoritative comparison behind the two action types.
- Object kinds — what each of the eleven kinds does.
- Choosing a surface — why the mod types differ.
- Known limitations — every documented gap, in one list.
Vec3#
Surface A — table script · type
A [x, y, z] position/rotation triple in table space.
declare type Vec3 = [number, number, number];
A position or a rotation, as a three-element tuple: [x, y, z]. Positions are absolute table-space coordinates
in feet; rotations are Euler angles in degrees. Every coordinate a table script reads or writes is one of
these — ObjectData.position, ObjectData.rotation, SpawnObjectOptions.position and rotation, and the
arguments to setPosition and setRotation.
How, why and when to use it#
You are moving a piece three feet to the left, and the first thing you need to know is what shape the API wants.
Vec3 is a plain array, so you read it by destructuring and write it by building a new one — there is no
constructor, no clone, and no x/y/z properties to reach for. The alternative shape, an object with
x/y/z, is what the mod API uses and what the replicated entity state uses internally; if you have written
a mod first, this is the thing that will trip you. Build the tuple inline at the call site rather than mutating
one you read, because the array a handle hands you is its own cached copy and writing into it changes nothing.
Example#
// content/scripting-api/examples/vec3.ts
// Scene script: Vec3 is a plain [x, y, z] tuple in FEET, not an object with
// x/y/z properties. Destructure it to read, and build a fresh tuple to write.
function distanceFeet(a: Vec3, b: Vec3): number {
const dx = a[0] - b[0];
const dy = a[1] - b[1];
const dz = a[2] - b[2];
return Math.sqrt(dx * dx + dy * dy + dz * dz);
}
const ORIGIN: Vec3 = [0, 0, 0];
async function tidyStrays(): Promise<void> {
const entities = await world.getAllObjects();
if (entities.length === 0) {
world.log("Nothing on the table yet.");
return;
}
for (const entity of entities) {
const [x, y, z] = entity.position;
const away = distanceFeet(entity.position, ORIGIN);
world.log(`${entity.name ?? entity.kind} at [${x}, ${y}, ${z}] ft is ${away.toFixed(2)} ft from the middle.`);
if (away > 6) {
// One foot above the table so it drops onto the surface.
entity.setPosition([0, 1, 0]);
entity.setRotation([0, 0, 0]);
world.log(`${entity.id} was recalled to the middle of the table.`);
}
}
}
void tidyStrays();
The script console prints one line per entity, for example
red-die at [4.2, 0.35, -1.1] ft is 4.35 ft from the middle.
Gotchas#
Units are feet, and y is up. [0, 1, 0] is one foot above the table origin — the default spawn height, so
a new piece drops onto the surface rather than clipping through it.
Mod scripting uses a different shape. Surface B's Vector3 is { x, y, z }, not a tuple, and the two are
not interchangeable. The one exception on that side is api.playSound's position, which really is a
[number, number, number] tuple. See Vector3.
Writing into the array you read does nothing. handle.position[0] = 3 mutates the sandbox's cache and posts
no intent. Call setPosition with a new tuple.
Bad input is coerced, not rejected. The sandbox turns each element into a number and replaces any non-finite
result with 0; an array shorter than three elements is dropped entirely — setPosition posts nothing at all,
and SpawnObjectOptions.position falls back to [0, 1, 0].
Rotations are absolute, not relative. setRotation([0, 90, 0]) faces the entity at 90°; it does not turn it
by 90°. rotate() is the relative quarter-turn.
See also#
ObjectData.position— the read side.ObjectHandle.setPosition— the write side, and its coercion rules.SpawnObjectOptions.position— the default when you omit it.Vector3— the mod-side shape, for comparison.- Choosing a surface — why the two surfaces differ at all.
ObjectKind#
Surface A — table script · type
The kinds of objects that can exist on a DiceyTable table.
declare type ObjectKind =
| "card" | "deck" | "die" | "token" | "board" | "bag" | "custom" | "card-holder" | "button" | "table" | "coin" | (string & {});
What kind of thing an entity is. It is the value of ObjectData.kind, the required field of
SpawnObjectOptions, and the filter world.getAllObjects({ kind }) narrows on. The union names all eleven kinds and
then opens up with (string & {}), which keeps autocomplete useful while still accepting any string.
How, why and when to use it#
Almost every action behaves differently by kind — shuffle reorders a deck and is refused outright on a bag,
draw does nothing at all to a die — so branching on kind is how a script that operates on whatever is on the table
avoids doing something absurd. The alternative is tagging entities yourself at authoring time and filtering on
the tag, which is better whenever your rule is about this game's categories ("scoring die", "player marker")
rather than the platform's. Use kind for platform behavior, tags for game meaning; world.getAllObjects
accepts either.
Example#
// content/scripting-api/examples/objectkind.ts
// Scene script: kind decides what an entity will do with an action, so branch
// on it before acting. An unrecognized kind is silently replaced with
// "custom" at spawn time, so read the kind back when it comes from data.
const KINDS: ObjectKind[] = ["card", "deck", "die", "token", "board", "bag", "custom", "card-holder", "button", "table", "coin"];
async function actByKind(): Promise<void> {
const entities = await world.getAllObjects();
const counts = new Map<string, number>();
for (const entity of entities) {
counts.set(entity.kind, (counts.get(entity.kind) ?? 0) + 1);
if (entity.kind === "die") {
entity.roll();
} else if (entity.kind === "deck") {
// Only a deck shuffles: a bag draws at random, so it has no order to change.
entity.shuffle();
}
}
for (const kind of KINDS) {
world.log(`${kind}: ${counts.get(kind) ?? 0}`);
}
}
async function spawnFromData(requested: string): Promise<void> {
// `requested` came from data, so it may be a typo. The union's (string & {})
// arm lets it compile; the sandbox replaces anything unknown with "custom".
const entity = await world.spawnObject({ kind: requested, name: "spawned", position: [0, 1, 2] });
world.log(entity === null ? "Spawn request was malformed." : `Requested "${requested}", got back "${entity.kind}".`);
}
void actByKind();
void spawnFromData("button");
void spawnFromData("dice"); // typo -> "custom"
The script console prints one line per kind — card: 52, deck: 1, die: 2, and zeros for the rest — followed
by Requested "button", got back "button". and Requested "dice", got back "custom".
Gotchas#
The union names all eleven kinds, card-holder, button, table and coin included, and matches
TABLE_OBJECT_KINDS (packages/shared/src/tableObjects/kinds/index.ts) and the sandbox's own accepted list
(apps/web/src/scripting/sandbox/tableScriptSandbox.html, KNOWN_KINDS). It named fewer once —
card-holder was added alongside the per-kind handle types, button with the button object, table with the
table entity and coin with the coin kind — but a script
written against an older declaration compiled anyway, because of the (string & {}) arm below.
An unrecognized kind becomes "custom", silently. The sandbox checks the spawn's kind against its list of
eleven and substitutes "custom" for anything else — no error, no console line. A typo such as "dice" produces
a plain custom entity that never rolls. Read handle.kind back when the kind comes from data rather than a
literal, as the example does.
The (string & {}) arm is what makes the typo compile. It exists so a future kind is usable before the
declaration catches up; the cost is that TypeScript cannot catch a misspelling for you.
kind is fixed at spawn. Nothing in the table-scripting API changes an existing entity's kind.
See also#
ObjectData.kind— reading it back off a handle.SpawnObjectOptions.kind— the required field, and its coercion.world.getAllObjects— filtering by kind or by tag.- Object kinds — what each of the eleven kinds is and how it behaves.
- Action vocabularies — which actions do something on which kind.
ObjectAction#
Surface A — table script · type
Actions a script can REQUEST on an object (host-validated allowlist).
declare type ObjectAction =
| "flip" | "rotate" | "lock" | "unlock" | "tap" | "untap"
| "shuffle" | "draw" | "deal" | "split" | "combine" | "roll" | "delete";
The 13 action names a table script is allowed to request. The union is mirrored exactly by the host's
allowlist (apps/web/src/scripting/TableScriptHost.ts, SCRIPT_SAFE_OBJECT_ACTIONS), which re-checks every
object-action intent the sandbox posts. It is the vocabulary behind the nine ObjectHandle methods that post
actions. What an event delivers is the wider
ObservedObjectAction — request and observe are deliberately
two types.
How, why and when to use it#
You are looking for the method that taps a card, or annotating a helper that takes an action you are about to request. This is the type for the second case and a misleading answer to the first, so read the Gotcha before you rely on it. When you need the authoritative comparison — what the engine has, what a script may ask for, what a mod may ask for — go to Action vocabularies, which owns that table; this entry is only about the declared union.
Example#
// content/scripting-api/examples/objectaction.ts
// Scene script: the union names 13 actions, and only 9 of them have a method
// on ObjectHandle. Map the callable ones explicitly rather than assuming a
// method exists for every name in the type.
const CALLABLE: ObjectAction[] = ["flip", "rotate", "lock", "unlock", "shuffle", "draw", "deal", "roll", "delete"];
const NO_METHOD: ObjectAction[] = ["tap", "untap", "split", "combine"];
function perform(entity: ObjectHandle, action: ObjectAction): boolean {
switch (action) {
case "flip": entity.flip(); return true;
case "rotate": entity.rotate(); return true;
case "lock": entity.lock(); return true;
case "unlock": entity.unlock(); return true;
case "shuffle": entity.shuffle(); return true;
case "draw": entity.draw(); return true;
case "deal": entity.deal(); return true;
case "roll": entity.roll(); return true;
case "delete": entity.destroy(); return true;
default: return false;
}
}
async function demonstrate(): Promise<void> {
const decks = await world.getAllObjects({ kind: "deck" });
const deck = decks[0];
if (!deck) {
world.log("Add a deck to the table and restart the scripts.");
return;
}
world.log(`${CALLABLE.length} callable actions, ${NO_METHOD.length} with no method: ${NO_METHOD.join(", ")}.`);
world.log(`shuffle dispatched: ${String(perform(deck, "shuffle"))}; tap dispatched: ${String(perform(deck, "tap"))}.`);
}
void demonstrate();
The script console prints 9 callable actions, 4 with no method: tap, untap, split, combine. and then
shuffle dispatched: true; tap dispatched: false.
Gotchas#
Known gap. Four of the 13 have no method on ObjectHandle: tap, untap, split and combine. They are
in the union and the host's allowlist accepts them, so every layer below the typed API is ready — only the
calling surface is missing (packages/shared/src/scripting.ts). delete looks like the same problem and is
not: it is reachable, as destroy(). Until a method exists, model tapping as your own state — a tag, or saved
data — and read it back with handle.refresh().
See Known limitations.
It is not the type an event hands you. onObjectAction and ObjectHandle.onAction are declared with
ObservedObjectAction, which adds the 14 engine
actions a script may only observe — lift, flick, press, toss, peek, the three search*, the three
reveal-*, tip-out, empty and clear-source. Passing an observed action into a helper typed
ObjectAction does not compile, which is the point — narrow first.
The engine actions missing from the union are a deliberate boundary, not an oversight. lift and
flick are drag mechanics driven by pointer input, press and toss are a player's own click on a button or a
coin, peek, search* and reveal-* are hidden-information reveals the host must own, and tip-out, empty
and clear-source manage a container's contents. Action vocabularies explains why.
An action the host refuses is dropped with a diagnostic and nothing else. The intent never reaches the runtime, no event fires, and the only signal is a line in the script console.
See also#
- Action vocabularies — the three vocabularies compared, and which asymmetries are deliberate.
ObjectHandle— the nine methods that post an action.ObservedObjectAction— the wider union an event delivers.globalEvents.onObjectAction— the delegate that delivers the wider one.ObjectHandle.destroy— the method whose name differs from its action.- Known limitations — the full list of documented gaps.
ObservedObjectAction#
Surface A — table script · type
Actions an onAction / onObjectAction handler can OBSERVE. Wider than
ObjectAction: the engine also raises the drag mechanics (lift,
flick) and the hidden-information reveals, which a script may watch but
may not request. Write a default branch; do not rely on a never check.
declare type ObservedObjectAction =
| ObjectAction
| "lift" | "flick" | "reveal-all" | "reveal-team-a" | "reveal-team-b" | "press" | "peek"
| "search" | "search-pull" | "search-close"
| "toss"
| "tip-out" | "empty" | "clear-source";
The 27 action names an action handler can receive — every action the engine has. It is
ObjectAction — the 13 a script may request — plus the 14 the engine
raises but no script can ask for: lift, flick, press, toss, peek, search, search-pull,
search-close, reveal-all, reveal-team-a, reveal-team-b, tip-out, empty and clear-source. Both
action delegates are declared with it:
globalEvents.onObjectAction
and ObjectHandle.onAction.
How, why and when to use it#
You are writing a handler and want to know which strings can actually arrive, so that a switch over them is not
quietly wrong. This is that list, and it is the reason there are two action types rather than one: request and
observe are different vocabularies, and collapsing them would either hide real events or advertise calls that
the host's allowlist refuses. Annotate a helper with ObservedObjectAction when it takes an action off
an event; annotate it with ObjectAction when it takes one you are about to request. The authoritative comparison
of all three vocabularies — engine, table script, mod — is on
Action vocabularies; this entry is only about the declared union.
Example#
// content/scripting-api/examples/observedobjectaction.ts
// Scene script: an action handler observes more names than a script may
// request. Split the two vocabularies explicitly, then keep a default branch
// for anything the engine gains later.
const OBSERVE_ONLY: ObservedObjectAction[] = [
"lift",
"flick",
"press",
"peek",
"search",
"search-pull",
"search-close",
"reveal-all",
"reveal-team-a",
"reveal-team-b",
"toss",
"tip-out",
"empty",
"clear-source"
];
function isObserveOnly(action: ObservedObjectAction): boolean {
return OBSERVE_ONLY.includes(action);
}
globalEvents.onObjectAction.add((entity, action, context) => {
if (isObserveOnly(action)) {
world.log(`${context.actor} caused ${action} on ${entity.id} - observed, never requestable.`);
return;
}
switch (action) {
case "flip":
world.log(`${entity.id} was flipped by ${context.actor}.`);
break;
case "shuffle":
world.log(`${entity.id} was shuffled by ${context.actor}.`);
break;
case "delete":
world.log(`${entity.id} is going away.`);
break;
default:
// A name this script does not handle - including one added to the engine
// after it was written - lands here instead of falling through silently.
world.log(`${entity.id}: unhandled action ${action}.`);
break;
}
});
world.log("Action observer is running.");
Dragging a card prints a1b2c3d4 caused lift on obj-3 - observed, never requestable.; flipping it prints
obj-3 was flipped by a1b2c3d4.
Gotchas#
Write a default branch anyway. The union is complete for the engine as it stands, but the payload the
runtime sends is a plain string typed as the engine's own action list. The two lists live in different files
(packages/shared/src/scripting.ts, packages/shared/src/tableObjects/intents.ts). A repository test keeps them
in step, but your script can still run against an engine newer than the editor it was written in. A never
check that proves your switch exhaustive today becomes a compile error the day an action is added. That is
fine. A handler with no default becomes silently wrong instead, which is not. toss is the most recent
example: a handler written before it shipped receives it as a name it never listed.
The observe-only names are a deliberate boundary, not an oversight. lift and flick are drag mechanics
driven by pointer input. press is a button's own click. toss is a player's coin flip, which a coin's own script also hears as
CoinObject.onTossed; a script that wants a
random result should pick one itself rather than throw a coin and wait for it to land. peek, the three
search* actions and the three reveal-* actions are hidden-information reveals the host must own — see
DeckObject.onSearched for what a search event does and
does not carry. tip-out, empty and clear-source are container management; empty and clear-source are
host-only even for players. Asking for any of them is not a type error — the escape hatch is a different type. The
host's allowlist refuses it, dropping the intent with a diagnostic in the script console and no event.
It is an observe type only. Passing an ObservedObjectAction where an ObjectAction is expected does not
compile, which is the point. Narrow first, as the example does.
See also#
ObjectAction— the 13 a script may request, and the four with no method.DeckObject.onSearched— the threesearch*observe-only names, and why they are observe-only.globalEvents.onObjectAction— the table-wide delegate declared with this type.ObjectHandle.onAction— the entity-scoped one.- Action vocabularies — engine, table script and mod compared.
- Events and delegates — ordering, multiplicity and cancellation.
ObjectDestroyedReason#
Surface A — table script · type
Why an entity was destroyed, on EventContext.reason of an
onObjectDestroyed / onDestroyed event. There are four removal paths and
only one of them is somebody asking for it:
"deleted"— thedeleteaction was applied (a menu, a peer, or a script'sdestroy())."depleted"— the last card was drawn off a deck and the empty deck went."converted"— a one-card deck became a plain card; the deck entity went. The card that replaces it raises its ownonObjectCreated."absorbed"— acombinefolded the entity into a stack.context.containerIdnames the surviving stack that took its cards.
Write a default branch: this union grows when the engine grows a removal path.
declare type ObjectDestroyedReason = "deleted" | "depleted" | "converted" | "absorbed";
The four ways an entity can leave the table, on context.reason of an
onObjectDestroyed or
onDestroyed event. Only one of them —
"deleted" — is somebody asking for the entity to go; the other three are the runtime tidying up after a
draw or a merge, and two of them mean the cards are still in play inside something else.
Returns#
"deleted" | "depleted" | "converted" | "absorbed". Each value corresponds to exactly one runtime path
(apps/web/src/playcanvas/TabletopRuntime.ts):
| Value | What happened | Raised by | containerId |
|---|---|---|---|
"deleted" |
The delete action was applied — a menu, a peer's intent, or a script's destroy(). |
applyObjectAction |
absent |
"depleted" |
The last card was drawn off a deck, so the empty deck was removed. Nobody asked to delete it. | removeDepletedDeck |
absent |
"converted" |
A one-card deck became a plain card. The deck entity went; the card raises its own onObjectCreated. |
convertDeckToLastCard |
absent |
"absorbed" |
A combine folded the entity into a stack. Its cards survive inside the survivor. |
combineIntoStack, mergeCardLikeIntoDeck |
the surviving stack's id |
Applies to: every object kind. "depleted" and "converted" can only ever describe a deck, and
"absorbed" only a card or a deck, but nothing stops a future kind reaching the same paths — branch on
the value, not on the kind you expect.
How, why and when to use it#
You are keeping a set of the entities in play, and a player drags two cards together. Before this discriminator
existed, the merge either raised nothing at all or looked identical to a delete, so your set drifted — the two
cards were "gone" while their faces were sitting in a pile that could still be drawn from. reason is what makes
the difference readable: on "absorbed" the contents survive and
EventContext.containerId tells you where they went; on
"deleted" they do not.
The other real use is attribution. "depleted" and "converted" are the runtime cleaning up after a draw, so a
"who removed my deck?" message that fires on them is wrong. Check the reason first, then read
EventContext.actor.
Example#
// content/scripting-api/examples/objectdestroyedreason.ts
// Scene script: an entity can leave the table four ways and only one of them is
// somebody asking for it. Branch on context.reason before you treat a
// disappearance as a loss - a card absorbed into a pile is still in play.
const inPlay = new Set<string>();
globalEvents.onObjectCreated.add((entity) => {
inPlay.add(entity.id);
});
globalEvents.onObjectDestroyed.add((entityId, context) => {
inPlay.delete(entityId);
const reason: ObjectDestroyedReason | undefined = context.reason;
switch (reason) {
case "absorbed":
// Still in the game, just inside something else now.
world.log(`${entityId} was folded into ${context.containerId ?? "an unnamed stack"}.`);
break;
case "depleted":
world.log(`${entityId} was an empty deck and went away on its own.`);
break;
case "converted":
// The replacement card raises its own onObjectCreated, so `inPlay` is
// already correct by the time anyone reads it.
world.log(`${entityId} was a one-card deck and became a card.`);
break;
case "deleted":
world.log(`${context.actor} removed ${entityId}.`);
break;
default:
// A reason this script does not know - including one added to the engine
// after it was written - lands here instead of being silently ignored.
world.log(`${entityId} left the table for an unrecognised reason: ${String(reason)}.`);
break;
}
});
world.log("Lifetime tracker is running.");
Dropping one card onto another prints two was folded into lines — one per absorbed card, both naming the new
deck. Drawing a deck down to nothing prints was an empty deck and went away on its own.
Gotchas#
An absorbed entity is gone; its card is not. This is the product rule and it is not negotiable: a card
absorbed into a deck and later drawn back out is a new entity with a new id. Entity ids are not preserved
across a merge and never will be — a preset deck's 52 cards were never entities in the first place, so no
contract could hold uniformly. Reconnect on card identity: the cardId in the deck's metadata.cards
entries, which survives absorb → shuffle → draw, and the label the drawn card is created with. A Map keyed on
entity id is the wrong data structure for anything that has to survive a merge.
Write a default branch. The union is complete for the engine as it stands, and the payload is a plain
string that arrives across a postMessage boundary. A never check that proves your switch exhaustive today
becomes a compile error the day a removal path is added, which is fine; a handler with no default becomes
silently wrong instead, which is not.
reason is optional in the type. It is declared reason?: ObjectDestroyedReason on
EventContext because the same context object is passed to every
other event, where it is undefined. Inside a destroy handler the sandbox always fills it.
"converted" is two events, not one. The deck's onObjectDestroyed and the replacement card's
onObjectCreated are separate fan-outs. Nothing links them for you except the position they share.
See also#
EventContext.reason— the field this type lives on.EventContext.containerId— the surviving stack, on"absorbed".globalEvents.onObjectDestroyed— the table-wide delegate.ObjectHandle.onDestroyed— the entity-scoped twin.- Events and delegates — the per-action ordering table, including
combine.
ObjectClickContext#
Surface A — table script · interface · 2 members
Who clicked an entity, on onObjectClicked / onClicked. An EventContext plus the
clicker's seat, which the host reads from its own roster — never from the clicker.
What globalEvents.onObjectClicked and
ObjectHandle.onClicked pass last: an
EventContext with two more fields, the clicker's
seat and the
input the click came from.
How, why and when to use it#
A click means whatever your game says it means, and almost every meaning depends on who clicked: the
defending seat picking a reaction, the player whose turn it is choosing a target. seat answers that directly,
so a click handler rarely needs actor at all. Compare context.seat with the seat your rules are waiting on,
and return early for anyone else.
The seat can be trusted because the clicker never sends it. A player's browser sends only "I clicked this
entity"; the host looks the sender up in its own roster and fills in seat itself.
Gotchas#
seat can be null. Spectators have no seat, and neither does a host who has not taken one. Decide what a
seatless click does (usually nothing) before you compare.
actor is still here and still mostly a peer id. It follows the same rules as on every other event; see
EventContext.actor.
A fresh object per event. Copy the strings out if you need them later, as with every EventContext.
See also#
globalEvents.onObjectClicked— the event that passes it.ObjectHandle.onClicked— the same click, on one entity.EventContext— the fields it inherits.- Highlights and clicks — the guide.
Members#
| Signature | Description | Returns |
|---|---|---|
seat |
The clicker's seat ("red", …), or null for a spectator or a host without a seat. |
string | null |
input |
How the click was made. Informational: treat all three alike. | "mouse" | "touch" | "vr" |
objectclickcontext.seat#
readonly seat: string | null;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The clicker's seat ("red", …), or null for a spectator or a host without a seat.
The seat of the player who clicked ("red", "blue", …), or null for a spectator or a host without a seat.
The host reads it from its own roster when the click arrives; the clicker's browser never supplies it.
Returns
string | null.
How, why and when to use it
Use it to decide whether a click counts. In a reaction window, only the deciding seat's clicks should open a
prompt; on a turn, only the active seat's. Compare it with the seat your rules are waiting for, or with
world.getTurn().seats, and pass it straight to
ui.prompt, which asks one seat.
Gotchas
Check for null first. A spectator can click as freely as a player: the click still reaches your handler,
with no seat.
It is the seat when the host received the click. A player who changes seat afterwards does not change an event already delivered.
Seat, not owner. It says who clicked, not whose entity it is. A player can click an opponent's card on the table; your handler decides whether that means anything.
See also
ObjectClickContext— the object it lives on.ui.prompt— ask that seat what the click should do.
objectclickcontext.input#
readonly input: "mouse" | "touch" | "vr";
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
How the click was made. Informational: treat all three alike.
How the click was made: "mouse", "touch" (a tap) or "vr" (a VR controller or hand).
Returns
"mouse" | "touch" | "vr".
How, why and when to use it
It is informational. Your rules should treat all three alike: a player on a phone and a player in VR are playing the same game. Use it for logging, or to word a message ("tap" rather than "click" in a hint).
Gotchas
Do not gate rules on it. Nothing in a game should be possible with a mouse and impossible on a phone.
An AI agent's click reports "mouse". The table_click tool
clicks the way the user's mouse would.
See also
ObjectClickContext— the object it lives on.- Highlights and clicks — what each input counts as a click.
HighlightStyle#
Surface A — table script · type
An object-highlight style: one of the three built in — "target" (red-orange: being aimed
at), "active" (gold, pulsing: acting now, e.g. attacking), "playable" (mint: you could
play or use this) — or one your game defines in the editor (Game row ▸ HIGHLIGHT STYLES), which
may also restyle the three built-ins. Lowercase letters, digits and -.
declare type HighlightStyle = "target" | "active" | "playable" | (string & {});
The name of an outline style, as world.setHighlight and
ClearHighlightsOptions.style take it: one of the three
built-ins, or a style your game defines in the editor.
| Style | Look | Meaning |
|---|---|---|
"target" |
red-orange #ff5a36, width 1.25, steady |
Being aimed at. |
"active" |
gold #ffc83d, width 1.25, pulses |
Acting now, for example attacking. |
"playable" |
mint #2ee6a6, width 1, intensity 0.9, steady |
You could play or use this. |
How, why and when to use it#
Pick a style by what it means in your game, not by its colour. The three built-ins cover most card and
board games: the attacker is active, what it attacks is target, and the cards a player could use right now
are playable.
When a game needs more meanings (exhausted, blocked, chosen), add a style in the editor's
Highlight Styles section and use its name here. The
same section can restyle a built-in for one game, for example a softer playable on a pale table.
Gotchas#
A name the game does not have is refused. The type accepts any string so that your own names compile, but the host checks the name when you call. An unknown name changes nothing and writes a diagnostic that lists the names this game has.
Names are lowercase letters, digits and -, starting with a letter, at most 32 characters.
The look is fixed when you call. The host resolves the name to its colour, width, intensity and pulse at the moment of the call and stores that look with the outline. Changing the style in the editor affects later calls, not outlines already on the table.
Styles follow the variant. A game's styles are scene data, edited per variant like scene scripts, so one variant can define or restyle them differently from another.
See also#
world.setHighlight— the call that uses it.- Highlight Styles — defining your game's own styles.
- Highlights and clicks — the guide.
HighlightTarget#
Surface A — table script · type
What world.setHighlight outlines: entity ids or handles.
declare type HighlightTarget = string | { readonly id: string };
What world.setHighlight outlines: an entity id, or anything with
an id, such as an ObjectHandle. The call takes one, or a list.
How, why and when to use it#
Pass whatever you already have. Inside an event handler that is usually the handle the event gave you; in rules code that keeps its own state it is usually an id you stored. A list can mix the two.
Gotchas#
Only the id is read. It is not checked against the table when you call: an id the table does not have
draws nothing, and an outline is dropped when its entity leaves the table.
At most 256 per call. A longer list refuses the whole call with a diagnostic. A repeated id counts once.
An id must be a non-empty string of at most 96 characters. Anything else refuses the whole call.
See also#
world.setHighlight— the call that takes it.ObjectHandle— a handle works wherever an id does.
HighlightOptions#
Surface A — table script · interface · 2 members
Options for world.setHighlight.
The optional third argument of world.setHighlight: who sees the
outline (seats) and how long it lasts
(seconds). Leave it out for a public outline that stays
until you clear it.
How, why and when to use it#
Use seats whenever the outline would give away something a player should not know: which cards in a hand are
playable says a lot about that hand. Use seconds for a flash that should not need a cleanup call, such as
marking where a card just landed.
Gotchas#
A private outline is a separate outline. Setting a public outline does not replace a seat's private one on the same entity, or the other way round. A player who has both sees the private one.
A bad option refuses the whole call. A value that is not a seat, or a seconds out of range, changes nothing
and writes a diagnostic.
See also#
HighlightOptions.seats— private outlines.HighlightOptions.seconds— timed outlines.world.setHighlight— the call that takes it.
Members#
| Signature | Description | Returns |
|---|---|---|
seats |
Show the outline ONLY to these seats. Every other player's browser never receives it — use this for anything that depends on hidden information ("the cards in your hand you can play"). | string | readonly string[] |
seconds |
Remove the outline by itself after this many seconds (0.5 to 600). Default: until cleared. | number |
highlightoptions.seats#
seats?: string | readonly string[];
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Show the outline ONLY to these seats. Every other player's browser never receives it — use this for anything that depends on hidden information ("the cards in your hand you can play").
Makes the outline private to these seats: one seat id, or a list. Only those seats' browsers ever receive it; no other player's browser gets so much as a hint that it exists.
Returns
string | readonly string[], optional. Absent: a public outline everyone sees.
How, why and when to use it
This is what makes outlines safe for hidden information. "The cards in your hand you can play" is a fact about
that hand, and drawing it publicly would tell the opponent what you hold. With seats, the outline travels the
same private path as a seat's private Game UI state: it is saved with the table, and each seat's outlines reach
that seat alone. They are never part of the state every player receives.
Gotchas
Seat ids, not peer ids or names. A value that is not a seat refuses the whole call with a diagnostic, and so does an empty list: a private outline is never quietly widened to everyone.
Private wins on screen. A player with both a public and a private outline on one entity sees the private one. Among several outlines of the same kind, the most recent shows.
The host holds every seat's private outlines, as it holds every seat's private Game UI state, because the host keeps the table. The person hosting sees only their own seat's outlines on screen.
See also
ClearHighlightsOptions.seats— clearing one seat's outlines.- Game UI audiences and privacy — the same privacy rule for HUD state.
- Highlights and clicks — the guide.
highlightoptions.seconds#
seconds?: number;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Remove the outline by itself after this many seconds (0.5 to 600). Default: until cleared.
Removes the outline by itself after this many seconds, from 0.5 to 600. Absent: the outline stays until you clear it.
Returns
number, optional.
How, why and when to use it
Use it for a brief flash: where a card just landed, which die a rule just read. It saves a
world.wait followed by a clear, and it cannot be left behind if your
script stops in between.
Gotchas
The host's clock times it. The host removes the outline, so every player sees it go at the same moment; a slow browser does not keep it longer.
A script restart removes timed outlines. When your scripts restart, timed outlines go; outlines without
seconds stay.
Out of range refuses the whole call. Less than 0.5, more than 600, or not a number changes nothing and writes a diagnostic.
See also
HighlightOptions— the other option.world.setHighlight— the call that takes it.
ClearHighlightsOptions#
Surface A — table script · interface · 2 members
Options for world.clearHighlights.
The optional argument of world.clearHighlights: narrow the
clear to one style, to some
seats' private outlines, or both. Leave it out to
remove every outline your game's scripts set.
How, why and when to use it#
Clear by meaning when a phase ends: { style: "playable" } when a reaction window closes,
{ style: "target" } when an attack resolves. Clear by seat when one player's hints are out of date and the
rest of the table's are not.
Gotchas#
Both together narrow twice. { style: "playable", seats: ["red"] } removes only red's private playable
outlines.
Only your game's outlines. Outlines set by another game's or Asset pack's scripts are never touched.
See also#
world.clearHighlights— the call that takes it.world.setHighlight— passingnullclears chosen entities instead.
Members#
| Signature | Description | Returns |
|---|---|---|
style |
Only outlines of this style. | HighlightStyle |
seats |
Only these seats' private outlines. Without it, the public outlines AND every seat's go. | string | readonly string[] |
clearhighlightsoptions.style#
style?: HighlightStyle;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Only outlines of this style.
Clears only outlines of this style: public and private alike, unless
seats narrows it.
Returns
HighlightStyle, optional.
How, why and when to use it
Use it to end one phase of play without disturbing the others: the attack's active and target outlines can
stay while the reaction window's playable ones go.
Gotchas
The name must be one this game has. An unknown style refuses the call with a diagnostic listing the game's style names; nothing is cleared.
It matches the name stored with each outline. Restyling a style in the editor does not change which outlines it clears.
See also
HighlightStyle— the built-in names.world.clearHighlights— the call.
clearhighlightsoptions.seats#
seats?: string | readonly string[];
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Only these seats' private outlines. Without it, the public outlines AND every seat's go.
Clears only these seats' private outlines: one seat id, or a list. Without it, the clear removes the public outlines and every seat's private ones.
Returns
string | readonly string[], optional.
How, why and when to use it
Use it when one player's private hints change and nobody else's do, for example after that player draws a card and you work out again what they can play.
Gotchas
Public outlines are untouched. With seats, only private outlines go; a public target stays.
A value that is not a seat refuses the call with a diagnostic, and so does an empty list.
See also
HighlightOptions.seats— setting private outlines.world.clearHighlights— the call.
ObjectMenuItemRegistration#
Surface A — table script · interface · 6 members
A context-menu entry this script adds to entities on the table.
Registered with world.addObjectMenuItem, drawn BELOW the built-in actions, and reported
back through globalEvents.onObjectMenuItem (or refObject.onMenuItem) when a
player clicks it.
match is data, not a callback#
There is deliberately no "show this when this function returns true". Table scripts run on the
HOST alone, while the context menu is drawn on every peer — so the peer that has to decide
whether to show your item is not running your script, and a function could not cross the
sandbox boundary to reach it anyway. match is a filter the table evaluates for you, on
every peer, against replicated state.
It is AND across the fields you set, OR within objectIds and kinds, and
tagMatch decides within tags. Omit match entirely to target EVERY entity.
For a condition match cannot express — "only on the back rank" — put the test in the
HANDLER, or move the condition into a tag the script maintains.
A context-menu entry a table script contributes to entities on the table, passed to
world.addObjectMenuItem.
Two required fields — an id you choose and a label players read — plus an optional
match that decides which entities it appears on,
and two presentation hints.
How, why and when to use it#
Think of it as a declaration, not a command: you are describing an entry that should exist, and the table
decides moment to moment which entities show it. That is why match is data rather than a callback — the menu
is drawn on every peer, and only the host is running your script, so the filter has to be something a peer can
evaluate on its own.
Everything that depends on game state belongs in the handler instead. See
globalEvents.onObjectMenuItem.
Gotchas#
match is data, not a callback, and every field on this type is plain JSON for the same reason: the
registration is replicated to peers that are not running your script, so nothing on it can be a function.
An invalid registration is dropped rather than thrown. A missing id or label raises an author diagnostic;
anything that fails schema validation is discarded so it cannot poison the replicated snapshot for the table.
See also#
world.addObjectMenuItem— the call that takes it.globalEvents.onObjectMenuItem— the click it produces.
Members#
| Signature | Description | Returns |
|---|---|---|
id |
Your own id for the item, unique within this script. Handed back to the handler, and the key world.removeObjectMenuItem takes. Registering the same id twice REPLACES it, which is how you relabel one. |
string |
label |
The caption on the button. | string |
match |
Which entities the item appears on. Omit for all of them. | { objectIds?: string[]; kinds?: ObjectKind[]; tags?: string[]; /** "all"requires every tag (the default);"any" requires at least one. */ tagMatch?: "all" | "any"; } |
danger |
Draw it as a destructive action, like Delete. | boolean |
order |
Sort order among script items. Script items always follow the built-in actions. | number |
seats |
Offer the item ONLY to players seated in one of these seats. Omit it to offer the item to everyone. | string[] |
objectmenuitemregistration.id#
id: string;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Your own id for the item, unique within this script. Handed back to the handler, and the
key world.removeObjectMenuItem takes. Registering the same id twice REPLACES it,
which is how you relabel one.
Your own identifier for the entry, unique within this script.
Returns
string, required, 1–96 characters.
How, why and when to use it
It comes back to you as the second argument of
onObjectMenuItem, and it is the key
removeObjectMenuItem takes — so pick something you will
recognise in a switch, not a generated id.
Registering the same id twice replaces the entry. That is the supported way to relabel one, or to narrow its
match, without a remove-then-add round trip.
Ids are scoped to the script realm that registered them, so two different scripts may both use "promote"
without colliding, and neither can remove or overwrite the other's.
Gotchas
Registering the same id twice replaces the entry rather than adding a second one. That is the supported way
to relabel an entry or narrow its match; it is also how a script that re-registers on every tick quietly does
nothing instead of hitting the 100-entry cap.
An empty id is refused, with an author diagnostic in the Script Errors tab rather than a silent drop.
Ids are scoped to the script realm. Two scripts may both use "promote"; neither can see, replace or remove
the other's, because the scope is stamped by the host and never taken from your call.
See also
world.addObjectMenuItem— where you set it.world.removeObjectMenuItem— which takes it back.
objectmenuitemregistration.label#
label: string;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The caption on the button.
The caption players see on the menu button.
Returns
string, required, 1–64 characters.
How, why and when to use it
Write it as the verb the player is performing — Promote, Rally, Give to owner — and keep it short: the context menu sits under the pointer and a long label pushes the whole menu off small screens.
An empty label is refused with an author diagnostic rather than drawn as a blank button, and one over 64 characters fails schema validation and is dropped.
Gotchas
An empty label is refused with an author diagnostic, and one over 64 characters fails schema validation and is dropped — the registration never reaches the snapshot, so nothing appears in any player's menu.
It is not an identifier. Labels are for reading; match on
id in the handler, never on the label.
See also
objectMenuItemRegistration.danger— how it is styled.world.addObjectMenuItem— where you set it.
objectmenuitemregistration.match#
match?: {
objectIds?: string[];
kinds?: ObjectKind[];
tags?: string[];
/** `"all"` requires every tag (the default); `"any"` requires at least one. */
tagMatch?: "all" | "any";
};
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Which entities the item appears on. Omit for all of them.
Which entities the entry appears on. Omit it entirely to target every entity on the table.
Returns
An optional object:
| Field | Type | Notes |
|---|---|---|
objectIds |
string[] |
Only these entities, by id. |
kinds |
ObjectKind[] |
Only these kinds. |
tags |
string[] |
Only entities carrying these tags. |
tagMatch |
"all" | "any" |
How tags is read. "all" is the default. |
The fields combine with AND: an entry setting both kinds and tags appears only on entities that satisfy
both. Within objectIds and kinds the values are OR. Within tags, tagMatch decides.
An empty object (match: {}) is the same as omitting it: every entity.
How, why and when to use it
Prefer tags. An id list breaks the moment a piece is re-spawned, and a kind filter is usually too broad —
kinds: ["token"] catches every token on the table, while tags: ["pawn"] catches the ones the rule is about.
Tags also give you a lever for conditions: a script that maintains a promotable tag can make an entry appear
and disappear without touching the registration.
⚠ This is a filter, not a predicate. There is no callback form, and that is deliberate — the peer drawing the menu is not the peer running your script. Conditions over game state go in the handler.
Gotchas
It is a filter, not a predicate, and there is no callback form. Table scripts run on the host alone while the menu is drawn on every peer, so the peer deciding whether to show your entry is not running your script — and a function could not cross the sandbox boundary to reach it anyway. Conditions over game state belong in the handler.
An empty match: {} means every entity, not none. If you meant "nothing for now", remove the entry instead.
It is re-evaluated every time a menu opens, so an entry automatically covers entities spawned after it was registered, and stops covering an entity whose tags change.
The host checks it again on click. A peer's view can be stale and an intent can be forged, so the handler is never reached for an entity the filter excludes.
See also
world.addObjectMenuItem— where you set it.globalEvents.onObjectMenuItem— where runtime conditions go instead.
objectmenuitemregistration.danger#
danger?: boolean;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Draw it as a destructive action, like Delete.
Draw the entry as a destructive action, the way Delete is drawn.
Returns
boolean, optional. Defaults to false.
How, why and when to use it
Set it for entries that discard, remove or otherwise cannot be undone. It changes styling only — nothing confirms on the player's behalf, so an entry that genuinely destroys something should still ask.
Gotchas
It changes styling only. Nothing is confirmed on the player's behalf, and nothing is blocked — an entry that really destroys something should still ask before doing it.
See also
objectMenuItemRegistration.label— the text it styles.world.addObjectMenuItem— where you set it.
objectmenuitemregistration.order#
order?: number;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Sort order among script items. Script items always follow the built-in actions.
Sort order among this table's script entries.
Returns
number, optional integer, 0–100000. Defaults to 0.
How, why and when to use it
Entries sort by order first and then by label, so leaving it unset gives alphabetical order — fine until two
entries have a natural sequence (Promote to Queen before Promote to Knight), which is what this is for.
⚠ It cannot reorder against the built-in actions. Script entries are always drawn below Flip, Lock, Delete
and the rest, whatever order says. A script cannot move, hide or displace the actions a player relies on.
Gotchas
It cannot reorder against the built-in actions. Script entries are always drawn below Flip, Lock, Delete and the rest, whatever this says. A script cannot move, hide or displace the actions a player relies on.
It sorts across scripts, not just your own. Two mods contributing entries to the same entity interleave by
order, so a large number is not a way to claim the bottom of the list reliably.
See also
world.addObjectMenuItem— where you set it.
objectmenuitemregistration.seats#
seats?: string[];
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Offer the item ONLY to players seated in one of these seats. Omit it to offer the item to everyone.
Use it for an action that belongs to one player, above all on a card the others must not know about: "Deploy Luke Skywalker" on a card in your hand would tell your opponent what you hold. A seat-scoped item never reaches the other players at all (it is removed from what their table receives, not just hidden in their menu), spectators never see one, and the host refuses a click from anybody not seated in a listed seat before your handler runs.
Offers the menu entry only to players seated in one of these seats. Leave it out to offer the entry to everyone.
Returns
string[], optional, 1 to 64 seat ids. A list that names no seat drops the entry (with a line in the script log)
rather than offering it to everyone.
How, why and when to use it
For an action that belongs to one player, above all an action on a card the others must not know about. "Deploy Luke Skywalker" on a card in your hand would tell your opponent what you hold.
A seat-scoped entry is hidden information, and it is treated as such three ways: the other players' tables never receive it (it is removed from what the host sends them, not just from their menu); every menu, including the host's own and an AI agent's, offers it only to a listed seat; and the host refuses a click from anybody else before your handler runs. Spectators never see one.
Example
// content/scripting-api/examples/objectmenuitemregistration.seats.ts
// Scene script: a "Deploy" entry on each card in a player's hand, offered to
// that player alone.
//
// The label names the card, so the other players must not receive it: with
// `seats`, the item never reaches them, and the host refuses a click from
// anyone who is not seated in a listed seat.
async function offerDeploys(seat: string): Promise<void> {
const hand = await world.getAllObjects({ kind: "card", seat });
for (const card of hand) {
world.addObjectMenuItem({
id: `deploy-${card.id}`,
label: `Deploy ${card.name ?? "this card"}`,
match: { objectIds: [card.id] },
seats: [seat]
});
}
}
globalEvents.onObjectMenuItem.add((object, itemId, context) => {
if (!itemId.startsWith("deploy-")) {
return;
}
// Only the owning seat could have clicked it: the host checked.
world.log(`${context.actor} deploys ${object.id}.`);
world.removeObjectMenuItem(itemId);
});
void offerDeploys("north");
Gotchas
The exact seat, not the team, and players only. A teammate is not offered another seat's entry, and a spectator is never offered one, even one still holding a seat.
A table with a seat-scoped entry sends each player their own copy of the table, as a table with face-down cards already does. Remove entries you no longer need.
See also
world.addObjectMenuItem: where you set it.
TextLabelOptions#
Surface A — table script · interface · 8 members
A line of text drawn flat on the table, for world.setTextLabel.
A label is not an entity: it has no physics, nobody can pick it up, and it never appears in
world.getAllObjects. It is replicated, so every player sees it. Use one for a score, a
pot total, a phase name, a "your turn" prompt - anything a player should read rather than
handle.
One text label, as world.setTextLabel takes it: text drawn flat
on the table for every player to read.
Three required fields — an id you choose, the
text and a
position in feet — plus five that decide how it looks:
rotationY,
size,
color,
background and
bold.
How, why and when to use it#
Think of it as the whole description of a label, every time. setTextLabel replaces rather than patches, so
the object you pass is what the label becomes: an option you leave out is back at its default, not left as it
was. The practical pattern is one small function per label that builds the full object from your script's
state, called whenever that state changes.
Every field is plain data — strings, numbers, a boolean, a tuple — because the label is replicated to players who are not running your script.
Gotchas#
These eight keys are the whole vocabulary. The host checks the object strictly: a key it does not know — a
misspelt colour, a fontSize borrowed from another API — or a value of the wrong type refuses the whole label
with setTextLabel was ignored: … in the script console. Nothing is dropped quietly and nothing falls back to a
default, so a label that draws is the label you described.
The label is drawn unlit. Its colours read the same in a dark room as in a bright one, and it neither casts nor receives shadows. That is deliberate — a label is information — but it also means a label never looks like it is printed on the felt.
Each player's own machine draws the text, with the fonts it has. Line breaks and sizes are exact; the width of a line can differ slightly from one machine to the next, so do not lay labels out edge to edge.
Photo mode can hide it. Text labels are their own photo-mode category, Text labels, which a player can switch off for a shot.
See also#
world.setTextLabel— the call that takes it, with an example.world.removeTextLabel— taking a label away again.
Members#
| Signature | Description | Returns |
|---|---|---|
id |
Your own id for the label, unique among your game's scripts: 1 to 48 letters, digits, _, -, . or :. Setting the same id again REPLACES the label, which is how you change its text or move it. It is also the key world.removeTextLabel takes. |
string |
text |
What to show, up to 256 characters. A line break starts a new line (8 lines at most). | string |
position |
Where the middle of the text sits, in table space. Use the table surface height for y. | Vec3 |
rotationY |
Yaw in degrees. At 0 the text reads upright for someone on the +Z side of the table looking toward -Z; 180 turns it to face the other side. |
number |
size |
Height of one line of text, in feet. Defaults to 0.12. |
number |
color |
Text colour, #rrggbb. Defaults to white. |
string |
background |
Draw a rounded plate of this colour behind the text. Omit or pass null for bare text. |
string | null |
bold |
Draw the text bold. Defaults to true. |
boolean |
textlabeloptions.id#
id: string;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Your own id for the label, unique among your game's scripts: 1 to 48 letters, digits,
_, -, . or :. Setting the same id again REPLACES the label, which is how
you change its text or move it. It is also the key world.removeTextLabel takes.
Your own identifier for the label.
Returns
string, required: 1–48 characters, each a letter, a digit, _, -, . or :.
How, why and when to use it
It is how you address the label afterwards. Setting the same id again replaces the label — that is the way
to change its text, move it or restyle it — and it is the key
removeTextLabel takes. Pick a name for what the label is
("pot", "round", "score:red"), not for what it currently says.
The : and . are allowed so you can build a family of ids from data: `score:${seat}` gives every seat
its own label with no bookkeeping, and re-running the same line updates the right one.
Gotchas
An id outside the pattern drops the whole label. A space, a slash, an empty string or a 49th character is
refused with setTextLabel was ignored: … rather than being trimmed to fit. Build ids from seat names or your
own keys, not from player display names or card titles.
Ids are unique among your game's scripts, not within one script. The scope is the game the script ships in,
not the script file: two scripts in the same game that both use "score" are writing the same label, and either
can remove it. Scripts shipped by an Asset pack are a separate scope, so their ids cannot collide with the
game's.
It is not an entity id. A label is not an entity, so its id means nothing to
world.getObjectById.
Only new ids count toward the 200-label cap, so re-setting an existing id always works. The 200 is counted across all of the game's scripts, in Edit Mode and at a live table alike.
See also
world.setTextLabel— where you set it.world.removeTextLabel— which takes it back.
textlabeloptions.text#
text: string;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
What to show, up to 256 characters. A line break starts a new line (8 lines at most).
The words the label shows.
Returns
string, required, 1–256 characters. A line break (\n) starts a new line; a label has at most 8 lines.
How, why and when to use it
Write what a player needs at a glance — Pot 240, Round 3 of 5, Red to play — and keep it short: a label is
read from across a table, often at an angle.
Use a line break to stack a caption over a value, as `Total\n${total}` does. Lines are centred on
position, and each one is
size tall.
Gotchas
No formatting. The text is drawn exactly as given: **, [color=…] and HTML are shown as typed. One
colour and one weight apply to the whole label; for two colours, draw two labels.
An empty string drops the label, as does one over 256 characters — with setTextLabel was ignored: …, not a
truncation. To make a label disappear, call
removeTextLabel.
A ninth line does not start a new line. Everything after the seventh line break is joined onto the eighth line with spaces.
A very long line is drawn smaller than size. A label can be at most about 21 times as wide as one line is
tall; a line that needs more room is shrunk to fit rather than cut off. Break it into lines instead.
A non-string is converted, so text: 12 draws 12. TypeScript will not let you write that; a value built
at run time can.
See also
TextLabelOptions.size— how tall each line is.world.setTextLabel— where you set it.
textlabeloptions.position#
position: Vec3;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Where the middle of the text sits, in table space. Use the table surface height for y.
Where the middle of the text sits, in table space.
Returns
Vec3, required: an [x, y, z] tuple in feet. x and z run across the
table and y is height.
How, why and when to use it
Give y the height of the surface the label should lie on, and the label is drawn a hair above it — 0.004 ft —
so it does not flicker against the felt. Where that is depends on the table your game assigns: about y = 2.07 on
Square Table (the default), y = 1.5 on the built-in Dining Table, and wherever its own pack puts it
on any other table.
For a label that belongs beside something, read the position rather than hard-coding it: a
snap point, a
seat zone or an entity's own position gives you coordinates in
the same frame, and offsetting x or z from one of them survives the scene being rearranged.
Gotchas
It is the middle of the text, not a corner. A label grows equally in every direction from position as the
text gets longer or gains lines.
A label does not follow anything. It is fixed at the coordinates you gave it. To keep one beside an entity that moves, set it again when the entity is dropped — not on every tick.
A label below the surface is hidden by it. A y under the table's playing surface draws the label inside
the table, where nobody can see it. If a label does not appear, check y first.
A malformed position refuses the label. Anything that is not an array of at least three finite numbers — a
two-number array, a string in one slot, a NaN from arithmetic that went wrong — drops the whole call with
setTextLabel was ignored: …. Nothing is drawn at the origin instead, and a label already on the table stays
where it was.
It is a tuple, not an { x, y, z } object — like every other coordinate in table scripting. Passing the
object form is refused, not converted.
See also
Vec3— the tuple, and its units.TextLabelOptions.rotationY— which way the text faces.world.getSnapPoints— authored positions to place a label by.
textlabeloptions.rotationY#
rotationY?: number;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Yaw in degrees. At 0 the text reads upright for someone on the +Z side of the table
looking toward -Z; 180 turns it to face the other side.
Which way the text faces: a yaw, in degrees, about the vertical axis.
Returns
number, optional. Defaults to 0.
How, why and when to use it
At 0 the text reads upright for someone on the +Z side of the table looking toward −Z. 180 turns it
round for the player opposite; 90 and 270 face the two ends.
Set it per label to face the seat the label is for — a score in front of each player, each turned toward its owner. For text everyone must read, there is no single right angle: draw the label once per side.
Gotchas
Yaw is the only rotation. A label always lies flat on the table. It cannot be stood upright or tilted toward a camera, and it does not turn to face whoever is looking.
A value that is not a finite number refuses the whole label. "90", null and NaN are not read as 0:
the call is dropped with setTextLabel was ignored: …. Any finite number is accepted, including negatives and
values past 360.
See also
TextLabelOptions.position— where it sits.world.getSeatZones— where each seat is, to face a label toward it.
textlabeloptions.size#
size?: number;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Height of one line of text, in feet. Defaults to 0.12.
The height of one line of text, in feet.
Returns
number, optional, from 0.02 to 4. Defaults to 0.12 — about an inch and a half.
How, why and when to use it
Size a label against the things around it, which are also measured in feet: a standard playing card is about
0.29 ft tall, so the default reads as a caption beside one, 0.2–0.3 as a headline, and anything near 1
as a banner across the table.
A label with several lines is that many times size tall, so a two-line label at 0.2 covers about 0.4 ft.
Gotchas
It is the line height, not the letter height. The type is set at about three-quarters of the line, with
space above and below, so capital letters at size: 0.2 stand nearer 0.1 ft than 0.2.
Out of range drops the label; it is not clamped. 0.01, 5 or 0 is refused with
setTextLabel was ignored: …. Clamp the number yourself if you compute it.
A value that is not a number is refused too. "0.2" and null do not fall back to the default; the call
is dropped with the same line. Leave size out, or pass undefined, to get 0.12.
It is not pixels or points. size: 24 is not a 24-point label — it is out of range.
See also
TextLabelOptions.text— lines, and what happens to a very long one.Vec3— the same unit, for positions.
textlabeloptions.color#
color?: string;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Text colour, #rrggbb. Defaults to white.
The colour of the text.
Returns
string, optional: six-digit hex, #rrggbb, in either case. Defaults to white, #ffffff.
How, why and when to use it
Use it to tie a label to what it describes — a seat's colour for that seat's score, red for a warning — and to
keep it readable against the surface underneath. White is the default because most table surfaces are dark; on a
pale board, set a dark colour or add a background
plate.
Gotchas
Only #rrggbb is accepted. red, #f80, rgb(…) and an eight-digit #rrggbbaa all drop the whole label
with setTextLabel was ignored: …. There is no transparency.
The colour is not lit. It is drawn exactly as given whatever the room's lighting, so a mid-grey that looks subtle in a bright scene glows in a dark one.
A value that is not a string is refused the same way. A number or null does not fall back to white: the
call is dropped with setTextLabel was ignored: …. Leave color out, or pass undefined, to get the default.
See also
TextLabelOptions.background— a plate to read it against.world.setTextLabel— where you set it.
textlabeloptions.background#
background?: string | null;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Draw a rounded plate of this colour behind the text. Omit or pass null for bare text.
A rounded plate drawn behind the text, in the colour you give.
Returns
string | null, optional: six-digit hex, #rrggbb. Omitted or null means bare text, which is the default.
How, why and when to use it
Add a plate when the text has to be readable over something busy — a patterned board, a card layout, a felt close to the text colour. Bare text is lighter on the eye and right for captions on a plain surface.
The plate is sized to the text, with a margin, and grows with it; you do not set its size.
Gotchas
Omitting it removes the plate. Because setTextLabel replaces the whole label, re-setting one without
background draws it bare. Pass the colour every time you want the plate kept.
Only #rrggbb or null is accepted, as for color: any
other string, a number or false drops the whole label with setTextLabel was ignored: …. The plate is opaque;
there is no transparency.
The plate makes the label bigger than the text. Leave room for the margin when you place two labels side by side.
See also
TextLabelOptions.color— the text drawn on it.world.setTextLabel— where you set it.
textlabeloptions.bold#
bold?: boolean;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Draw the text bold. Defaults to true.
Whether the text is drawn bold.
Returns
boolean, optional. Defaults to true.
How, why and when to use it
Leave it on for anything players read from their seats: text lying flat on a table is seen at a shallow angle,
and a heavier weight survives that better. Pass false for secondary text — a caption under a bold value, a
rules reminder — so the two read as different levels.
Gotchas
The default is bold, not regular. Leaving bold out is the same as true; you have to pass false to get
the lighter weight.
It applies to the whole label. For a bold value over a regular caption, draw two labels.
A value that is not a boolean refuses the whole label. bold: "false", bold: 0 and bold: null are not
coerced: the call is dropped with setTextLabel was ignored: … and nothing is drawn or changed.
See also
TextLabelOptions.size— the other way to make text stand out.world.setTextLabel— where you set it.
TooltipVariableValue#
Surface A — table script · type
A tooltip variable's value. Numbers show bare when whole, else rounded to at most two decimal places.
declare type TooltipVariableValue = string | number | boolean;
What a tooltip variable can hold: a string, a number or a boolean. It is what
setTooltipVariable accepts and what
TooltipData.variables hands back, with the type you wrote — a number stays a number.
How, why and when to use it#
Store the value in its natural type and let the tooltip format it. A number is shown bare when it is whole and
rounded to two decimal places otherwise; a boolean is shown as true or false; a string is shown exactly, as
plain text, with no formatting applied to it even if it contains ** or [color=red].
Gotchas#
A string is capped at 200 characters, and a number must be finite — NaN and Infinity are refused, because
they would not survive the JSON a snapshot is sent as. Either refusal arrives as a diagnostic in the script
console and changes nothing.
Control characters are stripped when the value is drawn. A tab becomes a space and a newline disappears, so a variable is always one line of text.
See also#
ObjectHandle.setTooltipVariable— setting one.TooltipOptions.variables— setting several at once.
TooltipData#
Surface A — table script · interface · 5 members
An entity's hover tooltip, as configured. Tooltips are OFF unless something turns them on,
so most entities read tooltip: null.
An entity's hover tooltip as configured — the value of
ObjectData.tooltip whenever the entity has one. Five
read-only fields: enabled, title, description, showDetails and variables. The templates are returned as
written, so {hp} and **bold** are still in them; what a player actually sees is rendered from this on their own
machine when they hover the entity.
How, why and when to use it#
Read it to find out what an author set up before you change it, or to read back a variable the Inspector gave a
starting value. Every field is filled in with its default where the stored configuration leaves it out —
title and description are null, showDetails is true, variables is {} — so you never need to test for
undefined.
Gotchas#
This is the configuration, not the rendered tooltip. The built-in variables and the built-in detail lines are resolved per viewer when the tooltip is drawn, and nothing in this record tells you what they came to.
See also#
ObjectData.tooltip— where you read it.TooltipOptions— the shape you change it with.
Members#
| Signature | Description | Returns |
|---|---|---|
enabled |
Whether the tooltip shows at all. | boolean |
title |
The title template, or null for the entity's name. | string | null |
description |
The description template (formatting and {variables}), or null for none. |
string | null |
showDetails |
Whether the built-in detail lines (die value, card count, counters, owner) show. | boolean |
variables |
The entity's own tooltip variables. | Readonly<Record<string, TooltipVariableValue>> |
tooltipdata.enabled#
readonly enabled: boolean;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Whether the tooltip shows at all.
Whether hovering the entity shows its tooltip. false means the tooltip has been written and switched off: its
text and variables are still stored, and switching it back on shows them again unchanged.
How, why and when to use it
Test it before switching a tooltip on, so your script does not overwrite an author's decision to leave one off — or, the other way round, to find out whether the text you are about to update is currently visible to anyone.
Gotchas
An entity with no tooltip at all has no TooltipData. handle.tooltip is null then, so read
handle.tooltip?.enabled === true rather than handle.tooltip.enabled.
It controls hover, and nothing else. A disabled tooltip still replicates and can still be read and written by a script.
See also
TooltipOptions.enabled— changing it.ObjectData.tooltip— the record this is on.
tooltipdata.title#
readonly title: string | null;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The title template, or null for the entity's name.
The tooltip's title template, as written — variables like {name} still unsubstituted.
Returns
string | null. null means no title has been set, and the tooltip uses the entity's name as its title: its
displayName, or its label when it has none.
How, why and when to use it
Read it when you want to extend a title rather than replace it, or to check whether an author has given the entity a title of its own before your script sets one.
Gotchas
Titles take variables only. {name} and {name|fallback} are substituted; **, * and [color=…] are
shown exactly as typed. Formatting belongs in the description.
See also
TooltipOptions.title— changing it.- TOOLTIP template syntax — what a template may contain.
tooltipdata.description#
readonly description: string | null;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The description template (formatting and {variables}), or null for none.
The tooltip's description template, as written — formatting markers and {variables} still in it. It is drawn
under the title and above the built-in detail lines.
Returns
string | null. null means the tooltip has no description, so it shows the title and, unless they are turned
off, the built-in detail lines.
How, why and when to use it
Read it to find out what an author wrote before your script adds to it or replaces it. When the only thing that
changes during play is a number or a name inside the text, you do not need to touch the description at all — put
a {variable} in it once and change the variable.
Gotchas
It is the template, not what a player reads. **Range** {range} ft comes back exactly like that; it is
rendered — bold, colour, bullets, variables substituted — separately for each player when they hover.
See also
TooltipOptions.description— changing it.- TOOLTIP template syntax — bold, italic, colour, bullets and variables.
tooltipdata.showDetails#
readonly showDetails: boolean;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Whether the built-in detail lines (die value, card count, counters, owner) show.
Whether the tooltip adds the built-in detail lines under the description: a die's Value, a deck's Cards count
and the card showing on it, a bag's Contents count, the entity's overlay values and counters, Locked, and
Owner. true unless an author or script has turned them off.
How, why and when to use it
Check it when your description already says what the details would — a description that reads
{count} cards left makes the built-in Cards: line a duplicate, and the fix is showDetails: false.
Gotchas
Only lines that apply are drawn. A die that is still tumbling has no Value line, an unlocked entity has no
Locked line, and a player not entitled to a hidden card's identity sees none of it. true is permission to show
the details, not a promise that there are any.
See also
TooltipOptions.showDetails— changing it.
tooltipdata.variables#
readonly variables: Readonly<Record<string, TooltipVariableValue>>;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The entity's own tooltip variables.
The entity's own tooltip variables, by name, with the types they were stored as. An entity with no variables
reads {}. The record is a copy: writing into it changes nothing on the table.
How, why and when to use it
Read a value back before changing it — to add one to a counter an author started at 3 in the Inspector, for
example — rather than keeping a second copy of the number in your script that an author's edit can silently
invalidate.
Gotchas
The built-ins are not in it. name, kind, value, count, owner, counters.<key> and values.<key> are
worked out when the tooltip is drawn and never stored here. A variable of your own with one of those names is
here, and it replaces the built-in in every template on this entity.
See also
TooltipOptions.variables— changing several at once.ObjectHandle.setTooltipVariable— changing one.
TooltipOptions#
Surface A — table script · interface · 5 members
A change to an entity's tooltip. Every field is optional and only the ones you pass
change; null clears a field back to its default, and a null variable deletes it.
What setTooltip() accepts: a patch to an entity's
tooltip. Every field is optional and only the ones you pass change. null puts a field back to its default, and a
null inside variables deletes that one variable.
How, why and when to use it#
Pass the least you mean. { enabled: false } hides a tooltip and keeps its text; { variables: { hp: 4 } }
changes one number and leaves the wording alone; a full object with every field is for the first time you set a
tooltip up. Because unnamed fields are left alone, two scripts can share one entity's tooltip without either
wiping out the other's part.
Gotchas#
Unknown keys are refused, not ignored. The host checks the patch against a strict schema, so descripton, or
any other key that is not one of the five, rejects the whole call with a diagnostic in the script console.
TypeScript catches most of these at compile time; a value built at run time is where they slip through.
Leaving a field out and passing undefined are the same. Neither changes anything. Only null clears.
See also#
ObjectHandle.setTooltip— the call that takes it, with an example.TooltipData— the shape you read back.
Members#
| Signature | Description | Returns |
|---|---|---|
enabled |
boolean |
|
title |
A title template — variables only, no formatting. null = use the entity's name. | string | null |
description |
A description template. **bold**, *italic*, [color=red]...[/color] (or a #rrggbb colour), - bullets and line breaks; {name} or {name|fallback} inserts a variable. null = no description. |
string | null |
showDetails |
Show the built-in detail lines. null resets to the default (shown). | boolean | null |
variables |
Variables to set (merged into the existing ones); a null value deletes that variable. | Record<string, TooltipVariableValue | null> |
tooltipoptions.enabled#
enabled?: boolean;
| Badge | Value |
|---|---|
| Authority | host-authoritative |
| Timing | sync |
| Capability | none |
| Availability | both |
Turns the tooltip on (true) or off (false). Off keeps the title, description and variables, so turning it
back on restores the same tooltip.
Returns
Accepts a boolean, optional. Leave it out to keep the current setting. There is no null for this field: an
entity without a tooltip is off already.
How, why and when to use it
Tooltips are off by default, so pass enabled: true the first time you give an entity one — without it the text
is stored and nobody sees it. Afterwards, toggling enabled on its own is the cheap way to show and hide a
tooltip during play: a hint that should appear only in the first round, a label that matters only while a piece is
in a certain zone.
Gotchas
Off-and-empty removes the tooltip. Switching off a tooltip that has no title, description, variables or
showDetails: false leaves nothing worth storing, so the field is dropped and handle.tooltip reads null.
See also
TooltipData.enabled— reading it.ObjectHandle.setTooltip— the call this belongs to.
tooltipoptions.title#
title?: string | null;
| Badge | Value |
|---|---|
| Authority | host-authoritative |
| Timing | sync |
| Capability | none |
| Availability | both |
A title template — variables only, no formatting. null = use the entity's name.
The tooltip's title template: one line of text, with {name} and {name|fallback} replaced by variables.
Returns
Accepts a string of at most 120 characters, null, or nothing. null clears the title so the tooltip shows
the entity's name (its displayName, or its label when it has none); leaving it out keeps the current title. A
blank string behaves like null.
How, why and when to use it
Set a title when the entity's name is not what a player needs to see first — {faction} scout rather than
scout-token-3, or a card title that includes its cost. Leave it unset to keep the entity's own name, which is
what most tooltips want.
Gotchas
No formatting. **, * and [color=…] in a title are shown exactly as typed, and a newline becomes a
space. Put formatted text in the description.
A title over 120 characters is refused, not truncated — with a diagnostic in the script console, and nothing else in the same patch applied.
See also
TooltipData.title— reading it.- TOOLTIP template syntax — variables and fallbacks.
tooltipoptions.description#
description?: string | null;
| Badge | Value |
|---|---|
| Authority | host-authoritative |
| Timing | sync |
| Capability | none |
| Availability | both |
A description template. **bold**, *italic*, [color=red]...[/color] (or a
#rrggbb colour), - bullets and line breaks; {name} or {name|fallback}
inserts a variable. null = no description.
The tooltip's description template, drawn under the title. It supports **bold**, *italic*,
[color=red]…[/color] (a named colour or #rgb / #rrggbb), bullet lines starting - , line breaks, and
{name} / {name|fallback} variables.
Returns
Accepts a string of at most 1,000 characters — formatting markers included — null, or nothing. null
removes the description; leaving it out keeps the current one. A blank string behaves like null.
How, why and when to use it
Use the description for what a player needs to know about the piece that its name and the built-in details do not
say: what a card does, what a board's spaces mean, a unit's stats. Write it with {variables} for the parts that
change during play, so later updates are one
setTooltipVariable call each instead of a
rewrite of the whole text.
Gotchas
Styles end at every line break. An unclosed ** bolds the rest of its own line and no further, so one typo
cannot bold a whole card.
Variable values are never formatted. A variable whose value is **big** shows the asterisks. Formatting comes
from the template only, so whoever writes the description decides how the tooltip looks, whatever a variable
contains.
Over 1,000 characters is refused, with a diagnostic in the script console and nothing else in the same patch applied.
See also
TooltipData.description— reading it.- TOOLTIP template syntax — the full syntax, with escapes and colour names.
tooltipoptions.showDetails#
showDetails?: boolean | null;
| Badge | Value |
|---|---|
| Authority | host-authoritative |
| Timing | sync |
| Capability | none |
| Availability | both |
Show the built-in detail lines. null resets to the default (shown).
Whether the built-in detail lines — a die's value, a deck's card count, overlay values and counters, Locked,
Owner — appear under the description.
Returns
Accepts a boolean, null, or nothing. null resets to the default, which is shown; leaving it out keeps
the current setting.
How, why and when to use it
Turn the details off when your description already covers them or when they are noise for this piece — a scenery
board does not need Locked under its rules. Leave them on for dice and decks, where the value or count is usually
the reason anyone hovers.
Gotchas
Off hides every built-in line together. There is no way to keep a die's value and drop its Owner line. If
you need a subset, turn the details off and put the ones you want in the description with the built-in variables
{value}, {count}, {owner}, {counters.<key>} and {values.<key>}.
See also
TooltipData.showDetails— reading it, and the full list of lines.
tooltipoptions.variables#
variables?: Record<string, TooltipVariableValue | null>;
| Badge | Value |
|---|---|
| Authority | host-authoritative |
| Timing | sync |
| Capability | none |
| Availability | both |
Variables to set (merged into the existing ones); a null value deletes that variable.
Variables to set on the entity, by name. They are merged into the variables it already has: names you pass are
set, a name whose value is null is deleted, and every name you do not mention is left alone.
Returns
Accepts a Record<string, TooltipVariableValue | null>, optional. Each name is a letter or _ followed by up to
31 letters, digits or _; each value is a string of at most 200 characters, a finite number, or a boolean.
How, why and when to use it
Set several variables in one call when they change together — a unit's hp and status after an attack — so the
table receives one change instead of one per variable. To change a single one,
setTooltipVariable is the same thing with
less punctuation.
Gotchas
There is no "replace all". Passing {} changes nothing. To clear variables you must name each one with
null.
One bad entry rejects the whole call. An invalid name (hp-max, 2nd, anything with a dot) or an
over-long value is reported as a diagnostic in the script console, and none of the patch is applied — not even the
valid entries or the other fields.
32 is the ceiling per entity, counted after the merge. A call that would leave more than 32 variables on the entity is refused whole, with an error in the script console.
See also
TooltipData.variables— reading them back.TooltipVariableValue— what a value may be.
ObjectActionOptions#
Surface A — table script · interface · 1 members
Options common to the cosmetic-bearing object actions.
What the cosmetic-bearing object actions accept. One field today:
silent.
How, why and when to use it#
Optional everywhere it appears. Omit it and an action behaves exactly as a player's click does — which is the right default, because a script's action should look like an action.
Gotchas#
Cosmetic only. Nothing here changes what the action DOES, so a silent shuffle and a loud one produce the same deck order.
See also#
Members#
| Signature | Description | Returns |
|---|---|---|
silent |
Perform the action without its animation or sound. | boolean |
objectactionoptions.silent#
silent?: boolean;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | async |
| Capability | none |
| Availability | both |
Perform the action without its animation or sound.
A script that shuffles three times during setup does not want three riffles, and a deck shuffled before the table is dealt has no audience for the flourish. The resulting state is identical either way - this suppresses only the presentation, on every client.
Perform the action without its animation or sound.
How, why and when to use it
For setup, not for play. A script that shuffles three times while dealing does not want three riffle sounds and three 0.8-second spins, and a deck shuffled before anyone is looking has no audience for the flourish.
Leave it off for anything a player is meant to notice. The animation and the sound are how a table tells someone that something happened.
Gotchas
Silences the action on every client, not just the one that ran the script. Peers derive the shuffle spin from the broadcast sound event, so suppressing the sound suppresses the spin everywhere — which is the intent, but it does mean you cannot make an action silent for yourself and audible for everyone else.
The resulting state is identical either way. This is presentation, never behaviour.
Example
// content/scripting-api/examples/objectactionoptions.silent.ts
// Scene script: shuffle the deck three times during setup, silently.
globalEvents.onChatMessage.add((message) => {
if (message.text.trim() === "!setup") {
void prepare();
}
});
async function prepare(): Promise<void> {
const decks = await world.getAllObjects({ kind: "deck" });
for (const deck of decks) {
for (let pass = 0; pass < 3; pass += 1) {
deck.shuffle({ silent: true });
}
}
world.broadcast("Table ready.");
}
See also
ContainerItem#
Surface A — table script · interface · 4 members
One KIND of piece stored in a container, as a run of identical copies.
A bag's contents are run-length encoded — twenty identical black stones are ONE entry with
count: 20, not twenty entries — so this describes a group, never an individual piece.
Pieces in a container are not entities: they have no id, no position and no owner, and
nothing here can be passed to world.getObjectById. Take one out with
BagObject.takeObject and you get a real entity with an id of its own.
One sort of piece stored in a container, as a run of identical copies. It is what
BagObject.items is an array of, and the only shape on this
surface that describes something inside a bag that is not a card.
A bag's contents are run-length encoded: twenty identical black stones are one ContainerItem with
count: 20, not twenty entries. So an entry always describes a group, never an individual piece — there is no id
here, no position, no owner, and nothing that
world.getObjectById will accept. A piece only becomes an entity
again when takeObject hands one back with an id of its
own.
How, why and when to use it#
Use it to answer what is in here, and how many of each — a menu of what a player may draw, a setup check that
the bag was stocked correctly, a scoreboard counting what is left. The four fields are exactly that answer:
key addresses a run, name labels it,
kind says what a drawn copy will be, and count is how many.
The pairing that does the real work is key plus takeObject({ key }): read the runs, let a player choose one,
and take from that run rather than at random. That is the whole of the "choose a tile" pattern, and it needs
nothing else.
Gotchas#
The array is not the draw order. A bag draws at random by default, and even in "stack"/"queue" mode a run
is a group rather than a position. Nothing about the order of
items predicts what comes out next.
Only a "bag" form has any. A "holder" — an open bowl or tray — keeps its pieces as ordinary entities
resting in it, so its items is always empty and
world.getAllObjects is where they are. An infinite container
stores nothing either.
Cards are a different lane. A bag holds cards or pieces, never both. A bag of cards reports them through
ContainerObject.cards as
ContainerCard entries and leaves items empty.
A very large bag is truncated. The sandbox copies at most 256 runs onto a handle
(apps/web/src/scripting/sandbox/tableScriptSandbox.html), which is the same ceiling the shared schema puts on
stored runs — so it bounds how many sorts of piece one bag can hold, not how many pieces.
See also#
BagObject.items— the array these live in.BagObject.takeObject— turning a run into an entity.ContainerCard— the card-lane equivalent.- Object kinds — what a
bagcan hold.
Members#
| Signature | Description | Returns |
|---|---|---|
key |
The identity key for this sort of piece — the handle takeObject({ key }) takes to draw one deliberately rather than at random. |
string |
name |
The piece's display name, falling back to its slug. What to put in a menu or a log line. | string |
kind |
ObjectKind |
|
count |
How many copies of this piece the container holds. Always 1 or more. | number |
containeritem.key#
readonly key: string;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The identity key for this sort of piece — the handle takeObject({ key }) takes to draw
one deliberately rather than at random.
Derived from what the piece IS (kind, model, colour, material, scale) and from nothing about where it was: two pieces that look alike share a key and collapse into one run, and a blue cube never shares a key with a red one. Treat it as opaque — it is stable within a session and across a save, and its spelling is not part of this contract.
The identity of this sort of piece, and the handle
takeObject({ key }) takes to draw one deliberately
rather than at random. Treat it as opaque: it is stable within a session and across a save, and its spelling
is not part of this contract.
Returns
A non-empty string. It is derived by containerItemIdentityKey
(packages/shared/src/tableContainers.ts) from what a piece is and from nothing about where it was — the
kind, the model reference, the look (colour, per-slot materials, material id) and the scale, rounded to 1e-4.
Ignored: id, slug, display name, transform, face-up state, lock, owner seat, tags, physics and sound overrides.
How, why and when to use it
Two pieces that look alike share a key, which is exactly what collapses a bowl of go stones into one run. Read a
key when you want to name a run in a later call: show the player their options from
items, remember the key they picked, and pass it back to
takeObject. Nothing else on this surface accepts one.
Gotchas
A blue cube never shares a key with a red one. Colour and material variants are deliberately different pieces, so that a piece dropped into a bowl of another colour is refused rather than silently recoloured on the way back out. Do not expect "same shape" to mean "same key".
Compare it; never parse it, and do not persist it. The derivation is an implementation detail, and a key written into saved data and compared against one derived by a later build is a bug waiting for a release.
An unknown key is not an error. takeObject({ key }) resolves null when the key names no run — the same
null an empty bag gives you. Handing out a different piece from the one asked for would be worse.
See also
ContainerItem— the run this addresses.BagObject.takeObject— the one call that takes a key.ContainerItem.name— what to show a player instead of the key.
containeritem.name#
readonly name: string;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The piece's display name, falling back to its slug. What to put in a menu or a log line.
What to call this sort of piece in a menu or a log line. The sandbox fills it from the stored definition's
displayName, falling back to its slug when the author set no human name
(apps/web/src/scripting/sandbox/tableScriptSandbox.html).
Returns
A string, possibly empty. An empty string means the stored definition carried neither name — rare, but a
name || "piece" fallback costs one character and stops a blank button.
How, why and when to use it
This is the display half of a run, and key is the identity half. Build a "what would you
like to draw?" list out of name and count, and carry key alongside it as the value
you pass back to takeObject. It is also the right thing
to put in a broadcast: "Anna drew a Black Stone" reads as a game event, where a key does not.
Gotchas
It is not unique, and it is not an address. Two runs can share a name — an author may have given a red and a
blue meeple the same display name — while their keys differ. Matching on name to decide what to draw can take
the wrong run; match on key.
It is a display name first and a slug only as a fallback. Where no human name was authored it is the slug,
but where one exists it is that instead. So do not treat this value as the slug-and-identity that
ObjectData.name carries on a real entity.
It describes the run, not a piece. Every copy in the run answers to it; a run of 20 has one name, not 20.
See also
ContainerItem.key— the identity to match on.ContainerItem.count— the other half of a menu line.- Identity, names and tags — the three names and what each is for.
containeritem.kind#
readonly kind: ObjectKind;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
What a piece from this run becomes when it is taken out — the
ObjectKind of the entity
takeObject creates, and the kind its handle is typed
as.
Returns
An ObjectKind. The sandbox falls back to "custom" when the stored definition names no kind, so this is never
absent and never empty.
How, why and when to use it
Read it to decide whether a run is worth drawing at all before you draw it: a rule that only cares about dice
can skip every run whose kind is not "die" without taking a piece out to find out. It is also what lets one
generic "draw something" helper branch its follow-up — position a token, roll a die — on the same value the
resulting handle will report.
Gotchas
It is not the container's kind. The container is a bag; this says what is inside it, which is something
else entirely. Two runs in one bag can differ — a bag takes any mix of pieces.
"card" and "deck" never appear here. Cards are the other lane: a bag holds cards or pieces, and a card
bag reports through ContainerObject.cards with an
empty items. A card run is not something the drop path can create.
The union is open. ObjectKind ends in (string & {}), so write a default branch rather than assuming the
named kinds are all there will ever be.
See also
ObjectKind— the union, and why it is open.ContainerItem— the run this describes.BagObject.takeObject— where the kind becomes an entity.
containeritem.count#
readonly count: number;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
How many copies of this piece the container holds. Always 1 or more.
How many copies of this piece the container holds. Always 1 or more — a run that reaches zero is removed from
items rather than left behind at 0.
Returns
A positive integer, counting this run only. The bag's total is the sum across runs.
How, why and when to use it
It is the number a player wants to see next to name — "Black Stone ×180" — and the number
a rule checks before it commits to something: is there a meeple left in this colour, has the bag of tiles run low
enough to end the round. Summing it across items gives the true total in the bag:
bag.items.reduce((sum, item) => sum + item.count, 0).
Gotchas
It is not stackCount, and the two can disagree. The container's public
stackCount is the wire-facing count and is clamped
to 1000 (MAX_CONTAINER_PUBLIC_COUNT, packages/shared/src/tableContainers.ts), so a bag of 2,000 stones
publishes 1000. It is also never below 1, so an empty bag still reports stackCount: 1 while its items
array is empty. Sum count when you need the real number; read stackCount when you want what every peer sees.
A run is capped too. The shared schema refuses a run above 10,000 copies, and a bag above 256 runs, so a "stock it with a million" setup script fails at the drop rather than at the draw.
It changes under you. Every draw, every drop and every tip-out rewrites the runs, so an items array you
captured before an await describes a bag that may no longer be in that shape. Re-read it.
See also
ContainerItem.name— the label that goes beside it.BagObject.items— the array to sum.ObjectData.stackCount— the public, clamped count.
CoinObject#
Surface A — table script · interface · 1 members
A coin — a flat piece that turns over and stacks like a token, and that a player can
flip (toss). A script cannot start a toss; it hears one through onTossed (and
onAction as "toss").
A coin: a flat entity that turns over and stacks exactly like a token, and that a player can
also toss — the Flip Coin action, shortened to Toss on the touch rail and in the VR
object menu. refObject is declared as this in a script created from a coin's Script section,
and world.getAllObjects({ kind: "coin" }) resolves CoinObject[].
Any entity of kind coin gets this handle: the five built-in coin presets (coin, coin-1,
coin-2, coin-5, coin-10) and a project's own coin model whose Type is set to Coin in
the Inspector's PIECE panel alike. A save or published scene from before the coin kind
existed, holding a built-in coin as a token, loads as a coin — the rewrite happens on load,
so such a coin gets this handle too.
How, why and when to use it#
Use it when a rule hangs off a coin being thrown — announcing the toss, counting tosses, or
starting a timer while it is in the air. The one thing it adds to
ObjectHandle is onTossed, so a
coin's own script can say "when this coin is tossed" without filtering
onAction by name.
Gotchas#
toss is an action a script can observe, never one it can request: there is no toss()
method and "toss" is not an ObjectAction. A script
that wants a random result should pick it itself and show it, rather than throw a coin and
wait for physics to land it.
A coin's in-place Flip (turning it over without throwing it) is a different action. It
reaches onAction as "flip" and does not raise onTossed; onFlipped is declared on
CardObject only.
A locked coin cannot be tossed, and a coin parented to another entity is held in place and
is not thrown, so neither raises onTossed.
See also#
ObjectHandle— everything a coin inherits.- Coin — the kind at the table: physics, size, sound, and the toss itself.
- Action vocabularies — why
tossis observe-only.
Members#
| Signature | Description | Returns |
|---|---|---|
onTossed |
Fires when a player tosses this coin. It fires at the throw, while the coin is still in the air — read which side is up once it has settled, not here. | ScriptDelegate<[CoinObject, EventContext]> |
coinobject.onTossed#
readonly onTossed: ScriptDelegate<[CoinObject, EventContext]>;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Fires when a player tosses this coin. It fires at the throw, while the coin is still in the air — read which side is up once it has settled, not here.
Fires when a player tosses this coin. It is
onAction narrowed to the toss action, and fires
immediately after it on the same handle.
Applies to: coin. It is declared on CoinObject only.
It fires at the throw, while the coin is still in the air. There is no result value: nothing reports heads or tails, and the side that lands up is not known yet when your handler runs.
Parameters
The handler receives two arguments, transcribed from ScriptDelegate<[CoinObject, EventContext]>:
| Position | Type | Notes |
|---|---|---|
| 1 | CoinObject |
The same handle you subscribed on, as it was at the throw. |
| 2 | EventContext |
The peer who tossed it. Never "Script" — no script can toss a coin. |
How, why and when to use it
Attach a rule to the coin itself when the toss is the moment that matters — a chat line naming
who threw, a toss counter, a short pause before the next step of a turn. Use
globalEvents.onObjectAction with an
action === "toss" check instead when the rule belongs to the table rather than to one coin.
Gotchas
Do not read the result here. The coin is mid-air. If your game needs the side that landed, wait until it has settled and read its orientation then — and consider whether a result the script picks itself would serve the game better than one physics picks.
A toss aimed at a locked coin is refused by the host and raises nothing, so this delegate never fires for a locked coin.
Example
// content/scripting-api/examples/coinobject.onTossed.ts
// Object script on the coin. `refObject` is a CoinObject.
//
// Announce every toss, and call out a second toss made while the first is still in the
// air. The toss carries no heads or tails: physics lands the coin after this handler runs.
const LANDING_SECONDS = 2;
let inFlight = false;
refObject.onTossed.add(async (coin, context) => {
const name = coin.name ?? "the coin";
if (inFlight) {
world.broadcast(`${context.actor} tossed ${name} again before it landed.`);
return;
}
inFlight = true;
world.broadcast(`${context.actor} tossed ${name}.`);
// Give the coin time to come down before treating the toss as finished.
await world.wait(LANDING_SECONDS);
inFlight = false;
world.log(`${name} has landed.`);
});
See also
CoinObject— the handle this is declared on.- Coin — how high a toss goes and how it lands.
TableFurnitureObject#
Surface A — table script · interface
A table placed as an entity — furniture the game is played on. Static, and its surface material colours the sound of every piece that lands on it.
A table placed as an entity - the furniture a game is played on. refObject is declared as this in a script created from a table's Script section.
It adds nothing to ObjectHandle. A table is a fixture: it cannot be flicked, the host never lifts it out of a board it overlaps, clearing the table to blank keeps it, and a scripted deal treats its top as a surface to land on. Like a board, a table script is normally written about the other entities that land on it, through globalEvents.
Its Surface material matters more than its own sound. Every piece that lands on a table is heard through the table's surface - a felt top muffles a token being placed, a glass or stone top makes it ring.
This is the kind for a table you place inside a scene. The table a whole game sits on is usually a table pack instead, and a table pack sets the same surface material on its Play Surface.
Gotchas#
- Static is not locked. A table is the one kind the runtime makes static by kind alone, so it never topples - but only
lockedstops a player dragging it. A table placed from a model classified as Table in the Model editor is already locked; one you spawn from a script should passlocked: true. See Object kinds § Table.
See also#
globalEvents.onObjectDropped- what most table rules watch.BoardObject- the other fixture kind.SoundMaterial- how a surface colours what lands on it.
ButtonObject#
Surface A — table script · interface · 2 members
A pressable button. Pressing it dips the cap, plays its sound and raises
onPressed — the whole point of the kind, and the only event it adds.
eventName is the author-set name from the button's configuration, so one
handler can serve several buttons and branch on which was pressed rather than
comparing object ids.
A pressable button: a coloured cap in a frame that dips when a player presses it, plays its
sound and raises onPressed. Both silhouettes — rectangular and
round — are the same button kind and share this handle; the shape is configuration, not a
different type.
Everything about a button's appearance (size, colours, frame, and the text or image on its
cap) lives in the object's own configuration, not on this handle. A script reacts to presses
and reads eventName; it does not restyle the button mid-game.
How, why and when to use it#
Use a button when a rule needs an explicit, deliberate input rather than a piece being moved — ending a turn, ringing a bell, committing a bid. A button is the one control on the table whose only purpose is to be pressed, so a press carries no ambiguity about intent the way "a token was dropped in a zone" does.
Gotchas#
press is an action a script can observe, never one it can request. A script that wants
to do the button's job should simply do it — simulating a press would let a script fake input
attributed to a seat, which is exactly what the host-authoritative model exists to prevent.
See also#
ObjectHandle— everything a button inherits.- Button objects — the configuration a button carries.
Members#
| Signature | Description | Returns |
|---|---|---|
eventName |
The configured event name for this button (default "button-press"). |
string |
onPressed |
Fires when a player presses this button. | ScriptDelegate<[ButtonObject, EventContext]> |
buttonobject.eventName#
readonly eventName: string;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The configured event name for this button (default "button-press").
The author-configured name this button emits when pressed, defaulting to "button-press".
How, why and when to use it
It exists so one handler can serve several buttons and branch on which was pressed without hard-coding object ids. Ids are generated per spawn, so a script written against them breaks the moment the table is rebuilt from a save; a name set in the button's configuration is stable across saves, republishes and re-places.
Gotchas
Names are not unique and are not validated for collisions — two buttons may deliberately share one when they should do the same thing. If you need to tell those two apart anyway, compare the object rather than the name.
An empty name is not possible: the configuration schema requires at least one character and
falls back to "button-press".
See also
onPressed— where you read this.
buttonobject.onPressed#
readonly onPressed: ScriptDelegate<[ButtonObject, EventContext]>;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Fires when a player presses this button.
Fires when a player presses this button — the reason the kind exists. It is
onAction narrowed to the press
action, and fires immediately after it on the same handle.
Applies to: button. It is declared on ButtonObject only.
Parameters
The handler receives two arguments, transcribed from ScriptDelegate<[ButtonObject, EventContext]>:
| Position | Type | Notes |
|---|---|---|
| 1 | ButtonObject |
The same handle you subscribed on. |
| 2 | EventContext |
The seat that pressed it, or an unseated actor. |
How, why and when to use it
Attach the rule to the button rather than filtering a table-wide action feed: the handler then cannot drift out of step with which buttons exist, and reads as what it is — "when this button is pressed, do this".
Gotchas
The dip animation and the sound are not contingent on your handler. They start on the press itself, so throwing from here does not cancel the press or roll back the feedback the player already saw.
A press by a player with no seat still fires, with an unseated actor. Guard on the seat if your rule requires one — do not assume it is present.
Example
A full deal routine: shuffle, three face-down rows into each seat's card zones, three face-up rows on top, then three rounds into hands — each round starting with whoever pressed the button and moving clockwise.
// content/scripting-api/examples/buttonobject.onPressed.ts
// Object script on the button. `refObject` is a ButtonObject.
//
// Seven, Twos & Tens deal:
// 1. shuffle
// 2. one FACE-DOWN card to each seat's CardZone1, then CardZone2, then CardZone3
// 3. the same three zones again FACE UP, stacked on the face-down ones
// 4. three rounds into each seat's hand
// Every round starts with whoever pressed the button and moves clockwise, so each active
// player ends with 9 cards: 3 face down, 3 face up over them, 3 in hand.
// Clockwise seat order, matching PLAYER_SEAT_OPTIONS.
const SEAT_ORDER = ["red", "blue", "green", "yellow", "purple", "orange", "pink", "cyan", "white", "brown"];
const CARD_ZONES = ["CardZone1", "CardZone2", "CardZone3"];
const HAND_ROUNDS = 3;
/** Pause between cards so the deal reads as a deal rather than appearing all at once. */
const DEAL_PAUSE = 0.08;
/**
* Seats to deal to, clockwise, starting from `startSeat`.
*
* Only seats that are BOTH occupied and actually authored in the scene are included: a
* player at a seat the scene has no zones for cannot be dealt to, and dealing to an empty
* seat would strand cards on the table.
*/
function dealOrder(startSeat: string | null, seatedSeats: string[]): string[] {
const seated = SEAT_ORDER.filter((seat) => seatedSeats.indexOf(seat) !== -1);
if (seated.length === 0) {
return [];
}
// An unseated presser (or a seat with no zones) just starts the deal at the head of the
// order rather than refusing to deal.
const startIndex = startSeat ? seated.indexOf(startSeat) : -1;
const offset = startIndex === -1 ? 0 : startIndex;
const ordered: string[] = [];
for (let step = 0; step < seated.length; step += 1) {
ordered.push(seated[(offset + step) % seated.length]);
}
return ordered;
}
refObject.onPressed.add(async (button, context) => {
const decks = await world.getAllObjects({ kind: "deck" });
const deck = decks[0];
if (!deck) {
world.log("Deal: no deck on the table.");
return;
}
// Seats that are both occupied AND authored with zones in this scene.
const zones = await world.getSeatZones();
const seatsWithZones: string[] = [];
for (const zone of zones) {
// `seat` is null for a TABLE zone, which belongs to nobody and seats no player.
if (zone.seat !== null && seatsWithZones.indexOf(zone.seat) === -1) {
seatsWithZones.push(zone.seat);
}
}
const players = world.getPlayers();
const occupied = players
.map((player) => player.seat)
.filter((seat): seat is string => typeof seat === "string" && seat.length > 0);
const seated = seatsWithZones.filter((seat) => occupied.indexOf(seat) !== -1);
// EventContext carries the actor's PEER ID, not their seat, so map it here. An unseated
// presser (or the host acting as "Host"/"Script") leaves this null and the deal simply
// starts at the head of the clockwise order.
const presser = players.find((player) => player.peerId === context.actor);
const order = dealOrder(presser ? presser.seat : null, seated);
if (order.length === 0) {
world.log("Deal: nobody is seated.");
return;
}
deck.shuffle();
// Let the shuffle land before drawing from it, so the deal uses the shuffled order.
await world.wait(0.35);
// Rows 1-3: face DOWN, one zone at a time, all the way round before moving on. A null
// result means the deck ran out or the seat has no zone by that name; stop rather than
// grinding through 50 more no-ops.
for (const zoneName of CARD_ZONES) {
for (const seat of order) {
const dealt = await deck.dealTo({ seat, zoneName, faceDown: true });
if (!dealt) {
world.log(`Deal: could not deal to ${seat}'s ${zoneName}. Stopping.`);
return;
}
await world.wait(DEAL_PAUSE);
}
}
// Rows 4-6: face UP, laid over the face-down card in the same zone.
for (const zoneName of CARD_ZONES) {
for (const seat of order) {
await deck.dealTo({ seat, zoneName, faceDown: false, stack: true });
await world.wait(DEAL_PAUSE);
}
}
// Three rounds into hands. No zoneName = a real hand deal: the card is owned by the seat,
// takes its slot in the fan and is hidden from everyone else.
for (let round = 0; round < HAND_ROUNDS; round += 1) {
for (const seat of order) {
await deck.dealTo({ seat, faceDown: true });
await world.wait(DEAL_PAUSE);
}
}
world.log(
`${context.actor} dealt ${order.length} player(s): 3 down, 3 up, ${HAND_ROUNDS} in hand.`
);
});
See also
eventName— how to tell several buttons apart.
SpawnObjectOptions#
Surface A — table script · interface · 10 members
Definition for spawning a new object.
The single argument to world.spawnObject. One required field —
kind — and nine optional ones. The sandbox turns it into a table object definition, generates the entity's id
itself, and posts a spawn intent; nothing else in table scripting takes this type.
How, why and when to use it#
Think of it as the whole description of a new entity, because it is: there is no second call that adjusts an
entity's tags, metadata or name afterwards. Whatever you want an entity to carry for the rest of the session has
to be in this object at spawn. The alternative is to place the entity in the mod's setup.json while authoring,
which gives you the full object schema — physics, components, parenting — instead of these ten
fields. Spawn from a script when the entity's existence depends on something you only learn at run time;
pre-place when it does not.
Gotchas#
Ten fields is much less than the entity schema has. No physics, no parenting, no
components, no displayName, no owner seat. Those exist on the replicated entity state and are not reachable
from a spawn — set them by authoring the entity instead, or by pointing presetId at a standard preset.
Every field is coerced, not validated. A malformed value is silently substituted or dropped rather than
raising. The one thing that fails the whole call is a missing or non-string kind, which resolves null before
anything is sent.
The sandbox's checks are looser than the host's. A definition that passes in the frame can still be rejected by the host's schema — an over-long tag is the usual cause, and the rejection takes the entire spawn with it. See Tag validation is asymmetric.
You cannot choose the id. The sandbox generates one of the form script-… and the host honors it, which is
why the returned handle addresses the right entity from the first tick.
See also#
world.spawnObject— the call, its return value and whatnullmeans.ObjectKind— the valueskindaccepts.Vec3— the shape ofpositionandrotation.- Object state — the full entity schema these ten fields are a slice of.
- Known limitations — the full list of documented gaps.
Members#
| Signature | Description | Returns |
|---|---|---|
kind |
ObjectKind |
|
name |
string |
|
position |
Vec3 |
|
rotation |
Vec3 |
|
scale |
Scale, per axis. Every component must be above zero — a zero or negative scale is refused and the entity spawns at its default size. For an imported model, pass the scale of an existing entity of the same set (other.scale); the model's sidecar does not supply it. |
Vec3 |
presetId |
Preset id from the standard object library (e.g. "die-d6", "deck-standard"). | string |
color |
Tint, as a full #rrggbb string. Left out, the entity takes the default colour of its kind. |
string |
metadata |
Record<string, unknown> |
|
tags |
string[] |
|
container |
Make this entity a CONTAINER. Only meaningful with kind: "bag"; ignored otherwise. |
{ form: "holder" | "bag"; infinite?: boolean; secretContents?: boolean; /** Infinite only: the piece a draw spawns. A definition with no position of its own. */ source?: { kind: ObjectKind; name?: string; presetId?: string; rotation?: Vec3; scale?: Vec3; /** #rrggbb. */ color?: string; metadata?: Record<string, unknown>; tags?: string[]; }; } |
spawnobjectoptions.kind#
kind: ObjectKind;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The platform kind of the entity to create. The only required field on
SpawnObjectOptions, and the only one whose absence stops the
call outright.
Returns
Accepts an ObjectKind. It must be a non-empty string: pass nothing,
null, an empty string or a non-string and world.spawnObject resolves null without sending anything to the
host. A non-empty string that is not one of the eleven the sandbox knows — card, deck, die, token,
board, bag, custom, card-holder, button, table, coin — is replaced with "custom", with no error and no log line.
How, why and when to use it
kind decides what the entity is for the rest of its life: whether it can be shuffled, drawn from, rolled or
flipped, and what physics it gets. Choose it from the behavior you need, not from what the piece looks like — art
comes from presetId and from the mod's assets, and a custom entity with a die model still will not roll.
Where a game concept has no platform equivalent, spawn a token or a custom and carry the meaning in
tags.
Gotchas
The silent "custom" substitution is the one to watch. kind: "dice" compiles, spawns, and produces a plain
entity that never rolls. Read handle.kind back whenever the value comes from data rather than a literal.
It also becomes the default label. Omit name and the
entity's slug is the kind string, so three unnamed dice all get the label die.
See also
ObjectKind— every value the field accepts.world.spawnObject— the only place this field is used.SpawnObjectOptions.presetId— how the entity gets a model.- Object kinds — what each kind does.
spawnobjectoptions.name#
name?: string;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The entity's label — its slug and machine key — despite the field being called name. It is not the human
name shown in the Hierarchy, and there is no field here that sets one.
Returns
Accepts a string, optional. A non-empty string is truncated to 80 characters; anything else, including an
empty string, falls back to the kind string. It is written to the definition's label, which is what
ObjectData.name reads back and what world.getAllObjects has no filter for.
How, why and when to use it
For a card, label is the card's identity — it drives hidden-information redaction, so renaming a card for
readability changes which card it is. For every other kind it is a machine key you choose, and the reason to set
it deliberately is that it is the only self-describing thing about an entity a script can read later. Give
spawned entities a predictable label (scoring-die-1, marker-north) so a script that finds them again can tell
them apart; leave it unset only when the entity is disposable. If you want a display name, put your own string
in metadata and read it back from
ObjectData.metadata.
Gotchas
Known gap. A table script can neither read nor write an entity's displayName. This field writes label,
and ObjectData.name reads label back (apps/web/src/scripting/sandbox/tableScriptSandbox.html,
stateToData), so an entity a script spawns has no human name at all until somebody sets one in the editor.
Spawning, labelling and reading the label all work correctly — only the second name is missing. Carry a display
string in metadata if you need one.
See Known limitations.
Truncation is silent. An 81-character name becomes an 80-character label with no warning, so two long names that share a prefix can collide.
Labels are not enforced unique from a script. The editor treats a slug as unique within a scene; nothing
stops a script spawning three entities with the same label. Address entities by id, not by label.
See also
ObjectData.name— the read side, and which name it really is.SpawnObjectOptions.metadata— where a display string belongs.- IDs, names and tags —
id,labelanddisplayName, defined once. - Known limitations — the full list of documented gaps.
spawnobjectoptions.position#
position?: Vec3;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Where the entity appears, as an absolute table-space Vec3 in feet.
Returns
Accepts a Vec3, optional. Defaults to [0, 1, 0] — one foot above the table origin, so the entity drops
onto the surface instead of clipping through it. A value that is not an array of at least three entries falls
back to that default; individual entries that are not finite numbers become 0.
How, why and when to use it
Spawning several entities in a row without a position stacks them all at the origin, where physics shoves them
apart in whatever direction it likes. Space them yourself — an index times a spacing, as
world.spawnObject's example does — whenever you create more than
one. The alternative is spawning them on top of each other deliberately, which is a reasonable way to build a
pile and a poor way to lay out player markers. Keep y at 1 unless you have a reason: dropping is what settles a
piece onto the table.
Gotchas
Units are feet, and there is no bounds check. A position off the table is accepted; the entity falls. The host nudges strays back onto the surface in some cases, and that is not something to rely on.
A short array is not a partial position. [1, 2] is not "x and y" — it fails the length check and the whole
value is replaced with the default.
It is the entity's own position, not an offset. There is no relative spawn.
Spawning at a seat is not supported here. No field places an entity into a player's hand. Spawn it on the
table and move it, or use deal() on a container, which
sends one item to every authored seat.
See also
Vec3— the tuple shape and its coercion rules.SpawnObjectOptions.rotation— the same shape, with a different default behavior.ObjectHandle.setPosition— moving an entity after it exists.world.spawnObject— a worked example that spaces several spawns out.
spawnobjectoptions.rotation#
rotation?: Vec3;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The entity's starting orientation, as Euler angles in degrees, in the same
Vec3 tuple shape as position.
Returns
Accepts a Vec3, optional. Omit it and the entity spawns unrotated — the field is left off the definition
entirely rather than defaulted to [0, 0, 0], which is the one place its handling differs from
position. A value that is not an array of at least
three entries is dropped the same way; individual non-finite entries become 0.
How, why and when to use it
Set it when the entity's facing is part of the game: a card that has to start face-down ([180, 0, 0]), a board
laid out along the table's other axis, markers that face their owner. Otherwise leave it off — spawning
unrotated and then calling rotate() or
flip() costs an extra intent and a snapshot for the same
result. The rule of thumb: anything you know at spawn belongs in the spawn.
Gotchas
A face-down card is an X rotation of 180 degrees, and there is no faceDown field here — orientation is the
only way a spawn expresses which way up a card starts. ObjectData.faceUp reads the resulting state back.
Angles are absolute, not relative, and they are degrees, not radians.
A malformed value is silently dropped, not defaulted. Passing [1, 2] gives you an unrotated entity, not an
error — the same input to position would give you the default [0, 1, 0].
See also
Vec3— the tuple shape, and why rotations are absolute.SpawnObjectOptions.position— the same shape, defaulted rather than dropped.ObjectHandle.setRotation— turning an entity after it exists.ObjectData.faceUp— reading which way up it ended.
spawnobjectoptions.scale#
scale?: Vec3;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Scale, per axis. Every component must be above zero — a zero or negative scale is refused
and the entity spawns at its default size. For an imported model, pass the scale of an
existing entity of the same set (other.scale); the model's sidecar does not supply it.
The entity's scale per axis, in the same Vec3 tuple shape as position.
Returns
Accepts a Vec3, optional. Omit it and the entity spawns at its kind's default size. Every component must be
above zero: a zero or negative scale is refused and the entity spawns at its default size instead. Components
above 100 are clamped to 100.
How, why and when to use it
Set it whenever you spawn an imported model that should match pieces already on the table. For an imported model, scale is a multiplier on the model's own size, and it lives on each placed entity — the model's sidecar does not carry it. So a script spawning a new chess queen must say what scale the set was placed at, or the queen arrives at the default token size, a fraction of the height of its neighbours.
The reliable source is an entity of the same set: copy its scale.
Replacing a piece is the common case — a promoted pawn keeps the pawn's position, rotation and scale.
Gotchas
It is a multiplier, not a size in feet, for imported models. A chess set placed at [3, 3, 3] is three times
its modelled size; [3, 3, 3] here means the same thing, not three feet.
Zero and negative scales are refused, not clamped. A degenerate scale would build a collider the physics engine cannot handle, so it never reaches it.
See also
ObjectData.scale— the value to copy from an existing entity.SpawnObjectOptions.rotation— the other field a replacement copies.
spawnobjectoptions.presetId#
presetId?: string;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Preset id from the standard object library (e.g. "die-d6", "deck-standard").
The id of an entry in the standard object library, such as die-d6 or deck-standard. The sandbox writes it
into the definition's metadata.standardPresetId, and the runtime uses it to attach the preset's 3D model — and,
for kind: "die", its convex-hull collision shape.
Returns
Accepts a string, optional. A non-empty string is stored; anything else, including an empty string, is ignored
and no standardPresetId is written. It is applied after your own metadata is copied, so it overrides a
standardPresetId you set there yourself.
How, why and when to use it
Without a preset a spawned entity gets the kind's plain default shape — a die with no preset is a box that
tumbles like a box. presetId is how a script gets a real d6, a standard 52-card deck or a proper token without
shipping any assets of its own. The alternative is a mod asset referenced from the entity's metadata, which is
what you want for game-specific art and is not something a spawn can set up on its own. Use a preset for the
generic tabletop furniture; author the entity in the editor when it needs your own model.
Gotchas
It only brings the model and, for a die, the collision shape. Color and scale still come from the kind defaults, so a preset does not make a spawned entity identical to the same preset placed in the editor.
An unknown preset id is not an error. Nothing validates the string in the sandbox; a typo gives you the kind's default appearance and no diagnostic.
It does not imply a kind. presetId: "die-d6" on kind: "card" writes the metadata and leaves you with a
card. Set both.
The library of ids is not readable from a script. There is no call that lists presets — take ids from the standard object presets reference.
See also
SpawnObjectOptions.metadata— the bag this is written into, and why it wins.SpawnObjectOptions.kind— the field that actually decides behavior.world.spawnObject— a worked example usingdie-d6.- Object kinds — the kind defaults a preset does not replace.
spawnobjectoptions.color#
color?: string;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Tint, as a full #rrggbb string. Left out, the entity takes the default colour of its kind.
The entity's tint, as a full six-digit #rrggbb hex string. It becomes the spawned entity's replicated
color.
Returns
Accepts a string, optional. Omit it and no color is written to the definition, so the entity keeps the color
it would have had anyway: its preset's or kind's. The sandbox passes on only a string of exactly # plus six
hex digits, in either case; anything else — #fff, "red", an eight-digit value with alpha, a number — is
ignored, and the entity spawns as if the field had been left out.
How, why and when to use it
Set it when the color is something the script decides at run time: a marker in the color of the seat it belongs to, a token recolored per team, a cube whose color is its meaning in a color-matching game. The alternative is one authored prefab or preset per color, which is the better choice when the set of colors is fixed while you are authoring — but it cannot follow a color that only exists once players have sat down.
You rarely write this field by hand for a copy of something that already exists. A
spawnable variable bound to a prefab already carries the prefab's
color, so world.spawnObject({ ...vars.piece, position }) spawns the copy in the prefab's color. Put your own
color after the spread when you want to override it.
Gotchas
A malformed value is dropped, not reported. There is no error and no console line. #fff gives you the
default color, not white — write #ffffff.
It can only be set at spawn. There is no call that recolors an entity afterwards, so a color you want for the rest of the session has to be in this object.
It is a tint, not a material. How it shows depends on what the entity is drawn with, and an entity carrying
a material assignment renders with that material whatever its color says. See
TableObjectState.color.
Do not use the color as the entity's identity. If your rules need to know whose piece it is, say so with a
tag or a metadata value in the same spawn; a color is a rendering choice.
See also
TableObjectState.color— the replicated field this writes, and how a tint is applied.SpawnObjectOptions.presetId— the preset whose look an omitted color leaves alone.declareVariables— aspawnablebound to a prefab supplies this field for you.world.spawnObject— the call this is an option of.
spawnobjectoptions.metadata#
metadata?: Record<string, unknown>;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
A freeform property bag copied onto the new entity's definition. It is the only way a spawn attaches arbitrary
data to an entity, and it is readable afterwards through
ObjectData.metadata.
Returns
Accepts a Record<string, unknown>, optional. The sandbox takes a shallow copy — nested objects are shared
by reference with whatever you passed in — and ignores a non-object value entirely.
presetId is written into the copy afterwards, so it
overrides a standardPresetId key of your own.
How, why and when to use it
metadata is where a script puts everything the entity schema has no field for: which player a marker belongs
to, what a token is worth, the display string a script cannot otherwise set. It replicates in every snapshot and
survives a save, so it is durable. The alternative for anything you only need to find entities by is
tags, because world.getAllObjects({ tag }) filters on a
tag and has no metadata filter at all — searching by metadata means fetching everything and filtering in your own
code. Tag what you query; put in metadata what you read once you have found it.
Gotchas
It is write-once from a script. There is no method that changes an entity's metadata after it exists. Model
anything that has to change with
ObjectHandle.setSavedData instead.
Values type as unknown when you read them back. ObjectData.metadata is a
Readonly<Record<string, unknown>>, so every read needs a typeof check or a cast before you can use it.
The runtime uses this bag too. Reserved keys already live here — scriptId attaches an object script,
standardPresetId selects a preset, cardId and sourceDeckId are written onto drawn cards,
grabbableWhileParented exempts a child from grab escalation. Namespace your own keys so you cannot collide with
one.
It rides every snapshot. A large bag is re-sent to every peer on every keyframe. Keep it small.
See also
ObjectData.metadata— the read side, and itsunknownvalues.SpawnObjectOptions.tags— the field you can actually filter on.ObjectHandle.setSavedData— per-entity state that can change.- Object state — where
metadatasits in the full entity schema.
spawnobjectoptions.tags#
tags?: string[];
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The entity's author tags. This is the only field on a spawn that
world.getAllObjects can filter on, which makes it the field
that decides whether a script can find its own entities again.
Returns
Accepts a string[], optional. The sandbox drops any entry that does not match [a-z0-9_-]+ — lower case,
digits, underscore and hyphen only — then keeps at most the first 100. If nothing survives, no tags field
is written at all. A non-array value is ignored.
How, why and when to use it
You spawn a die per player at the start of a round and need to find exactly those dice next round, not the ones
players brought themselves. Tag them at spawn and query the tag: world.getAllObjects({ tag: "scoring-die" }).
The alternative is keeping the handles in an array, which is faster and correct right up to the first script
restart, a host migration or a reload — the array is gone and the tag is still on the entities. Hold handles for
the current operation; tag anything a later run has to rediscover.
Gotchas
Known gap. The frame's filter and the host's schema disagree on length. The sandbox accepts a matching tag
of any length (apps/web/src/scripting/sandbox/tableScriptSandbox.html, spawnObject); the host then parses
the definition with the shared schema, which caps a tag at 32 characters
(packages/shared/src/tableObjects.ts). The parse fails, and it fails for the whole spawn — no entity, no
event, and a diagnostic in the script console as the only signal. Both filters are correct in isolation; they
have drifted apart. Keep tags to 32 characters or fewer.
See Known limitations.
Platform dt: tags can never be written from a script. The pattern forbids :, so the reserved namespace is
unreachable — and ObjectData.tags never contains one either.
Uppercase is dropped, not lower-cased. "ScoringDie" fails the pattern and disappears silently, leaving you
querying a tag nothing carries. Write tags in the form you will query them.
Tags are write-once from a script. Nothing changes an entity's tags after it exists.
See also
world.getAllObjects— the query this field exists for.ObjectData.tags— the read side.SpawnObjectOptions.metadata— for data you read rather than query.- Tags and groups — the
dt:namespace and the authoring rules. - Known limitations — the full list of documented gaps.
spawnobjectoptions.container#
container?: {
form: "holder" | "bag";
infinite?: boolean;
secretContents?: boolean;
/** Infinite only: the piece a draw spawns. A definition with no position of its own. */
source?: {
kind: ObjectKind;
name?: string;
presetId?: string;
rotation?: Vec3;
scale?: Vec3;
/** `#rrggbb`. */
color?: string;
metadata?: Record<string, unknown>;
tags?: string[];
};
};
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Make this entity a CONTAINER. Only meaningful with kind: "bag"; ignored otherwise.
form decides what sort it is — "holder" is an open bowl whose pieces stay real
entities, "bag" is closed and stores them. infinite makes it a dispenser that never
runs out, in which case source is the piece every draw spawns; an infinite container
with no source adopts the first piece dropped into it.
There is deliberately no way to spawn a bag with pieces already inside it. Stock it with
putObject, which takes the same host-side route a player dropping pieces in does, so
capacity and piece-type rules apply to a script exactly as they do to a player.
secretContents hides the contents from every peer but the host. It is expensive —
a non-empty secret bag disables snapshot delta compression for the WHOLE table, the same
cost a deck of face-down cards carries — so leave it off unless the game needs it.
Make the entity you are spawning a container. Only meaningful with kind: "bag" — the sandbox drops it for
any other kind — and it is the only way a script can create one, since
form and
infinite are read-only on the handle afterwards.
Returns
The four sub-fields, all optional except form:
| Field | Type | Notes |
|---|---|---|
form |
"holder" | "bag" |
"holder" is an open bowl whose pieces stay real entities; "bag" is closed and stores them. An unrecognised value falls back to "bag". |
infinite |
boolean |
A dispenser that never runs out. |
source |
an object definition | Infinite only — the piece every draw spawns. |
secretContents |
boolean |
Hide the contents from every peer but the host. Expensive; see below. |
How, why and when to use it
Use it in setup, when the game needs a supply the author did not place — a bag per player, a bowl that appears only in a variant. Spawn it, then stock it.
There is deliberately no way to spawn a bag with pieces already in it. Stock it with
putObject, which takes the same host-side route a
player dropping pieces in does — so capacity, the one-lane rule and piece-type matching apply to a script exactly
as they do to a player. A contents option here would be a second stocking path with none of those checks,
which is why there isn't one.
Gotchas
source is refused on anything but an infinite container. The shared schema rejects it outright, and the
sandbox drops it before it can travel — which turns what would have been a rejected spawn into a working one,
silently missing the source. Set infinite: true in the same call or leave source out.
An infinite container with no source adopts the first piece dropped into it. That is deliberate: it is how
an author sets a supply's type in play. Until then, draws resolve null.
⚠ secretContents is a table-wide cost, not a per-bag one. A non-empty secret bag disables snapshot delta
compression for the whole table and puts the host on per-peer full snapshots — exactly the cost a deck of
face-down cards already carries. Leave it off unless the game needs it. A piece bag's contents are unseen
rather than secret by default: everybody watched each piece go in, and which piece the next draw yields is
decided by the host's private RNG at draw time, not derivable from the list.
A holder is not free either. Its pieces stay real entities, so a bowl of 200 stones is 200 rigidbodies. A
"bag" stores them as runs and costs almost nothing.
kind still has to be "bag". Passing container alongside kind: "token" is not an error; the option is
simply ignored and you get a token.
See also
BagObject.form— what you are choosing between.BagObject.infinite— the dispenser behaviour.BagObject.putObject— how to stock what you spawned.world.spawnObject— the call this option belongs to.
SeatZoneInfo#
Surface A — table script · interface · 8 members
One seat zone, in world space — what a script needs to put something INTO a zone.
Seat zones are authored in the scene document and are never replicated, so before this existed a script had no way to find out where a seat's card zones were and therefore no way to deal into them. This is a read-only projection of the runtime's live zone boxes: plain data, no handles, and a copy rather than a live reference.
id is the authored zone id and is only unique WITHIN its seat, so always qualify it
with seat. name is the authored label ("HandZone", "CardZone1") and is what a
script normally matches on, because it survives re-authoring in a way ids do not.
One seat zone, in world space — the shape of what
world.getSeatZones() returns.
How, why and when to use it#
Seat zones are authored in the scene and never replicated, so this projection is the only
way a script can learn where a seat's zones are. Match on name and hand the result to
dealTo, or use position/size to place something yourself.
Gotchas#
It is a copy, taken when you asked. Zones do not move during play, but do not cache it across a scene reload.
See also#
Members#
| Signature | Description | Returns |
|---|---|---|
seat |
The owning seat, or null for a table zone that belongs to nobody. |
string | null |
id |
string |
|
name |
string |
|
zoneType |
ZoneType |
|
primary |
True for the seat's primary zone of its type (a seat may own several). | boolean |
position |
World-space centre [x, y, z]. |
Vec3 |
size |
World-space box size [x, y, z]. |
Vec3 |
rotationY |
Y rotation in degrees. The zone's top edge is its local +Z edge; a card or deck that should read toward it is placed at rotationY + 180, because card art points its top along the card's own -Z. |
number |
seatzoneinfo.seat#
readonly seat: string | null;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | async |
| Capability | none |
| Availability | both |
The owning seat, or null for a table zone that belongs to nobody.
Which seat owns this zone — "red", "blue", and so on.
How, why and when to use it
Zone ids are only unique within a seat, so this is half of every zone's real identity. Group by it to find "every zone belonging to the players who are actually here".
Gotchas
A seat having zones does not mean anyone is sitting there. Cross-check against
world.getPlayers() before dealing, or cards
land at an empty seat.
See also
id— the other half of the identity.
seatzoneinfo.id#
readonly id: string;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | async |
| Capability | none |
| Availability | both |
The authored zone id.
How, why and when to use it
Use it when you need to tell two same-named zones of one seat apart. For most scripts
name is the better key.
Gotchas
Only unique within its seat. Always qualify it with seat — a bare
id matches a zone at every seat.
See also
name— usually what you want instead.
seatzoneinfo.name#
readonly name: string;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | async |
| Capability | none |
| Availability | both |
The zone's AUTHORED name — "HandZone", "CardZone1" — or "" for a zone that was never
named.
How, why and when to use it
This is the key scripts match on, and what
DealToOptions.zoneName takes. Name your zones in the seat-zone
editor and a script can address them; leave them unnamed and it cannot.
Gotchas
Empty string, not undefined, when unnamed — and unnamed is the default. The generated
default seat ring has no named zones at all, so a script written against names finds nothing
there.
Names are authored free text: nothing guarantees a seat has a CardZone1, and nothing stops
two zones sharing a name. Handle "not found" rather than assuming.
See also
seatzoneinfo.zoneType#
readonly zoneType: ZoneType;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | async |
| Capability | none |
| Availability | both |
What kind of zone this is — hand, area, hidden, and the rest.
How, why and when to use it
Use it to find a seat's hand without knowing what the author named it, or to skip zone types your rule does not apply to.
Gotchas
It can be null for a zone authored with no type. Do not assume every zone is typed.
See also
primary— which of several zones of a type is the main one.
seatzoneinfo.primary#
readonly primary: boolean;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | async |
| Capability | none |
| Availability | both |
True for the seat's primary zone of its type (a seat may own several).
Whether this is the seat's main zone of its type.
How, why and when to use it
A seat may own several zones of one type; the primary one is where the platform itself puts
things — it is the hand zone the built-in deal() targets, and the one dealTo uses when
you pass no zoneName.
Gotchas
Nothing guarantees exactly one primary zone per type. Treat it as a preference, not a uniqueness guarantee.
See also
seatzoneinfo.position#
readonly position: Vec3;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | async |
| Capability | none |
| Availability | both |
World-space centre [x, y, z].
The zone's world-space centre, [x, y, z].
How, why and when to use it
Only needed when you are placing something yourself rather than using
dealTo. Combine with size to scatter within the
zone instead of stacking at its centre.
Gotchas
It is the zone's centre, including its Y plane — drop something at exactly this point and it
sits in the zone plane. Add a little clearance, which is what dealTo does for you.
See also
seatzoneinfo.size#
readonly size: Vec3;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | async |
| Capability | none |
| Availability | both |
World-space box size [x, y, z].
The zone box's world-space size, [x, y, z].
How, why and when to use it
Use it to lay several objects out inside one zone — a row of cards along size[0], say —
rather than piling them at the centre.
Gotchas
This is the box's full extent, not a half-extent. Halve it before offsetting from
position.
See also
seatzoneinfo.rotationY#
readonly rotationY: number;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | async |
| Capability | none |
| Availability | both |
Y rotation in degrees. The zone's top edge is its local +Z edge; a card or deck that should
read toward it is placed at rotationY + 180, because card art points its top along the
card's own -Z.
The zone's yaw in degrees. It alone decides which way the zone faces: the zone's top edge —
the one Edit Mode marks with an arrow head — is its local +Z edge, wherever the zone sits.
How, why and when to use it
Seats face the table from different sides, so a card placed without this reads upside-down
for most of the table. Apply it when you orient something you placed yourself; dealTo
already does.
An entity turned to this yaw has its own +Z pointing at the zone's top edge. The top of card
art is the card's local -Z, so a card or a deck you place yourself wants
rotationY + 180 to read the way a dealt card does.
Gotchas
Degrees, not radians, and yaw only — zones are not pitched or rolled.
Nothing re-points a zone at the table centre. A zone its author turned to face away from the centre reports that yaw, and cards dealt into it follow it.
See also
deck.dealTo()— applies this for you.- Which way is "up" — the top edge and its arrow head in Edit Mode.
SnapPointInfo#
Surface A — table script · interface · 5 members
One scene snap point, as a script sees it — a plain copy, not a live reference.
Snap points are the positions a dropped piece is pulled to: the squares of a board, the slots
of a tableau. They carry a label an author sets in Edit Mode, which is what makes a move
log read "e2 to e4" rather than a pair of coordinates.
Only SCENE snap points are listed — the ones placed with the editor's snap-point tool. The
older per-board metadata.snapPoints / snapGrid forms have no id and no label, so
there is nothing useful to hand back for them.
One scene snap point as a script sees it — a plain copy, never a live reference. Returned by
world.getSnapPoints and
world.getSnapPointAt.
How, why and when to use it#
Snap points are the positions a dropped piece is pulled to — the squares of a board, the slots of a tableau. Their
label is what lets a script name a place: a move log that prints "e2 to e4" instead of two sets of coordinates.
Gotchas#
Only SCENE snap points appear — the ones placed with the editor's snap-point tool. The older per-board
metadata.snapPoints / snapGrid forms have no id and no label, so there is nothing useful to hand back for them.
It is a copy. Nothing on it updates when the scene is edited.
See also#
world.getSnapPointAt— which point a position is on.world.getSnapPoints— all of them.
Members#
| Signature | Description | Returns |
|---|---|---|
id |
string |
|
label |
The author's label, e.g. "e4". Snap points nobody named read "Snap point". |
string |
position |
World-space position [x, y, z]. |
Vec3 |
rotationY |
Yaw in degrees a piece is turned to when it snaps here. | number |
snapRadius |
How close (horizontally, in feet) a drop has to land to be pulled here. | number |
snappointinfo.id#
readonly id: string;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The snap point's stable identifier.
Returns
string.
How, why and when to use it
Compare ids, not labels, when asking whether two positions are on the same point — the move log does exactly that to ignore a piece picked up and put back where it was. Two points can share a label; they never share an id.
Gotchas
It is opaque. It is generated by the editor (snap-…) and means nothing to a player — print the
label.
See also
SnapPointInfo.label— the human name.
snappointinfo.label#
readonly label: string;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The author's label, e.g. "e4". Snap points nobody named read "Snap point".
The name an author gave the point in Edit Mode — "e4", "Discard", "Boardwalk".
Returns
string, up to 80 characters.
How, why and when to use it
This is the field to print. It is what turns a move log from coordinates into something that reads like a scoresheet.
Gotchas
An unnamed point reads "Snap point", the editor's default — not an empty string. A script that wants to fall
back to something better has to test for that literal.
Labels are not unique. Two points may carry the same one; use id
to tell them apart.
See also
world.getSnapPoints— checking a whole board is labelled.
snappointinfo.position#
readonly position: Vec3;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
World-space position [x, y, z].
Where the point is, in world space.
Returns
Vec3 — [x, y, z], in feet.
How, why and when to use it
Pass it to setPosition to put a piece on a named point — build a map from label to position once with
world.getSnapPoints, then place pieces by name.
Gotchas
y is where the point was authored, usually the table surface. A piece placed at exactly this height will sit
inside a board that stands above it; keep the piece's own height and take only x and z.
See also
SnapPointInfo.snapRadius— how far from here a drop still counts.
snappointinfo.rotationY#
readonly rotationY: number;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Yaw in degrees a piece is turned to when it snaps here.
The yaw, in degrees, a piece is turned to when it snaps here.
Returns
number.
How, why and when to use it
Use it when placing a piece on a point from a script, so it faces the way a hand-dropped piece would.
Gotchas
It only sets yaw. A piece keeps its own tilt and whether it is face-up.
See also
SnapPointInfo.position— where it is.
snappointinfo.snapRadius#
readonly snapRadius: number;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
How close (horizontally, in feet) a drop has to land to be pulled here.
How close a drop has to land, horizontally, to be pulled to this point.
Returns
number, in feet, above 0 and at most 2.
How, why and when to use it
Mostly for understanding why a drop did or did not snap. On a board it is typically a little under half the square pitch, so every point of every square belongs to exactly one point.
Gotchas
Overlapping radii are resolved by distance. Where two radii overlap, the nearer point wins — that is the rule
getSnapPointAt applies, and the one the table snaps with.
See also
world.getSnapPointAt— the rule this feeds.
DealToOptions#
Surface A — table script · interface · 4 members
What DeckObject.dealTo accepts.
What deck.dealTo() accepts: which seat, which zone, which way up,
and whether to stack.
How, why and when to use it#
seat is the only required field. Leave zoneName out to deal to the seat's primary hand
zone — the same target the built-in deal() uses.
Gotchas#
faceDown defaults to the card's own facing in the deck, not to false. If you care
which way up a dealt card lands, say so explicitly.
See also#
Members#
| Signature | Description | Returns |
|---|---|---|
seat |
Target seat, e.g. "red". |
string |
zoneName |
Authored zone NAME ("CardZone1", "HandZone"). Matched case-insensitively. Omit to deal to the seat's primary hand zone, which is what the built-in deal() does. |
string |
faceDown |
Face the card down. Defaults to the card's own facing in the deck. | boolean |
stack |
Add the card to whatever is already in the zone instead of laying it beside it, so a face-up row can be stacked on a face-down one. Defaults to false. |
boolean |
dealtooptions.seat#
seat: string;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | async |
| Capability | none |
| Availability | both |
Target seat, e.g. "red".
Which seat to deal to — "red", "blue", and so on. The only required field.
How, why and when to use it
Take it from world.getPlayers() so you only deal to seats
someone is actually sitting in.
Gotchas
Dealing to an unoccupied seat is not an error — the card is placed and simply sits there. Filter first.
See also
dealtooptions.zoneName#
zoneName?: string;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | async |
| Capability | none |
| Availability | both |
Authored zone NAME ("CardZone1", "HandZone"). Matched case-insensitively.
Omit to deal to the seat's primary hand zone, which is what the built-in
deal() does.
The AUTHORED zone name to deal into, e.g. "CardZone1".
How, why and when to use it
Omit it to deal into the seat's hand — the same destination, layout and ownership the
built-in deal() produces. Name a zone when you are laying out a tableau in front of a
player rather than filling their hand.
Matching ignores case and separators, so "CardZone1", "Card Zone 1" and "card-zone-1"
all find the same zone. The zone's authored id works too.
Gotchas
A name no zone matches deals nothing and writes a line to the event log naming the zones the seat actually has. It used to fail in silence, which meant a typo looked like "the deal partly worked".
See also
world.getSeatZones()— what names exist.
dealtooptions.faceDown#
faceDown?: boolean;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | async |
| Capability | none |
| Availability | both |
Face the card down. Defaults to the card's own facing in the deck.
Which way up the dealt card lands.
How, why and when to use it
Set it explicitly whenever the facing carries meaning — a face-down row that players may not look at, or a face-up row that everyone can read.
Gotchas
It defaults to the card's own facing in the deck, not to false. A deck sitting face down deals face-down
cards unless you say otherwise.
See also
dealtooptions.stack#
stack?: boolean;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | async |
| Capability | none |
| Availability | both |
Add the card to whatever is already in the zone instead of laying it beside it,
so a face-up row can be stacked on a face-down one. Defaults to false.
A pile is ONE object on the table, so stacking onto an occupied zone folds the two together and resolves with the pile, not with a loose card; the dealt card ends up on top and every card keeps its own face. Stacking into an EMPTY zone just places the card, and resolves with it as usual.
Add the card to whatever is already in the zone instead of laying it beside it.
How, why and when to use it
This is what makes a face-up row sit on a face-down one in the same zone. A pile is a single object on this table, so stacking onto an occupied zone folds the two together: the dealt card goes on top, every card keeps its own face, and the zone ends up holding one pile rather than two overlapping cards.
That is deliberate, not a shortcut. A standard card is 0.3 mm of sheet inside a 6 mm collider — the floor Bullet needs to solve a shape at this world scale — so two loose cards resting on each other always leave a visible gap you can read the lower card through. Folding them is also exactly what a player gets by picking a card up and dropping it on the pile by hand.
Gotchas
With stack: true, the call resolves with the PILE, not with a loose card, whenever the
zone already held something. Its cardId is the card on top. Stacking into an empty zone has
nothing to fold into, so it simply places the card and resolves with it as usual — a script
that deals a face-down row and then a face-up row over it therefore gets cards back from the
first pass and piles from the second.
The pile is built from what is physically inside the zone's footprint, so moving cards in or out by hand between deals changes what the next one lands on.
See also
DiceRollSummary#
Surface A — table script · interface · 9 members
One finished batch roll — what globalEvents.onDiceRollResult hands you.
value is null for a die that settled COCKED (resting past the tilt the face reader
accepts) or that carries no face table at all. Those dice add nothing to total and are
counted in cocked — the table never invents a number it could not read.
One finished batch roll, as a plain read-only record: who threw, where the dice landed, the notation, every die,
the total, and how many dice could not be read. It is the only argument
globalEvents.onDiceRollResult passes, and it is a
copy assembled by the host at the moment the last die stopped — not a live view of the dice, which go on
being ordinary entities you can move, keep or clear afterwards.
How, why and when to use it#
This is the record that makes "score the roll" a three-line handler instead of a state machine. Everything a
throw means is on it at once: total for scoring, notation for printing, dice for per-die detail,
actorPeerId/seat for attribution, and cocked for the case where the answer is "we could not read it". The
alternative — accumulating onDiceRolled events until you decide the batch is done — cannot tell two
simultaneous rolls apart and has no way to know how many dice to wait for.
Treat rollId as the key when you store anything about a roll, and objectId on each die as the way back to the
entity if you want to highlight, move or delete it.
Gotchas#
Nothing here is a handle. dice[i].objectId is a string; reach the entity with
world.getObjectById when you need to act on a die. By the time
you do, a player may already have picked it up.
It is not in the snapshot. The summary is emitted once and is not stored on the table, so a script that starts later, or a peer that joins later, never sees a roll that already happened. Keep your own record if you need history; the durable half of a roll is the ordinary event-log entry the host appends.
total is not dice.length sums. Cocked dice are in dice with value: null, are counted in cocked, and
are excluded from total.
See also#
globalEvents.onDiceRollResult— the only thing that hands you one.globalEvents.onDiceRolled— the per-die event that fires first.manifest.dice— which dice a game offers the roller.
Members#
| Signature | Description | Returns |
|---|---|---|
rollId |
Correlates with the roll request that produced it. | string |
actorPeerId |
string |
|
actorName |
string |
|
seat |
The roller's seat, or null when they hold none. |
string | null |
target |
"tray" (the roller's own bounded region) or "table". |
"tray" | "table" |
notation |
Dice notation, e.g. "3d6+1d20". |
string |
dice |
ReadonlyArray<{ readonly objectId: string; readonly preset: string; readonly sides: number; /** * The die's NUMBER result: the face's number, or the number a designed die gives that * face. nullwhen the face counts as text (seetext) or the die was cocked. */ readonly value: number | null; /** The physical face that landed up (1..sides). Absent when the die could not be read. */ readonly face?: number; /** The face's TEXT result on a designed die ("Hit"). Tallied, never added to total. */ readonly text?: string; /** The face's name on a designed die ("Skull"), when it has one. */ readonly name?: string; }> |
|
total |
Sum of the dice that reported a NUMBER. Text results are not added. | number |
cocked |
How many dice could not be read (a die with a text result WAS read and is not counted). | number |
dicerollsummary.rollId#
readonly rollId: string;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Correlates with the roll request that produced it.
The id of the roll this summary describes — the same id the roll request carried, and the same id every die in the batch is stamped with while it is still the roller's.
Returns
string. Always present and never empty. Unique per roll for the life of the session; it is not derived from
anything and carries no meaning beyond identity.
How, why and when to use it
Key anything you remember about a roll on this rather than on the roller or the time: a player may roll twice in
a second, and two players may roll at once. It is also what lets you match a summary to the dice still sitting on
the table — a die kept in the roller's custody carries the same rollId, so "highlight the dice from that roll"
is a comparison, not a search through positions.
Gotchas
It is not a table object id. rollId names the throw; dice[i].objectId names a die. Passing one where the
other is expected resolves to nothing.
It does not survive the session. Nothing persists a roll id, so it is useless as a saved-data key across loads.
See also
DiceRollSummary.dice— the dice this roll produced.globalEvents.onDiceRollResult— where the summary arrives.
dicerollsummary.actorPeerId#
readonly actorPeerId: string;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The peer id of the player who rolled. This is the identity half of attribution — always present, always stable for the length of that player's connection.
Returns
string. Never null, on every roll, including one thrown by a spectating host who holds no seat.
How, why and when to use it
Key per-player state on this, not on seat (which is null for a spectator and can change hands) and not on
actorName (which is a display string and is not unique). Turn enforcement — "it is not your roll" — compares
this against
world.getTurn's activePeerId.
Gotchas
It is a peer id, not a player record. Turn it into something human with
world.getPlayers, or just print actorName.
A peer id dies with the connection. The same person rejoining is a different peer. Anything that must outlive a disconnect belongs on the seat.
See also
DiceRollSummary.actorName— the printable half.DiceRollSummary.seat— the seat, when they hold one.PlayerInfo.peerId— the same identity on the roster.
dicerollsummary.actorName#
readonly actorName: string;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The roller's display name, captured at the moment the roll was summarised. It is what the chat line and the on-screen summary print, and it is here so a script does not have to resolve a peer id to say who rolled.
Returns
string. Always present. A player who has set no name gets whatever the table shows for them, so this is never
empty — but it is not unique, and two players may share it.
How, why and when to use it
Use it for anything a person reads and nothing a script decides. It is a snapshot of the name at emit time, which is exactly right for a chat line ("Ada rolled 3d6") and exactly wrong for a scoreboard that should follow a rename.
Gotchas
Never key on it. Two players may pick the same name, and one player may change theirs mid-session. Use
actorPeerId.
It is frozen at emit. A rename after the roll does not rewrite a summary you kept.
See also
DiceRollSummary.actorPeerId— the identity to key on.PlayerInfo.displayName— the same name on the roster.
dicerollsummary.seat#
readonly seat: string | null;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The roller's seat, or null when they hold none.
The seat the roller was sitting in, or null when they hold none. It is the label half of attribution — handy
for scoring a seat rather than a person, and for saying whose end of the table the dice are at.
Returns
string | null. A seat identifier such as north or south when the roller is seated; null means they hold
no seat — a spectator, or a host who never sat down. null is an ordinary outcome, not an error: a seatless
player can still roll.
How, why and when to use it
Score on the seat when the score belongs to the position rather than the person — seats outlive the peers that
occupy them, so a running total kept per seat survives someone dropping out and reconnecting. Score on
actorPeerId when it belongs to the player. Handle
null explicitly either way, or a seatless roll will quietly land in a bucket named "null".
Gotchas
Not the same thing as "where the dice are". A roll can be made into the roller's own region or straight onto
the table; that is target, not this.
A seat can change hands mid-session. A summary you stored records who sat there then.
See also
DiceRollSummary.actorPeerId— the identity that is always present.PlayerInfo.seat— the same seat on the roster.globalEvents.onSeatChanged— when it changes.
dicerollsummary.target#
readonly target: "tray" | "table";
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
"tray" (the roller's own bounded region) or "table".
Where the dice were thrown: "tray" for the roller's own bounded region, or "table" for a throw made onto the
table itself.
Returns
"tray" | "table". Exactly one of the two, always present, and always what the roller asked for — it is not a
description of where the dice ended up.
How, why and when to use it
The two modes mean different things to a game. A "tray" roll is a roll the roller is still holding — the dice
sit in a bounded region in front of their seat, cannot shove anything else on the table, and are removed when
they clear. A "table" roll puts real dice into the shared space to be picked up and kept. A script that deals
out dice as tokens cares about the difference; a script that only scores totals does not, and can ignore this
field.
Gotchas
"tray" is not "private". Dice are public: everyone sees the result either way. The tray bounds a roll, it
does not hide it.
Custody, not location, is what a later clear reads. A die that is picked up and placed stops being the roller's and survives every subsequent clear, whichever target it was rolled to.
See also
DiceRollSummary.seat— whose region a"tray"roll used.tableObjectDefinitionSchema.diceTray— the custody field on a die that is still the roller's.
dicerollsummary.notation#
readonly notation: string;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Dice notation, e.g. "3d6+1d20".
The roll in dice notation — "3d6+1d20" — built from the dice that were actually thrown and grouped by face
count, smallest die first.
Returns
string. Never empty; a single die reads "1d6". Groups are joined with + and are always <count>d<sides>
— there is no modifier term, because the table rolls dice and does not add bonuses for you.
How, why and when to use it
Print it. It is the one field written for a human to read at a glance, and it is what the chat line and the summary panel show. It exists so that every surface describing a roll describes it the same way instead of each one inventing a format.
Gotchas
Grouped by sides, not by preset. Two visually different six-siders read as 2d6. A player who rolled a
wooden d6 and a white d6 expects 2d6, not 1d6+1d6 — but it does mean the string cannot tell you which models
were involved. Read dice[i].preset for that.
Do not parse it. Everything the string encodes is already structured on dice; re-deriving it from text is
work that can only go wrong.
See also
DiceRollSummary.dice— the structured form of the same throw.manifest.dice— which dice a game offers in the first place.
dicerollsummary.dice#
readonly dice: ReadonlyArray<{
readonly objectId: string;
readonly preset: string;
readonly sides: number;
/**
* The die's NUMBER result: the face's number, or the number a designed die gives that
* face. `null` when the face counts as text (see `text`) or the die was cocked.
*/
readonly value: number | null;
/** The physical face that landed up (1..sides). Absent when the die could not be read. */
readonly face?: number;
/** The face's TEXT result on a designed die (`"Hit"`). Tallied, never added to `total`. */
readonly text?: string;
/** The face's name on a designed die (`"Skull"`), when it has one. */
readonly name?: string;
}>;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Every die in the throw, in the order the host settled them, each as a small record: which entity it is, which preset it was spawned from, how many faces it has, and what it landed on.
Returns
ReadonlyArray<{ objectId: string; preset: string; sides: number; value: number | null; face?: number; text?: string; name?: string }>.
Never empty for a roll that happened. The fields are:
| Field | Type | Notes |
|---|---|---|
objectId |
string |
The die on the table. Resolve it with world.getObjectById if you want to act on it. |
preset |
string |
The standard preset the die came from, e.g. die-d6. |
sides |
number |
Face count, from the preset. This is what notation groups on. |
value |
number | null |
The die's number result: the printed face on a stock die, or the number a designed die gives that face. null when the face counts as text, or when there was nothing to read. |
face |
number (optional) |
The physical face that landed up, 1..sides. Absent when the die could not be read. |
text |
string (optional) |
A designed die's text result for that face, e.g. "Hit". Never added to total. |
name |
string (optional) |
A designed die's name for that face, e.g. "Skull". |
How, why and when to use it
Use it whenever the individual faces matter rather than the total: counting successes over a threshold, looking
for a matching set, scoring highest-die, or highlighting the dice that produced a result. Filter out the nulls
first — that single line is the difference between "count the 6s" working and silently counting a cocked die as
not-a-6 when nobody knows what it was.
Each objectId is a live entity for as long as the die is on the table, which is how a script can move, colour
or delete the dice a roll produced.
Gotchas
value is null for a cocked die or a die with no face table — and also for a designed die's face that
counts as TEXT, which is not cocked: check text before treating null as unread. Unread dice are still in
this array and still in dice.length; they are excluded from
total and counted in
cocked. Never coerce null to 0 — a die that landed
unreadable is not a die that landed on zero.
The dice may already be gone. By the time an async handler resolves an objectId, the roller may have
cleared the roll or another script may have deleted the die.
world.getObjectById resolves null then.
preset is a plain string, not a narrowed union. It is whatever preset the die was spawned from; compare it,
do not switch exhaustively on it.
preset is the face layout, not the look. A game or seat die may be declared with a custom look: a project
model, another die's model, a tint or a material. preset still reports the face layout the value was read
against. A wooden-art d6 therefore reports die-d6, and so does a red faction d6 next to a blue one. Two dice in
one roll can share a preset and still be different dice. The summary does not say which declared entry a die
came from, so to tell them apart, resolve each objectId and read the entity.
See also
DiceRollSummary.total— the sum of the readable faces.DiceRollSummary.cocked— how many of these reported nothing.tableObjectDefinitionSchema.faceValue— the same number as it rides in the snapshot.
dicerollsummary.total#
readonly total: number;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Sum of the dice that reported a NUMBER. Text results are not added.
The sum of every die that reported a face. Dice that could not be read contribute nothing, so this is the answer
to the roll only when cocked is 0.
Returns
number. Always present, and 0 for a roll in which no die was readable — which is why 0 is not, on its own,
a meaningful result.
How, why and when to use it
It is the field most scripts want and the reason this event exists: "the active player rolls and scores the
total" is one line here and a state machine over
onDiceRolled. Read cocked first, and if it is non-zero
either ask for a re-roll or score the readable dice deliberately — do not do it by accident.
Gotchas
It is a plain sum of faces. No modifiers, no multipliers, no dropping the lowest. Anything a game does beyond
adding the numbers up is yours to do from
dice.
0 is ambiguous without cocked. An all-cocked roll and a roll of dice that genuinely print zero both total
0. cocked is what tells them apart.
See also
DiceRollSummary.cocked— read this before trusting the total.DiceRollSummary.dice— the faces the total came from.
dicerollsummary.cocked#
readonly cocked: number;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
How many dice could not be read (a die with a text result WAS read and is not counted).
How many dice in the throw failed to report a face. 0 on a clean roll — and anything above 0 means the total
is missing that many dice.
Returns
number. Always present, between 0 and dice.length. A die counts here when it settled past the tilt the face
reader accepts (leaning on a piece, wedged against a wall, resting between two faces), or when it is a custom die
model that carries no face table at all. A die declared in the manifest's dice or the seat template with a
custom model or modelPreset does have a face table: it reads its declared preset's. It is counted here only
if it settles cocked.
How, why and when to use it
This field is the table refusing to guess. The face reader will not name a face it cannot see squarely, so rather
than rounding to the nearest plausible number the die reports null and is counted here. Branch on it: ask for a
re-roll, tell the player which dice to nudge, or score the readable dice — but make it a decision your script
took, not one it drifted into by summing nulls away.
Gotchas
A cocked roll is not an error. Nothing failed; the dice landed awkwardly, exactly as real dice do. There is no exception and no retry.
"No face table" is permanent, not transient. A die imported as a custom model reports null every time, so a
re-roll never fixes it. If every roll of a particular die is cocked, that is the cause.
It counts dice, not readings. cocked === 1 on a five-die roll means total is the sum of four dice.
See also
DiceRollSummary.total— what the readable dice came to.DiceRollSummary.dice— which die reportednull.globalEvents.onDiceRolled— the same honesty rule, per die.
RollRequestDie#
Surface A — table script · interface · 3 members
One kind of die in a world.requestRoll: which die, and how many.
Give sides and the seat rolls its OWN die with that many faces when its seat template has one
(so its colour), else one of the game's dice, else the stock die. Or name a die with die: a
game die's key (its DICE entry id) or one of the seat's dice as "seat:<key>".
One kind of die in a world.requestRoll: which die, and how many. Give sides, or name a die with die.
| Field | Meaning |
|---|---|
sides |
Face count. The seat's own die with that many faces when its seat template has one, else one of the game's dice, else the stock die. |
count |
How many, 1 to 40 (default 1). |
die |
A die by its key: a game die's DICE entry id, or one of the seat's dice as "seat:<key>". |
How, why and when to use it#
{ sides: 6, count: 3 } is all most games need, and it already picks the seat's own colour. Use die when a
game has two six-siders that mean different things (a red attack die and a white defence die). Pass a list to
roll different dice together: [{ die: "attack", count: 2 }, { die: "defence" }].
Gotchas#
Each entry needs sides or die. With both, they must agree, or the request is refused (invalid-roll).
At most 8 entries and 40 dice in all, the same ceiling as any roll.
See also#
RollRequestSpec.dice— where these go.manifest.dice— the game's dice and their ids.
Members#
| Signature | Description | Returns |
|---|---|---|
sides |
Face count: 4, 6, 8, 10, 12, 20, or any face count one of your dice has. | number |
count |
How many (default 1). | number |
die |
A die by its key. With sides too, the two must agree. |
string |
rollrequestdie.sides#
sides?: number;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Face count: 4, 6, 8, 10, 12, 20, or any face count one of your dice has.
The face count to roll: 4, 6, 8, 10, 12, 20, or any face count one of your dice has.
How, why and when to use it
Without die, the seat's own die with this many faces is used when its seat template has one (so it is the
seat's colour), else one of the game's dice, else the stock die with that many faces. It is the simple way to ask
for "3d6" and let each seat roll in its own colour.
Gotchas
A face count no die has is refused (invalid-roll), for example 7.
See also
RollRequestDie.die— pick an exact die instead.
rollrequestdie.count#
count?: number;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
How many (default 1).
How many of this die to roll, 1 to 40. Absent means 1.
How, why and when to use it
Set it for a pool: { sides: 6, count: 3 } is 3d6.
Gotchas
The whole request rolls at most 40 dice, across every entry; more is refused (invalid-roll).
See also
RollRequestSpec.dice— several entries in one roll.
rollrequestdie.die#
die?: string;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
A die by its key. With sides too, the two must agree.
A die by its key instead of by its face count.
How, why and when to use it
The key is a game die's DICE entry id (the id in manifest.dice, or its
preset for an entry without one), or one of the seat's own dice as "seat:<key>". Use it when a game has two
dice with the same face count that mean different things.
Gotchas
A key that seat cannot roll is refused (invalid-roll): another seat's faction die, or a die the game no
longer declares. With sides too, the two must agree.
See also
RollRequestDie.sides— ask by face count instead.
RollRequestSpec#
Surface A — table script · interface · 6 members
What world.requestRoll asks a seat to roll.
What world.requestRoll asks a seat to roll.
| Field | Meaning |
|---|---|
dice |
One RollRequestDie or a list of them. Required. |
area |
"tray" (default): the seat's walled roll tray. "table": the open table. |
label |
Shown on the seat's dice button with the roll, up to 60 characters. |
timeoutSeconds |
Close the request after this long (1 to 600). Default: it waits. |
onTimeout |
"roll" (default): the host rolls for the seat. "cancel": it closes unrolled. |
clearAfterSeconds |
Clear these dice this long after they settle (0 to 3600, 0 keeps them). Overrides the game's setting. |
How, why and when to use it#
Most requests need only dice and a label. Add timeoutSeconds for a roll the game cannot wait on forever,
and clearAfterSeconds for a roll whose dice should not stay on the table (a bot's, or a quick check).
Gotchas#
The spec is checked strictly. A misspelt key (count written cnt), a wrong type or a value out of range
rejects the request with invalid-roll and names the problem in the script log.
It must be plain data. Functions and cycles are refused before the request is sent.
See also#
world.requestRoll— the call that takes it.RollRequestResult— what comes back.
Members#
| Signature | Description | Returns |
|---|---|---|
dice |
One die type, or several. At most 8 types and 40 dice in all. | RollRequestDie | readonly RollRequestDie[] |
area |
Where they land: the seat's walled "tray" (the default) or the open "table". |
"tray" | "table" |
label |
Shown on the seat's dice button with the roll, e.g. "Attack roll". At most 60 characters. |
string |
timeoutSeconds |
Close the request after this many seconds (1 to 600). Default: it waits. | number |
onTimeout |
When it times out: "roll" (the default) — the host rolls for the seat; "cancel" — no roll. |
"roll" | "cancel" |
clearAfterSeconds |
Clear these dice this many seconds after they settle (0 to 3600; 0 keeps them). Overrides the game's "Clear rolled dice after" setting for this roll. A die someone picks up is kept. |
number |
rollrequestspec.dice#
dice: RollRequestDie | readonly RollRequestDie[];
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
One die type, or several. At most 8 types and 40 dice in all.
The dice to roll: one RollRequestDie, or a list of up to 8. Required.
How, why and when to use it
Pass one entry for a simple pool ({ sides: 6, count: 3 }) and a list to roll different dice together.
Gotchas
At most 40 dice in all. Repeats of one die are merged, so the dice button shows one group per die.
See also
RollRequestDie— one entry.
rollrequestspec.area#
area?: "tray" | "table";
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Where they land: the seat's walled "tray" (the default) or the open "table".
Where the dice land: "tray" (the default) or "table".
How, why and when to use it
"tray" rolls into the seat's walled roll tray in front of it, so the dice cannot scatter the board. "table"
throws them onto the open table, for a game where the dice should land among the pieces.
Gotchas
The dice button shows which, so a player always knows where their dice will go.
See also
world.requestRoll— the request.
rollrequestspec.label#
label?: string;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Shown on the seat's dice button with the roll, e.g. "Attack roll". At most 60 characters.
A short title for the roll, shown on the seat's dice button with the dice ("Attack roll", "Saving throw").
How, why and when to use it
Say what the roll is for, so the player knows why the game is waiting on them.
Gotchas
Up to 60 characters; blank is the same as none. It is public, like the rest of the request.
See also
world.requestRoll— the request.
rollrequestspec.timeoutSeconds#
timeoutSeconds?: number;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Close the request after this many seconds (1 to 600). Default: it waits.
How long the seat has to roll, 1 to 600 seconds. The dice button shows a countdown.
How, why and when to use it
Give one to any roll the game cannot wait on forever. When it runs out,
onTimeout decides what happens. Absent: the request waits until it is rolled,
replaced or cancelled.
Gotchas
Ignored for a bot's or an empty seat, which the host rolls at once. The countdown uses the host's clock, so on another player's screen it can be a second out.
See also
RollRequestSpec.onTimeout— what the timeout does.
rollrequestspec.onTimeout#
onTimeout?: "roll" | "cancel";
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
When it times out: "roll" (the default) — the host rolls for the seat; "cancel" — no roll.
What happens when timeoutSeconds runs out: "roll" (the default) or
"cancel".
How, why and when to use it
"roll": the host rolls the dice for the seat, and the result has byHost: true and timedOut: true, so a game
never stalls on a player who walked away. "cancel": the request closes unrolled (cancelled: true,
timedOut: true), for an optional roll.
Gotchas
Without timeoutSeconds it never applies.
See also
RollRequestResult.timedOut— how a timeout shows in the result.
rollrequestspec.clearAfterSeconds#
clearAfterSeconds?: number;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Clear these dice this many seconds after they settle (0 to 3600; 0 keeps them). Overrides
the game's "Clear rolled dice after" setting for this roll. A die someone picks up is kept.
Clear these dice this many seconds after they settle, 0 to 3600. 0 keeps them until someone clears them.
How, why and when to use it
Absent: the game's Clear rolled dice after setting
(diceClearAfterSeconds) applies. Give a bot's rolls a
short time (10 seconds is plenty) so its tray does not fill up.
Gotchas
A die a player picked up is kept: picking it up makes it an ordinary piece. A die someone is holding when the time runs out is never cleared.
See also
diceClearAfterSeconds— the game-wide setting.
RollRequestResult#
Surface A — table script · interface · 9 members
How a world.requestRoll ended.
How a world.requestRoll ended.
| Field | Meaning |
|---|---|
requestId |
The request's id, also the finished roll's rollId. |
seat |
The seat that was asked. |
rolled |
The dice were rolled, and result holds them. |
result |
The finished DiceRollSummary, or null when not rolled. |
byHost |
The host rolled for the seat (a bot's or empty seat, its person left, or a timeout that rolls). |
bot |
The seat is a bot's. |
timedOut |
The timeout ran out. With onTimeout: "roll" the dice were still rolled. |
cancelled |
Closed without rolling. |
replaced |
Cancelled by a newer requestRoll for the same seat. |
How, why and when to use it#
Check rolled first. When it is true, result has the faces and the total. When it is false, the roll did
not happen: carry on without it, or ask again.
Gotchas#
rolled: true can come with timedOut: true: the host rolled when time ran out.
See also#
world.requestRoll— the call that returns it.DiceRollSummary— the finished roll.
Members#
| Signature | Description | Returns |
|---|---|---|
requestId |
The request's id. It is also the finished roll's rollId. |
string |
seat |
string |
|
rolled |
The dice were rolled, and result holds them. |
boolean |
result |
The finished roll (the same summary onDiceRollResult hands you), or null when not rolled. |
DiceRollSummary | null |
byHost |
The host rolled for the seat: a bot's or empty seat, its person left, or a timeout that rolls. | boolean |
bot |
The seat is a bot's (always rolled by the host). | boolean |
timedOut |
The timeout ran out (with onTimeout: "roll" the dice were still rolled). |
boolean |
cancelled |
Closed without rolling: replaced, cancelled, timed out with "cancel", or your scripts restarted. |
boolean |
replaced |
Cancelled because a newer requestRoll for the same seat replaced it. |
boolean |
rollrequestresult.requestId#
readonly requestId: string;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The request's id. It is also the finished roll's rollId.
The request's id. It is also the rollId of the finished roll.
How, why and when to use it
Use it to recognise the same roll reaching
globalEvents.onDiceRollResult, which fires for it too.
Gotchas
It is not a seat or a player id. It names one request only.
See also
DiceRollSummary.rollId— the same id on the roll.
rollrequestresult.seat#
readonly seat: string;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The seat that was asked to roll.
How, why and when to use it
Handy when one handler awaits several seats' requests.
Gotchas
It is the seat asked, not who rolled: the host may have rolled for it (byHost).
See also
RollRequestResult.byHost— who rolled.
rollrequestresult.rolled#
readonly rolled: boolean;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The dice were rolled, and result holds them.
true when the dice were rolled and result holds the finished roll; false when the request closed without a
roll.
How, why and when to use it
Branch on it first: it is the one field that says whether there is a roll to read.
Gotchas
false always comes with cancelled.
See also
RollRequestResult.result— the roll.
rollrequestresult.result#
readonly result: DiceRollSummary | null;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The finished roll (the same summary onDiceRollResult hands you), or null when not rolled.
The finished roll — the same DiceRollSummary that onDiceRollResult receives — or null
when nothing was rolled.
How, why and when to use it
Read total for the sum, dice for each face, and cocked before trusting the total.
Gotchas
A die that settled cocked has value: null and is counted in cocked, not guessed at.
See also
DiceRollSummary— every field of the roll.
rollrequestresult.byHost#
readonly byHost: boolean;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The host rolled for the seat: a bot's or empty seat, its person left, or a timeout that rolls.
true when the host rolled the dice for the seat instead of a person pressing ROLL.
How, why and when to use it
That happens at once for a bot's or an empty seat, when the seat's person leaves while the request is open, and
when the timeout runs out with onTimeout: "roll". Use it to word the log ("rolled by the table").
Gotchas
Also true in Edit Mode, which rolls every request at once.
See also
RollRequestResult.bot— a bot's seat.
rollrequestresult.bot#
readonly bot: boolean;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The seat is a bot's (always rolled by the host).
true when a bot holds the seat.
How, why and when to use it
A bot never presses a button, so its requests are always rolled by the host (byHost is true too).
Gotchas
It says who holds the seat, not who decided to roll: your script did.
See also
RollRequestResult.byHost— rolled by the host.
rollrequestresult.timedOut#
readonly timedOut: boolean;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The timeout ran out (with onTimeout: "roll" the dice were still rolled).
true when timeoutSeconds ran out.
How, why and when to use it
With onTimeout: "roll" the host still rolled (rolled: true); with "cancel" it did not (cancelled: true).
Gotchas
A person may press ROLL in the same moment the time runs out; the roll then still counts.
See also
RollRequestSpec.onTimeout— what a timeout does.
rollrequestresult.cancelled#
readonly cancelled: boolean;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Closed without rolling: replaced, cancelled, timed out with "cancel", or your scripts restarted.
true when the request closed without a roll.
How, why and when to use it
That is: replaced by a newer request for the seat (replaced), taken back with
world.cancelRollRequest, timed out with onTimeout: "cancel", or your scripts
restarted. Treat it as "this roll is not going to happen".
Gotchas
It is not an error, so it does not reject the promise.
See also
RollRequestResult.rolled— the other side.
rollrequestresult.replaced#
readonly replaced: boolean;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Cancelled because a newer requestRoll for the same seat replaced it.
true, with cancelled, when a newer world.requestRoll for the same seat replaced this one.
How, why and when to use it
Usually means your own script asked again; the newer request's promise carries the roll.
Gotchas
Only one request per seat is open at a time.
See also
world.requestRoll— one request per seat.
PlayerInfo#
Surface A — table script · interface · 9 members
One seated participant — a connected person or a game bot — as a table script sees it: read-only fields, no methods. You get PlayerInfo from
world.getPlayers() and from the onPlayerJoined and onPlayerLeft delegates. It is a copy, assembled by
the app from the room's peer list and seat assignments and pushed into the sandbox whenever any of it changes —
not a live view of a player.
How, why and when to use it#
You want to say "Ada moved out of turn" rather than "peer-8f2a moved out of turn", or to know how many people are
seated before starting. PlayerInfo is the only place a script can turn a peer id into anything human, and the
only place seats and teams are readable. The alternative is keeping your own map from the seat and team events,
which you will end up doing anyway for anything that has to survive a departure — the roster drops a peer as soon
as they disconnect. Read getPlayers() for the current picture; keep your own record for anything historical.
Example#
// content/scripting-api/examples/playerinfo.ts
// Scene script: PlayerInfo is a snapshot of the roster the host pushed into
// the sandbox. Read it fresh each time - the array world.getPlayers() returns
// is a copy, so a stored one goes stale as people join, sit and leave.
function describe(player: PlayerInfo): string {
const name = player.displayName ?? player.peerId;
const seat = player.seat ?? "standing";
const team = player.team ?? "no team";
return `${name} [${seat}, ${team}]${player.isHost ? " (host)" : ""}`;
}
function reportRoster(): void {
const players = world.getPlayers();
if (players.length === 0) {
world.log("Nobody is connected yet.");
return;
}
const seated = players.filter((player) => player.seat !== null);
world.log(`${players.length} connected, ${seated.length} seated.`);
for (const player of players) {
world.log(describe(player));
}
}
globalEvents.onPlayerJoined.add((player) => {
world.broadcast(`Welcome, ${describe(player)}.`);
reportRoster();
});
globalEvents.onSeatChanged.add(() => reportRoster());
reportRoster();
At a two-player table the script console prints 2 connected, 2 seated. followed by
Ada [north, no team] and Bo [south, no team].
Gotchas#
The list includes the peer running the script, and it is the one with isHost: true. The signaling layer's
peer list deliberately excludes the peer reading it (apps/web/src/net/signaling/signalState.ts,
filterPresencePeers), so the app adds the local participant back before pushing the roster into the sandbox
(apps/web/src/ui/scriptPlayers.ts, buildScriptPlayers). A script that means "everyone else" has to filter on
isHost. A solo table therefore returns one entry, not none.
Every field is a snapshot taken when the context was last pushed. A stored PlayerInfo does not update. Call
world.getPlayers() again rather than holding one.
In Edit Mode there is exactly one, and it is synthetic. ▶ Play Scripts pushes a single entry —
{ peerId: "editor", displayName: "Editor", seat: null, team: null, isHost: true }
(apps/web/src/ui/TableEditModeShell.tsx, EDITOR_SCRIPT_PLAYER). A script that branches on the roster behaves
differently under test than at a table; check peerId === "editor" if that matters.
onPlayerLeft hands you a partly filled one. That event carries only a peer id and a display name, and the
sandbox fills the other three from the roster if the peer is still in it — which it is not once they have
disconnected. See
onPlayerLeft.
See also#
world.getPlayers— the call that returns these.globalEvents.onPlayerJoined— the arrival, with aPlayerInfopayload.globalEvents.onSeatChanged— how to keep a seat map that outlives the roster.TurnInfo— whose turn it is, which is a separate question.- Host authority — why the script sees the table from the host's side.
Members#
| Signature | Description | Returns |
|---|---|---|
peerId |
string |
|
displayName |
string | null |
|
seat |
string | null |
|
team |
string | null |
|
isHost |
boolean |
|
isBot |
true for a bot: a seat played by this game's script instead of a person. A bot is a player in every other respect — it holds a seat, takes turns and appears in world.getPlayers(). |
boolean |
botId |
The bot's id from the manifest's bots list, or null for a person. |
string | null |
difficultyId |
The difficulty the bot is playing at, or null for a person or a bot that declares none. |
string | null |
deckId |
The id of the game deck the room owner chose for this bot in the lobby — a deck in your manifest's gameDecks file, which you can read with world.readData — or null when nobody chose one (your script chooses) and for a person. |
string | null |
playerinfo.peerId#
readonly peerId: string;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The peer's id: the only value that identifies a player to the rest of the API. It is what
EventContext.actor carries for a player-caused event, what
onTurnStarted and onTurnEnded report, and what TurnInfo.activePeerId
holds.
Returns
string. Never null and never empty. It is assigned by the signaling server when the peer joins and does not
change while they stay connected.
How, why and when to use it
Key everything on peerId — scores, per-player state, "has moved this turn". The alternative that looks
tempting is displayName, which is what you want to print and is a terrible key: it is optional, it is not
unique, and for the host's own chat line it is the literal "You". Use peerId for identity and displayName
for display, and look one up from the other with world.getPlayers().
Gotchas
Treat it as valid for one connection only. Nothing in the scripting API guarantees a returning player the
same id, and onPlayerLeft followed by onPlayerJoined is what a reconnection looks like from a script. Store
anything that must outlive a disconnect against a seat, and write it with world.setSavedData.
Comparing it to context.actor fails for three values. "Script", "Host" and "You" are not peer ids.
Filter those out before treating an actor as one.
The host's own id never appears in world.getPlayers(). The roster excludes the peer the script is running
on, so a lookup for the host's id always returns undefined.
See also
EventContext.actor— where a peer id arrives from an event.PlayerInfo.displayName— the value to print instead.TurnInfo.activePeerId— the same id, in the turn state.world.setSavedData— persisting per-player state that must outlive a connection.
playerinfo.displayName#
readonly displayName: string | null;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The name the player chose, for showing to people. It is the only human-readable string a table script can get
about a participant, and it is optional — the app passes the peer's displayName straight through, or null
when they have not set one.
Returns
string | null. null means the peer has no display name at all, which is the case for anyone who has not set
one; the app does not substitute a fallback here. Write player.displayName ?? player.peerId wherever a name has
to appear.
How, why and when to use it
Every message your script broadcasts to the table should name a person, not a peer id — Ada took 34s reads as a
game, peer-8f2a took 34s reads as a bug report. Use this field in world.broadcast and world.log output.
Never use it to decide anything: it is optional, it is not unique, and two players can choose the same name.
PlayerInfo.peerId is the identity.
Gotchas
Not the same as an entity's displayName. Entities have three names — id addresses, label is the slug,
displayName is the human name — and a table script cannot read an entity's displayName at all. This field is
about a person, and it is unrelated. See
A table script cannot read displayName.
onChatMessage carries a different string under the same name. The chat event's displayName is already
resolved for display and is the literal "You" for a message typed at the host machine. This field is the raw
peer name.
In Edit Mode it is always "Editor". ▶ Play Scripts pushes one synthetic player.
A bot's name is a first name the table gives it, not the bot's type. A seated bot reads as a friendly first
name — "Ava", "Kenji" — the same name its seat nameplate, the turn indicator, the Bots panel and the lobby
show, so ${player.seat} (${player.displayName}) prints Black (Ava). The name is cosmetic and per table: it is
derived from the bot's peerId and steers clear of the people at the table, so the same kind of bot can have a
different name at another table, and a bot can be renamed if someone with its name joins. What the bot is lives
in botId and difficultyId; key on those (or peerId), never on
the name.
See also
PlayerInfo.peerId— the identity to key on.world.broadcast— where a name belongs.globalEvents.onChatMessage— the otherdisplayName, and why it differs.- IDs, names and tags — the three names an entity has, which are a separate story.
playerinfo.seat#
readonly seat: string | null;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Which seat the player is sitting in. The app reads it from the room's assignment map at the moment the roster is pushed into the sandbox, so it is the same value the seat UI shows and the same one the hidden-hand system uses to decide who may see a hand.
Returns
string | null. A seat identifier such as north or south when the player is seated; null means they hold
no seat — a spectator, or someone who has joined but not sat down yet. null is the ordinary state for a peer
that has just arrived, not an error.
How, why and when to use it
"Start when all the seats are full" and "deal a card to every seated player" both need this field, and both go
wrong if you use the connected-peer count instead — spectators are connected and are not playing. Read it
alongside world.getPlayers() when you need the current picture, and keep your own peer-to-seat map from
onSeatChanged when you need to know where somebody
was after they have gone.
Gotchas
onPlayerJoined reports null here on a first join. A peer arrives before they take a seat, so the join
event reads an empty assignment. Use onSeatChanged for the moment they sit down.
onPlayerLeft reports null here in practice. The departure event carries no seat, and the sandbox's
fallback fills null once the peer is out of the roster.
A seat is not a team. They are separate assignments with separate events; a player can hold either, both or
neither. See PlayerInfo.team.
A seat outlives a player. Seats belong to the table, not to the peer, so a piece owned by a seat stays attached to that seat when its occupant leaves. Key persistent per-player state on the seat rather than on the peer id.
See also
globalEvents.onSeatChanged— the event that changes this value.PlayerInfo.team— the other assignment.world.getPlayers— the current roster.ObjectHandle.deal— the action that sends one item to every authored seat.
playerinfo.team#
readonly team: string | null;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Which team the player is on. Like the seat, it comes from the room's assignment map at the moment the roster was
pushed into the sandbox. Teams are optional at every table — a game that does not use them leaves this null for
everyone, forever.
Returns
string | null. A team identifier such as A or B when the player has been assigned one; null means no
team, which is both the default and a legitimate ongoing state.
How, why and when to use it
Team games need to know the sides before a round starts — even sides, per-team scoring, a shared hand. This is
where that lives. The reason not to use it for anything about visibility is that team-based reveals are the
host's job: the reveal-team-a and reveal-team-b actions exist in the engine and are deliberately outside the
script vocabulary, so a script that tries to show a card to one team has to model it as its own state instead.
Read team for game logic, and leave card visibility to the host.
Gotchas
Unavailable on a join. onPlayerJoined reports null here unless the sandbox's roster already knew the
peer, which on a first join it does not. Read it from world.getPlayers() a moment later, or subscribe to
onTeamChanged.
A team is not a seat. They change independently and raise separate events.
Scripts cannot set it. There is no table-scripting call that assigns a seat or a team; both are the host's UI. A script reacts to assignments, it does not make them.
See also
globalEvents.onTeamChanged— the event that changes this value.PlayerInfo.seat— the other assignment.world.getPlayers— the current roster.- Action vocabularies — why
reveal-team-aandreveal-team-bare not scriptable.
playerinfo.isHost#
readonly isHost: boolean;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Whether this peer is the room's host. The app computes it by comparing the peer's id against the room's
hostPeerId as it builds each roster entry (apps/web/src/ui/scriptPlayers.ts, buildScriptPlayers); on a solo
or offline table with no room record, the local peer is the authority and gets true.
Returns
boolean. Exactly one entry in the roster has it set — the roster includes the local participant, and a
table script only ever runs on the host, so that entry is you. In Edit Mode the single synthetic player reports
true for the same reason.
How, why and when to use it
The useful thing it gives you is not "am I the host" — you are, or your script would not be executing — but
which roster entry is you. world.getPlayers().find(p => p.isHost) is how a script separates itself from the
other participants without needing to know its own peer id, which the table-scripting surface does not otherwise
expose. Use it to exclude yourself from a deal, to attribute a broadcast, or to pick the seat that does not get
dealt into.
Gotchas
It identifies the machine, not a seat. The host may be a spectator, or seatless. Check seat before treating
the isHost entry as a player in the game.
Every other entry is false, and that is not a gap. There is one host per room by construction.
No delegate reports a change to it. There is no host-changed event among them, so a script cannot react to
hosting moving during a migration. Call world.getPlayers() again if you need the current answer — the roster is
refreshed whenever it changes.
In Edit Mode the entry is synthetic. ▶ Play Scripts pushes one player with peerId: "editor" and
isHost: true (apps/web/src/ui/TableEditModeShell.tsx, EDITOR_SCRIPT_PLAYER), so anything keyed on a real
peer id behaves differently under test than at a table.
See also
PlayerInfo.peerId— the identity the comparison is made against.world.getPlayers— the roster, and who is in it.- Host authority — why a script is always on the host already.
playerinfo.isBot#
readonly isBot: boolean;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
true for a bot: a seat played by this game's script instead of a person. A bot is a
player in every other respect — it holds a seat, takes turns and appears in
world.getPlayers().
true for a bot — a seat played by this game's script instead of a person. A bot is a player in every other
respect: it holds a seat, takes turns, and appears in world.getPlayers() and in the player events.
Returns
boolean. Always present: false for every person, including the synthetic Edit Mode player.
How, why and when to use it
When a rule should treat bots differently — skip a "your turn!" chat ping, keep a bot out of a vote, mark its
seat on a scoreboard. bots.list is this same roster already
filtered.
Gotchas
A bot's peerId always starts with bot:. Where you only have an id (a turn's activePeerId, an event's
actor), that prefix answers the same question without a roster lookup.
isHost is false for a bot. Bots run on the host, but they are not it.
A bot's displayName is a first name, not its type. Players see the bot named like a person (with a bot icon
beside it) and its type and difficulty underneath — "Othello AI · Hard". Your script gets the same first name in
displayName; read botId for which bot it is.
See also
PlayerInfo.botIdandPlayerInfo.difficultyId— the two fields only a bot fills in.- Bots and AI — registering what a bot does.
playerinfo.botId#
readonly botId: string | null;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The bot's id from the manifest's bots list, or null for a person.
Which of the game's declared bots this is: its id in the manifest's
bots list.
Returns
string | null. null for a person; always a string for a bot.
How, why and when to use it
To tell your game's bots apart outside their own turns — for example to give the "Hard" bot different starting
resources from the "Easy" one in a onPlayerJoined handler.
Gotchas
Several seated bots can share one botId. It names the kind, not the instance; use peerId for the
instance.
This is the bot's identity; its displayName is not. A bot's
displayName is a cosmetic first name the table picks ("Ava"), and it can differ from
table to table. Anything that has to recognise a kind of bot — scoring it, remembering how strong it played —
keys on botId and difficultyId.
See also
PlayerInfo.isBot— the flag to check first.BotTurnContext.botId— the same value inside a bot's turn.
playerinfo.difficultyId#
readonly difficultyId: string | null;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The difficulty the bot is playing at, or null for a person or a bot that declares none.
The difficulty a bot is playing at: the id of one of its declared
difficulties.
Returns
string | null. null for a person, and for a bot that declares no difficulties.
How, why and when to use it
To show it ("Othello Bot — Hard") or to scale something outside the bot's own turn, such as a handicap set up when the bot sits down.
Gotchas
The host can change it during a game. globalEvents has no event for that; read world.getPlayers() again
when you need the current value.
See also
BotTurnContext.difficultyId— the value your bot's turn reads.
playerinfo.deckId#
readonly deckId: string | null;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The id of the game deck the room owner chose for this bot in the lobby — a deck in your
manifest's gameDecks file, which you can read with world.readData — or null when
nobody chose one (your script chooses) and for a person.
The game deck the room's owner chose for this bot in the lobby: the id of one deck in your manifest's
gameDecks file.
Returns
string | null. The bare deck id ("hope-light", not "game:hope-light"). null for a person, and for a bot
nobody chose a deck for — which is every bot in a ranked room.
How, why and when to use it
When your script builds a bot's deck. A bot has no library, so the platform does not put a deck on the table
for it: your script does, and this is how it learns what the owner asked for. Read your decks file with
world.readData (it is a declared .json file of your pack like any
other), find the deck with this id, and load its cards. When the value is null, choose one yourself — by the
bot's difficultyId, by the human's deck, or at random from a level.
Gotchas
Check the deck still exists. The id was valid against the file the lobby read; a deck you removed or renamed in a later version of the pack can still arrive from a room that was set up before you published. Fall back to your own choice rather than failing.
The lobby's pairing check is not a guarantee. distinctBy
refuses a bot deck that clashes with a deck whose value the lobby knows, but a person's own saved deck carries no
side, so a clash with one is only visible to your script. Check the pairing at the table if your rules need it.
Ranked rooms never set it. The server refuses a bot deck while the room is ranked and clears every bot's deck when ranked is switched on, so a ranked game always plays your script's own choice.
See also
- Game bots: lobby — how the owner hands a bot a deck.
gameDecks— the file format.
TurnInfo#
Surface A — table script · interface · 3 members
The table's turn state, as two read-only fields: whether turn order is running at all, and whose turn it is. You
get it from world.getTurn(), which answers from context the host
pushes into the sandbox — so it is a copy that is refreshed whenever the turn changes, not a live read.
How, why and when to use it#
You need to know whose turn it is inside some other handler — a drop, a chat command, an action — to decide
whether to allow it. world.getTurn() is the right tool there because it answers immediately, with no round-trip
and no await. The alternative, subscribing to onTurnStarted and keeping the active peer in a variable, is what
you want when the transition is the event you care about; it is redundant when you only need the current
answer. Use getTurn() for a check, onTurnStarted for upkeep.
Example#
// content/scripting-api/examples/turninfo.ts
// Scene script: gate an action on whose turn it is. TurnInfo has two fields
// and they move together - when turn order is off, enabled is false and
// activePeerId is null, so check enabled before trusting the peer id.
function activePlayerName(): string {
const turn: TurnInfo = world.getTurn();
if (!turn.enabled) {
return "turn order is off";
}
if (turn.activePeerId === null) {
return "turn order is on with nobody active";
}
const player = world.getPlayers().find((entry) => entry.peerId === turn.activePeerId);
return player === undefined ? turn.activePeerId : (player.displayName ?? turn.activePeerId);
}
globalEvents.onObjectDropped.add((entity, context) => {
const turn = world.getTurn();
if (!turn.enabled || turn.activePeerId === null) {
world.log(`${entity.id} moved with no turn order in force.`);
return;
}
if (context.actor !== turn.activePeerId) {
world.broadcast(`It is ${activePlayerName()}'s turn, not ${context.actor}'s.`);
return;
}
world.log(`${context.actor} moved ${entity.name ?? entity.kind} on their own turn.`);
});
globalEvents.onTurnStarted.add(() => world.log(`Active: ${activePlayerName()}.`));
world.log(`Turn gate is running. Active: ${activePlayerName()}.`);
With turn order off the script console prints Turn gate is running. Active: turn order is off.; with it on, a
drop by the wrong player puts It is Ada's turn, not peer-3c11's. into the table chat.
Gotchas#
A fresh object every call. world.getTurn() builds a new record from the sandbox's cached context each time,
so two calls are never the same object and holding one gives you a stale answer.
The turn order itself is not readable. There is no field for the sequence of players, the turn number, or the
per-turn action limit. Track those from onTurnStarted and onTurnEnded if you need them.
context.actor is not always comparable to activePeerId. A grab on the host machine reports the actor
"You", not a peer id, so a strict comparison treats it as the wrong player. Handle the three fixed actor
strings explicitly. See EventContext.actor.
In Edit Mode turn order is always off. ▶ Play Scripts pushes { enabled: false, activePeerId: null }, so a
turn-gated rule never triggers under test.
See also#
world.getTurn— the call that returns this.globalEvents.onTurnStarted— the transition, with the seat and team.globalEvents.onTurnEnded— the other half of the transition.PlayerInfo— turningactivePeerIdinto a name.EventContext.actor— why an actor is not always a peer id.
Members#
| Signature | Description | Returns |
|---|---|---|
enabled |
boolean |
|
activePeerId |
string | null |
|
seats |
The seats whose turn the table is showing: what world.setTurn last said, else the active peer's seat while turn mode is on, else none. |
readonly string[] |
turninfo.enabled#
readonly enabled: boolean;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Whether turn order is switched on for this table. It mirrors the host's turn-order setting, and the sandbox
coerces anything that is not the boolean true to false, so a missing or malformed context reads as "off"
rather than throwing.
Returns
boolean. false on a table where nobody has turned turn order on — which is the default, and the state of most
casual tables.
How, why and when to use it
Check this before you read activePeerId. A rule that enforces
turns has to do nothing at all on a table where turns are not in use, and the distinction between "turn order is
off" and "turn order is on and nobody is active" is a real one your messages should not blur. The alternative —
testing activePeerId !== null alone — happens to work today and reads as if the two fields were independent,
which is exactly the assumption that breaks when a game switches turn order on mid-session.
Gotchas
No delegate reports it changing. Switching turn order on raises onTurnStarted for the first player, and
switching it off raises nothing at all. A script that only listens never learns that turns stopped; poll
world.getTurn() where it matters.
In Edit Mode it is always false. ▶ Play Scripts pushes { enabled: false, activePeerId: null }, so turn
logic cannot be exercised there.
It says nothing about action limits. The table's per-turn action limit is enforced by the app before an intent reaches the runtime and is not exposed to table scripting at all.
See also
TurnInfo.activePeerId— the field to read once this istrue.world.getTurn— the call that returns both.globalEvents.onTurnStarted— the only event raised when turns begin.
turninfo.activePeerId#
readonly activePeerId: string | null;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The peer whose turn it is. The sandbox passes the host's value through, normalizing undefined to null, so the
field is either a real peer id or null and never anything in between.
Returns
string | null. null has two causes, and they are not the same situation: turn order is switched off, or
turn order is on but no player is active. Read
TurnInfo.enabled to tell them apart.
How, why and when to use it
This is the id you compare an actor against to answer "was that their move?". Pair it with a lookup in
world.getPlayers() when you want to name the player in a message, because the raw id means nothing to anybody
at the table. The alternative to reading it here is capturing turn.peerId from
onTurnStarted into a variable, which is equivalent and
one more thing to keep in sync — read it from world.getTurn() at the point of the check instead.
Gotchas
Comparing it to context.actor fails for a host-side grab. A pickup or drop made at the host machine
reports the actor "You", not a peer id, so a strict comparison marks it as the wrong player. Handle "You",
"Script" and "Host" before falling through to the comparison. See
EventContext.actor.
The id is not always in the roster. world.getPlayers() excludes the peer the script is running on and drops
anyone who has disconnected, so a lookup can return undefined for a perfectly valid active peer — the host's
own turn, for instance. Fall back to printing the raw id.
It changes without your script being told, in one case. Switching turn order off leaves it null and raises
no event.
See also
TurnInfo.enabled— the field that disambiguatesnull.PlayerInfo.peerId— the same identity, on the roster side.globalEvents.onTurnStarted— the event that changes this value.EventContext.actor— why a comparison against it needs care.
turninfo.seats#
readonly seats: readonly string[];
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The seats whose turn the table is showing: what world.setTurn last said, else the active
peer's seat while turn mode is on, else none.
The seats whose turn the table is showing: what world.setTurn last
said, otherwise the active player's seat while turn mode is on, otherwise none.
Returns
readonly string[] of seat ids. Empty when it is nobody's turn, when turns are not in use, and once the match has
ended.
How, why and when to use it
Read it when your script needs to know what the players can see, for example a bot deciding whether to act. If your script tracks the turn itself, its own record is the one to trust; this is the table's display.
Gotchas
It can lag your own call by a moment. The value is refreshed when the table's state comes back to the script,
so reading it on the line after world.setTurn may still show the previous turn.
See also
world.setTurn— set it.TurnInfo.activePeerId— turn mode's active player.
BotDifficultyInfo#
Surface A — table script · interface · 5 members
A bot's difficulty and its dials, from the manifest.
For an AI bot the dials come from the difficulties entry with the same id on the model it
plays with at that difficulty (BotTurnContext.modelId); a scripted
bot's difficulties declare a name only, so its dials are null and params is empty.
A bot's difficulty and its dials, as BotTurnContext.difficulty hands it to the
bot's own onTurn. Everything in it is public manifest data.
How, why and when to use it#
Use it to size your bot's thinking: simsPerMove and temperature go to ai.mcts as simulations
and temperature; params holds any other number you declared for the difficulty.
Gotchas#
Scripted bots get names only. A scripted bot's difficulties declare an id, a label and a description, so its
dials are null and its params empty — keep a scripted bot's numbers in your script, keyed by id.
See also#
manifest.aiModels[].difficulties— where the dials are declared.
Members#
| Signature | Description | Returns |
|---|---|---|
id |
The difficulty's id (the same as ctx.difficultyId). |
string |
label |
Its name as players see it. | string |
simsPerMove |
Searches per move (simsPerMove): pass it to ai.mcts as simulations. null when not declared. |
number | null |
temperature |
How adventurously to pick among good moves (temperature): pass it to ai.mcts. null when not declared. |
number | null |
params |
Your own numeric settings for this difficulty (params), by name. Empty when none are declared. |
Readonly<Record<string, number>> |
botdifficultyinfo.id#
readonly id: string;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
The difficulty's id (the same as ctx.difficultyId).
The difficulty's id — the same value as ctx.difficultyId.
Returns
string.
How, why and when to use it
Key a scripted bot's own numbers by it — a scripted bot's difficulties carry no dials, only this id and a label.
Gotchas
It is the bot's id for the difficulty, which is also the id the model's preset is looked up by: give a bot and
its model the same difficulty ids, or the dials come back null.
See also
botdifficultyinfo.label#
readonly label: string;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Its name as players see it.
The difficulty's name as players see it in the lobby and the Bots panel: the bot's own label for this id, else the model difficulty's.
Returns
string. Plain text from the manifest.
How, why and when to use it
For a chat line or a label that names the bot's strength the way players saw it chosen ("Minimax (Hard) passes").
Gotchas
It is author text. Show it as text; never build markup or code from it.
See also
botdifficultyinfo.simsPerMove#
readonly simsPerMove: number | null;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Searches per move (simsPerMove): pass it to ai.mcts as simulations. null when not declared.
The model difficulty's simsPerMove: how many searches a move at this difficulty should spend. Pass it to
ai.mcts as simulations.
Returns
number | null. null when the difficulty does not declare it, and always for a scripted bot.
How, why and when to use it
simulations: ctx.difficulty?.simsPerMove ?? 64 — the fallback covers a bot with no difficulty.
Gotchas
It is not applied for you. ai.mcts runs the simulations you pass, whatever the manifest says.
See also
botdifficultyinfo.temperature#
readonly temperature: number | null;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
How adventurously to pick among good moves (temperature): pass it to ai.mcts. null when not declared.
The model difficulty's temperature: how adventurously to pick among the moves the search liked. Pass it to
ai.mcts as temperature.
Returns
number | null. null when the difficulty does not declare it, and always for a scripted bot.
How, why and when to use it
temperature: ctx.difficulty?.temperature ?? 0 — 0 plays the most-visited move every time.
Gotchas
Randomness is not weakness. A high temperature makes occasional terrible moves; fewer simulations weakens a bot more smoothly.
See also
botdifficultyinfo.params#
readonly params: Readonly<Record<string, number>>;
| Badge | Value |
|---|---|
| Authority | host-only |
| Timing | sync |
| Capability | none |
| Availability | both |
Your own numeric settings for this difficulty (params), by name. Empty when none are declared.
The model difficulty's params: your own numbers for this difficulty, by name — a search depth, a bluff rate,
anything your bot reads.
Returns
Readonly<Record<string, number>>. Empty when none are declared, and always for a scripted bot. Frozen.
How, why and when to use it
const depth = ctx.difficulty?.params["depth"] ?? 2;
Gotchas
turnBudgetMs is read by the table too: it sets the bot's time for a turn (clamped by the host).
See also
UiWidgetPatch#
Surface A — table script · type
A change to a SHOWING widget (ui.update), or the overrides merged over a re-shown one: any
widget field except id. A null REMOVES that field ({ timing: null } makes a timed
banner stay); a field you leave out keeps its value. kind may change but not be removed.
declare type UiWidgetPatch = {
[K in Exclude<keyof UiWidget, "id" | "kind">]?: UiWidget[K] | null;
} & { kind?: UiWidget["kind"] };
A change to a widget: what ui.update takes as its
patch, and what ui.show takes as overrides when it
re-shows a widget by id. It has every UiWidget field
except id, each optional, and each (except kind) may also be null.
| You pass | What happens to that field |
|---|---|
| Leave it out | It keeps its value. |
| A value | It replaces the field whole. |
null |
It is removed, as if the widget had never had it. |
kind may change but cannot be null: a widget always has a kind.
How, why and when to use it#
Pass only what changes. { text: "Red leads" } rewrites one line and leaves the placement,
audience, theme and timing alone.
Use null to take something off a widget rather than to set it to nothing: { timing: null }
removes a widget's duration, so a hint or status that was going to close after 20 seconds
stays until you hide it; { when: null } shows a widget to everyone in its audience again;
{ theme: null } returns it to the platform's default look; { dismissible: null } takes its ✕
away.
Gotchas#
The merge is one level deep. A theme, placement, timing, actions or choices you pass
replaces that whole field. To change one button, pass the full button list; to change the tone,
pass the whole theme you want.
A banner always has a clock. Without a timing.duration a banner lasts 4 seconds, so
{ timing: null } on a banner does not make it stay: it falls back to 4 seconds, counted from
when it was first shown. Use a status or hint for a message that should stay.
The result is checked like a new widget. If removing or changing a field leaves an invalid
widget (a prompt with neither actions nor choices, a defaultAction that names no button),
the whole change is refused with a diagnostic and the widget stays as it was.
ui.update cannot turn a question into something else. Changing kind between prompt or
choice and any other kind is refused as "not showing"; show it again with
ui.show instead.
undefined is not null. A field set to undefined is treated as left out and keeps its
value. Only null removes.
See also#
ui.update— with an example that removestiming.ui.show—overrideson a re-show.UiWidget— every field.ModUiWidgetPatch— the mod twin.
ScriptVariableSpec#
Surface A — table script · type
One declared variable — a typed slot the script needs filled in, and the filters the inspector enforces when somebody fills it.
label is the row's caption (it falls back to the property name), and
description is its hint. kind and tag narrow which entities may be
dropped on an object/objectList row; min/max bound the numeric
editor; default is the value a scalar reads when nothing is bound.
declare type ScriptVariableSpec =
| { type: "object"; kind?: ObjectKind; tag?: string; label?: string; description?: string }
| { type: "objectList"; kind?: ObjectKind; tag?: string; label?: string; description?: string }
| { type: "spawnable"; label?: string; description?: string }
| { type: "zone"; label?: string; description?: string }
| { type: "number"; label?: string; description?: string; default?: number; min?: number; max?: number }
| { type: "string"; label?: string; description?: string; default?: string }
| { type: "boolean"; label?: string; description?: string; default?: boolean }
| { type: "vector3"; label?: string; description?: string; default?: Vec3 }
| { type: "color"; label?: string; description?: string; default?: string }
| { type: "seat"; label?: string; description?: string; default?: string };
One declared slot, as written inside declareVariables: what the variable is, and which
things the inspector will let somebody put in it. It is a declaration, never a value — nothing you write here
is evaluated, and none of it decides what the variable reads back. That is
ScriptVariableValue's job.
The ten types#
type |
What can be bound to it | Extra fields it accepts |
|---|---|---|
"object" |
one entity on the table | kind, tag |
"objectList" |
several entities on the table | kind, tag |
"spawnable" |
a standard-library preset, or a prefab authored in this project | — |
"zone" |
one seat zone | — |
"number" |
a number | default, min, max |
"string" |
text | default |
"boolean" |
true or false |
default |
"vector3" |
an [x, y, z] triple |
default (a Vec3) |
"color" |
a #rrggbb colour |
default (a #rrggbb string) |
"seat" |
a seat id | default |
label and description are accepted on every one of them: label is the row's caption and falls back to the
property name you declared it under, description is the row's hint.
How, why and when to use it#
Write the narrowest declaration that is still true. kind and tag are not decoration — they are what the
inspector uses to grey out the entities that cannot go in the slot, and they travel into the sandbox and are
re-checked on every read, so a wrongly-typed binding reads null instead of handing your script a card
where it expected a deck — and starts resolving if a matching entity later takes that id. kind also pays for itself at authoring time: declaring { type: "object", kind: "deck" } makes the
variable read as a DeckObject, so drawCard() is offered and a typo is caught in the editor.
Prefer a spawnable over a hard-coded presetId string whenever a script creates pieces. Both end up in the
same spawn intent, but the presetId string is a name only you know and it breaks silently when the project's
assets are re-authored; the spawnable is a row somebody can re-point without opening the script.
The scalar types exist for the numbers a script would otherwise carry as constants at the head of the file — how many cards to deal, how long to wait, which colour to tint something. Anything a table owner might reasonably want to change belongs in a declaration; anything that would break the rules of the game if it changed belongs in the code.
Gotchas#
A filter on the wrong type is a save-time diagnostic, not an ignored field. kind and tag are accepted
only on object and objectList, and min/max only on number. Writing { type: "string", max: 20 }
rejects the declaration, and the script keeps the declarations it last saved with.
default must match the declared type, and only the scalars have one. A default on an object,
objectList, spawnable or zone is meaningless — those read null (or []) when nothing is bound, and
there is nothing to substitute. A color default must be a full #rrggbb string; #fff does not parse.
kind is stricter here than ObjectKind looks. ObjectKind accepts any string so that a
future kind still type-checks, but a declaration's kind is validated against the eleven real kinds
(card, deck, die, token, board, bag, custom, card-holder, button, table, coin). A misspelled kind is a
diagnostic, not a filter that never matches.
min and max bound the editor, not the read. They constrain the inspector's numeric field. They are not
re-applied when the value reaches your script, so clamp anything you are about to loop over — the example on
declareVariables does.
Thirty-two declarations per script, and the whole literal is rejected past that. See
declareVariables for why the cap exists.
See also#
declareVariables— the call these specs go into.ScriptVariableValue— what eachtypereads back as.ObjectKind— the kinds akindfilter may name.SeatZoneInfo— what azonevariable resolves to.
ScriptVariableValue#
Surface A — table script · type
What one declared variable READS AS — the resolved value, not the binding.
Reference types resolve lazily, on every read: an object whose bound entity
is gone (deleted, never loaded, still inside a container) reads null rather
than handing back a stale handle or throwing, and an objectList simply
omits the entries that are not on the table right now. Declaring a kind
narrows the handle type too, so { type: "object", kind: "deck" } reads as
DeckObject | null and offers a deck's API.
declare type ScriptVariableValue<S> =
S extends { type: "object"; kind: infer K } ? (K extends ObjectKind ? ObjectHandleForKind<K> | null : ObjectHandle | null) :
S extends { type: "object" } ? ObjectHandle | null :
S extends { type: "objectList"; kind: infer K } ? (K extends ObjectKind ? ObjectHandleForKind<K>[] : ObjectHandle[]) :
S extends { type: "objectList" } ? ObjectHandle[] :
S extends { type: "spawnable" } ? SpawnObjectOptions | null :
S extends { type: "zone" } ? SeatZoneInfo | null :
S extends { type: "number" } ? number :
S extends { type: "boolean" } ? boolean :
S extends { type: "vector3" } ? Vec3 :
S extends { type: "string" | "color" } ? string :
S extends { type: "seat" } ? string | null :
never;
What one declared slot reads back as — the resolved value, not the binding. You never write this type; it is
how declareVariables turns each ScriptVariableSpec into the
property type your script actually sees, so { type: "object", kind: "deck" } reads as DeckObject | null and
offers a deck's API rather than a bare ObjectHandle's.
What each type reads as#
Declared type |
Reads as | When nothing usable is bound |
|---|---|---|
"object" |
ObjectHandle | null, narrowed to the declared kind |
null |
"objectList" |
ObjectHandle[], narrowed to the declared kind |
[], and entries that are not on the table are simply absent |
"spawnable" |
SpawnObjectOptions | null |
null |
"zone" |
SeatZoneInfo | null |
null |
"number" |
number |
the declared default, else 0 |
"string" |
string |
the declared default, else "" |
"boolean" |
boolean |
the declared default, else false |
"vector3" |
Vec3 |
the declared default, else [0, 0, 0] |
"color" |
string |
the declared default, else "#ffffff" |
"seat" |
string | null |
the declared default, else null |
How, why and when to use it#
The point of the table above is the right-hand column: a reference variable's normal, expected value is
null. Bound entities get deleted, drawn into a deck, put in a bag, or belong to a save that has not finished
loading. Rather than throw, or hand back a handle that addresses nothing, the read returns null — so a script
that checks is a script that keeps running, and a script that does not is one that fails at the worst moment.
Treat if (!vars.x) return; as the first line of anything that touches a reference variable, exactly as you
would treat the null from world.getObjectById.
The scalars have the opposite property: they never read null (except seat, which has no sensible empty
number to fall back on), so a number variable is safe to use in arithmetic without a guard. That asymmetry is
deliberate — it means an unconfigured script still runs with sensible values rather than dying on line one.
Gotchas#
The reads are synchronous, and they are live. Every property is a getter. Reading vars.landingBox twice
either side of an await can legitimately give you a handle and then null, because the entity left the table
in between. Read it once into a local when you need a stable answer for one operation, and re-read it on the
next.
A bound entity that no longer matches the declared filter reads null too. The kind/tag filter travels
to the sandbox beside the bound id and is re-checked on the same read as liveness, so re-tagging a piece can
empty a slot that the inspector still shows as bound — and re-tagging it back fills the slot again.
An objectList never contains holes. Missing entries are omitted, not left as null, so its length is the
number of entities you actually got — not the number somebody bound. If the count matters, compare it against
what you expect rather than assuming.
spawnable and zone read a fresh copy every time. Mutating what you read back changes nothing; spread it
into the call instead (world.spawnObject({ ...vars.dieTemplate, position })). A spawnable bound to a prefab
carries the prefab's scale, rotation and color as well as its kind, name, metadata and tags, so the copy
matches the prefab; one bound to a preset carries no size, rotation or color. A zone is likewise a snapshot
copy, with the same caveats as SeatZoneInfo.
A binding is never resolved once and frozen — it is lazy in both directions. The host passes the authored id
straight through, unchecked, with the declaration's kind/tag filter beside it; the sandbox checks liveness
and the filter on every read. So a bound entity that is not on the table when the script starts reads null
and then simply begins resolving the moment it arrives — a save finishing its load, a scripted spawn — with no
message from the host and no re-attach. One that leaves stops resolving just as quietly. An entity that arrives
under the bound id as the wrong kind still reads null, and the slot fills if a matching entity later takes
that id. Binding a piece a later save is expected to bring in is therefore fine; what is not fine is reading the
value once at load and caching it.
See also#
declareVariables— where these values come from.ScriptVariableSpec— the declaration each of these is derived from.ObjectHandle— what anobjectvariable hands you.SeatZoneInfo— what azonevariable hands you.- Async and snapshots — why a handle can go stale across an
await.
declareVariables#
Surface A — table script · const
Declare the typed slots this script needs filled in, and read back the resolved values.
Call it ONCE, at the top level, with an object literal — that literal is lifted out of the source when the script is saved, which is what lets the entity inspector render a row per variable without running anything. The values themselves come from the host, resolved from what somebody wired up in that inspector; the literal you pass is never evaluated for them.
Bindings belong to the ATTACHMENT, not to the script, so the same script on two entities reads two different sets of values.
declare const declareVariables: <T extends Record<string, ScriptVariableSpec>>(
declarations: T
) => { readonly [K in keyof T]: ScriptVariableValue<T[K]> };
Declares the typed slots this script needs filled in, and hands back an object whose properties read those slots' resolved values. The literal you pass is lifted out of the source when the script is saved, which is what lets the entity inspector render a row per variable without running anything; the values come from the host, resolved from whatever somebody wired up in that inspector.
Parameters#
| Name | Type | Required | Notes |
|---|---|---|---|
declarations |
Record<string, ScriptVariableSpec> |
yes | An object literal of object literals. Each key is a variable name (and the inspector row's fallback caption); each value is a ScriptVariableSpec naming its type and its filters. At most 32 entries. |
The argument is read by a literal parser, not evaluated — so a variable, a spread, a computed key, a template
with a substitution, a function call, or a second declareVariables() call anywhere in the file is a
save-time diagnostic rather than a run-time surprise. On a diagnostic the script keeps the declarations it
saved with last time, so a transient typo does not wipe out the bindings authored against them.
Returns#
An object with one readonly property per key you declared, typed by
ScriptVariableValue — { type: "object", kind: "deck" } reads as DeckObject | null,
{ type: "number" } as number, and so on.
Every property is a getter, and the read is synchronous — unusual on this surface, where nearly everything
that touches the table returns a Promise. Nothing is awaited because nothing is fetched: the host handed this
attachment's bindings to the sandbox before the script body ran, and the getter only decides whether what the
binding names is on the table — and still matches the declared kind/tag — at the moment you ask.
How, why and when to use it#
Reach for this the moment a script would otherwise hard-code a name. Without declared variables the only way to
find a specific piece is to search for it — world.getAllObjects({ tag: "landing-box" }), and hope nobody
renames or re-tags anything — and the only way to configure a script is to edit a constant at the head of the
file. Both work; both make the script the private property of whoever wrote it. A declared variable turns the
same script into something a non-programmer can wire up from the inspector: drag an entity onto the row, or
click it and pick from the entity tree.
The decisive property is that bindings belong to the attachment, not to the script. An object script's
bindings live on the attaching entity's metadata; a scene script's live in the scene document. Attach one
dice-roller script to three different buttons and each one throws its own dice into its own box, with no
copy-pasted script variants and no per-button if ladder. That is the thing a tag search cannot give you.
Keep using a world query when the set you want is genuinely dynamic — every card currently in play, every die
a player just spawned. Declare a variable when the answer is a decision somebody makes while authoring the
table, not something the script can work out at run time.
Example#
// content/scripting-api/examples/declarevariables.ts
// Roll a bound number of dice, from a bound die template, into a bound box.
// Nothing here names a piece: every reference is a slot somebody filled in from
// the entity inspector, so the same script on two entities can throw different
// dice into different boxes.
const vars = declareVariables({
dieTemplate: { type: "spawnable", label: "Die to spawn" },
landingBox: { type: "object", kind: "custom", label: "Landing box" },
count: { type: "number", label: "How many", default: 5, min: 1, max: 20 }
});
async function rollIntoBox(): Promise<void> {
// Both reference variables read null when nothing is bound yet, and again
// whenever the bound entity is not on the table - deleted, not loaded yet, or
// tucked inside a container. Re-read and re-check them on every run.
const template = vars.dieTemplate;
if (!template) {
world.log("No die bound yet - drop one on the 'Die to spawn' row in the inspector.");
return;
}
const box = vars.landingBox;
if (!box) {
world.log("The landing box is not on the table right now - skipping the roll.");
return;
}
const centre = box.position;
const howMany = Math.max(1, Math.round(vars.count));
for (let index = 0; index < howMany; index += 1) {
const angle = (index / howMany) * Math.PI * 2;
const die = await world.spawnObject({
...template,
position: [centre[0] + Math.cos(angle) * 0.4, centre[1] + 2, centre[2] + Math.sin(angle) * 0.4]
});
if (!die) {
world.log("spawnObject refused the bound template - check it still exists in the project.");
return;
}
die.roll();
}
world.log(`Threw ${howMany} dice into ${box.name ?? box.id}.`);
}
globalEvents.onTurnStarted.add(() => {
void rollIntoBox();
});
{ ...vars.dieTemplate, position } is the intended shape of a spawnable read: the template is exactly a
SpawnObjectOptions without a position, so you spread it and add where the
piece should land.
What the template carries depends on what the row is bound to:
| Bound to | The template carries |
|---|---|
| a standard-library preset | kind, name, presetId, and the preset's metadata and tags |
| a prefab authored in this project | kind, name, metadata and tags, plus the prefab's own scale, rotation and color |
So a copy spawned from a prefab comes out at the prefab's size, turned the way the prefab is turned and in its
color — not at the kind's default size. Anything you write after the spread wins, which is how you give one
copy a different rotation or color.
Gotchas#
The same script on two entities reads two different sets of values. Bindings are per attachment. Do not
cache a resolved handle in a script-level variable and reuse it across attachments — read vars.x where you
need it, every time.
A script that declares variables must survive having none of them bound. Nothing forces an author to fill a
row in. Until somebody does, a reference variable reads null and a scalar reads its declared default, or the
type's empty value (0, "", false, #ffffff, [0, 0, 0]; seat reads null). Write the if (!x) return;
branch first, as the example does.
The literal is never evaluated for values. Editing a default in the source and not saving changes nothing
at run time, and neither does passing a different literal than the one the script was saved with — the sandbox's
declareVariables ignores its argument entirely and returns what the host resolved. That is deliberate: it is
what stops a script smuggling a value past resolution.
Only one call, and only a literal. The extractor accepts exactly one declareVariables( in the file and
refuses anything it cannot read without running it. Build the object inline; do not assemble it from constants,
however tempting ...COMMON_VARS looks.
Thirty-two is the ceiling, and it is all-or-nothing. A thirty-third declaration is a diagnostic that rejects
the whole extraction, not just the extra row. Bindings ride the entity's metadata, which replicates in every
snapshot delta — the cap exists so one script cannot inflate the table's wire traffic.
No new reach. A variable is an index, not an access grant: an object binding resolves to a handle the same
script could have obtained from a world query, and a spawnable feeds the ordinary spawn intent, still
validated host-side. Nothing here is a way around the sandbox.
See also#
ScriptVariableSpec— the ten declaration shapes and the filters each one accepts.ScriptVariableValue— what each declared type reads back as, and when it readsnull.world.spawnObject— where aspawnabletemplate goes.SpawnObjectOptions— the shape aspawnablereads as.- Host authority — why the values are resolved on one peer.
