# Types

> The fourteen ambient declarations a table script compiles against - Vec3, ObjectKind, the action unions, SpawnObjectOptions, DiceRollSummary, declareVariables.

- Source: https://diceytable.com/docs/scripting-api/types
- Last verified: 2026-10-06

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`](https://diceytable.com/docs/scripting-api/types#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`](https://diceytable.com/docs/scripting-api/types#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`](https://diceytable.com/docs/scripting-api/types#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`](https://diceytable.com/docs/scripting-api/types#objectaction) is what a script may request and
[`ObservedObjectAction`](https://diceytable.com/docs/scripting-api/types#observedobjectaction) is what an event delivers.

## The core types

| Type | Kind | What it is for |
|---|---|---|
| [`Vec3`](https://diceytable.com/docs/scripting-api/types#vec3) | type alias | `[x, y, z]` in feet for a position, degrees for a rotation. Every coordinate in table scripting. |
| [`ObjectKind`](https://diceytable.com/docs/scripting-api/types#objectkind) | union | What an entity *is* — the required field of a spawn, and the filter `getAllObjects` narrows on. |
| [`ObjectAction`](https://diceytable.com/docs/scripting-api/types#objectaction) | union | The 13 action names a script may **request**, and the vocabulary behind the nine mutator methods. |
| [`ObservedObjectAction`](https://diceytable.com/docs/scripting-api/types#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`](https://diceytable.com/docs/scripting-api/types#objectdestroyedreason) | union | The four ways an entity can leave the table, on `EventContext.reason`. Only one of them is a deletion. |
| [`ButtonObject`](https://diceytable.com/docs/scripting-api/types#buttonobject) | interface | The handle a `button` narrows to — `eventName` and the `onPressed` delegate. |
| [`TableFurnitureObject`](https://diceytable.com/docs/scripting-api/types#tablefurnitureobject) | interface | The handle a `table` narrows to. Adds nothing to `ObjectHandle`; declared so a table's own script has a type. |
| [`CoinObject`](https://diceytable.com/docs/scripting-api/types#coinobject) | interface | The handle a `coin` narrows to — the `onTossed` delegate, raised at the throw. |
| [`SpawnObjectOptions`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptions) | interface | The whole description of a new entity: one required field and the optional rest. |
| [`PlayerInfo`](https://diceytable.com/docs/scripting-api/types#playerinfo) | interface | One connected peer — id, name, seat, team, host flag. |
| [`TurnInfo`](https://diceytable.com/docs/scripting-api/types#turninfo) | interface | Whether turn order is on, and whose turn it is. |
| [`DiceRollSummary`](https://diceytable.com/docs/scripting-api/types#dicerollsummary) | interface | One finished batch dice roll — the roller, the notation, every face, the total, and how many were unreadable. |
| [`declareVariables`](https://diceytable.com/docs/scripting-api/types#declarevariables) | const | The one call that declares the typed slots a script needs filled in from the entity inspector. |
| [`ScriptVariableSpec`](https://diceytable.com/docs/scripting-api/types#scriptvariablespec) | union | One declared slot — its `type`, and the `kind`/`tag` filters the inspector enforces. |
| [`ScriptVariableValue`](https://diceytable.com/docs/scripting-api/types#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`](https://diceytable.com/docs/scripting-api/types#textlabeloptions) — everything [`world.setTextLabel`](https://diceytable.com/docs/scripting-api/world#worldsettextlabel)
takes to draw text flat on the table.

## Members, one row each

| Member | Type | What it is for |
|---|---|---|
| [`SpawnObjectOptions.kind`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionskind) | `ObjectKind` | Required. A non-empty string, or the spawn resolves `null`. |
| [`SpawnObjectOptions.name`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionsname) | `string` | Sets the entity's **`label`** — its slug — not its human name. |
| [`SpawnObjectOptions.position`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionsposition) | `Vec3` | Where it appears. Defaults to `[0, 1, 0]`, one foot up. |
| [`SpawnObjectOptions.rotation`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionsrotation) | `Vec3` | Starting Euler angles. Dropped rather than defaulted when malformed. |
| [`SpawnObjectOptions.presetId`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionspresetid) | `string` | A standard-library preset, for the model and a die's collision hull. |
| [`SpawnObjectOptions.metadata`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionsmetadata) | `Record<string, unknown>` | Freeform data, copied shallowly, write-once from a script. |
| [`SpawnObjectOptions.tags`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionstags) | `string[]` | The only spawn field `world.getAllObjects` can filter on. |
| [`PlayerInfo.peerId`](https://diceytable.com/docs/scripting-api/types#playerinfopeerid) | `string` | The identity. Key everything on this. |
| [`PlayerInfo.displayName`](https://diceytable.com/docs/scripting-api/types#playerinfodisplayname) | `string \| null` | The name to print. Optional, not unique. |
| [`PlayerInfo.seat`](https://diceytable.com/docs/scripting-api/types#playerinfoseat) | `string \| null` | Their seat, or `null` for a spectator. |
| [`PlayerInfo.team`](https://diceytable.com/docs/scripting-api/types#playerinfoteam) | `string \| null` | Their team, or `null` — the default at most tables. |
| [`PlayerInfo.isHost`](https://diceytable.com/docs/scripting-api/types#playerinfoishost) | `boolean` | `true` on exactly one row — the machine the scripts run on. |
| [`TurnInfo.enabled`](https://diceytable.com/docs/scripting-api/types#turninfoenabled) | `boolean` | Whether turn order is running at all. |
| [`TurnInfo.activePeerId`](https://diceytable.com/docs/scripting-api/types#turninfoactivepeerid) | `string \| null` | Whose turn it is. `null` has two causes. |
| [`DiceRollSummary.rollId`](https://diceytable.com/docs/scripting-api/types#dicerollsummaryrollid) | `string` | Identifies the throw. The dice from it carry the same id. |
| [`DiceRollSummary.actorPeerId`](https://diceytable.com/docs/scripting-api/types#dicerollsummaryactorpeerid) | `string` | Who rolled. Always present — key on this. |
| [`DiceRollSummary.actorName`](https://diceytable.com/docs/scripting-api/types#dicerollsummaryactorname) | `string` | Their display name, frozen at emit. Not unique. |
| [`DiceRollSummary.seat`](https://diceytable.com/docs/scripting-api/types#dicerollsummaryseat) | `string \| null` | Their seat, or `null` — a seatless player can still roll. |
| [`DiceRollSummary.target`](https://diceytable.com/docs/scripting-api/types#dicerollsummarytarget) | `"tray" \| "table"` | Their own bounded region, or the shared table. |
| [`DiceRollSummary.notation`](https://diceytable.com/docs/scripting-api/types#dicerollsummarynotation) | `string` | `3d6+1d20`, grouped by face count, not by preset. |
| [`DiceRollSummary.dice`](https://diceytable.com/docs/scripting-api/types#dicerollsummarydice) | `ReadonlyArray<…>` | Per die: `objectId`, `preset`, `sides`, and the face or `null`. |
| [`DiceRollSummary.total`](https://diceytable.com/docs/scripting-api/types#dicerollsummarytotal) | `number` | Sum of the readable faces only. |
| [`DiceRollSummary.cocked`](https://diceytable.com/docs/scripting-api/types#dicerollsummarycocked) | `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`](https://diceytable.com/docs/scripting-api/objecthandle). `EventContext` and `ScriptDelegate` live on
[Events](https://diceytable.com/docs/scripting-api/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`](https://diceytable.com/docs/scripting-api/api) and
are not interchangeable with anything on this page.

## See also

- [`World`](https://diceytable.com/docs/scripting-api/world) — the calls that take and return these types.
- [`ObjectHandle`](https://diceytable.com/docs/scripting-api/objecthandle) — `ObjectData`'s ten fields, documented there.
- [Events](https://diceytable.com/docs/scripting-api/events) — `EventContext`, `ScriptDelegate`, and every delegate's payload.
- [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) — the authoritative comparison behind the two action types.
- [Object kinds](https://diceytable.com/docs/mods/reference/object-kinds) — what each of the eleven kinds does.
- [Choosing a surface](https://diceytable.com/docs/scripting/concepts/choosing-a-surface) — why the mod types differ.
- [Known limitations](https://diceytable.com/docs/reference/known-limitations) — every documented gap, in one list.

## Vec3

_Surface A — table script · type_

A [x, y, z] position/rotation triple in table space.

```ts
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

```ts
// 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`](https://diceytable.com/docs/scripting-api/api#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()`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlerotate) is the relative quarter-turn.

### See also

- [`ObjectData.position`](https://diceytable.com/docs/scripting-api/objecthandle#objectdataposition) — the read side.
- [`ObjectHandle.setPosition`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesetposition) — the write side, and its coercion rules.
- [`SpawnObjectOptions.position`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionsposition) — the default when you omit it.
- [`Vector3`](https://diceytable.com/docs/scripting-api/api#vector3) — the mod-side shape, for comparison.
- [Choosing a surface](https://diceytable.com/docs/scripting/concepts/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.

```ts
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

```ts
// 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`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatakind) — reading it back off a handle.
- [`SpawnObjectOptions.kind`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionskind) — the required field, and its coercion.
- [`world.getAllObjects`](https://diceytable.com/docs/scripting-api/world#worldgetallobjects) — filtering by kind or by tag.
- [Object kinds](https://diceytable.com/docs/mods/reference/object-kinds) — what each of the eleven kinds is and how it behaves.
- [Action vocabularies](https://diceytable.com/docs/reference/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).

```ts
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`](https://diceytable.com/docs/scripting-api/types#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](https://diceytable.com/docs/reference/action-vocabularies), which owns that table; this
entry is only about the declared union.

### Example

```ts
// 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](https://diceytable.com/docs/reference/known-limitations#actions-with-no-objecthandle-method).

**It is not the type an event hands you.** `onObjectAction` and `ObjectHandle.onAction` are declared with
[`ObservedObjectAction`](https://diceytable.com/docs/scripting-api/types#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](https://diceytable.com/docs/reference/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](https://diceytable.com/docs/reference/action-vocabularies) — the three vocabularies compared, and which asymmetries are deliberate.
- [`ObjectHandle`](https://diceytable.com/docs/scripting-api/objecthandle) — the nine methods that post an action.
- [`ObservedObjectAction`](https://diceytable.com/docs/scripting-api/types#observedobjectaction) — the wider union an event delivers.
- [`globalEvents.onObjectAction`](https://diceytable.com/docs/scripting-api/events#globaleventsonobjectaction) — the delegate that delivers the wider one.
- [`ObjectHandle.destroy`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandledestroy) — the method whose name differs from its action.
- [Known limitations](https://diceytable.com/docs/reference/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.

```ts
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`](https://diceytable.com/docs/scripting-api/types#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`](https://diceytable.com/docs/scripting-api/events#globaleventsonobjectaction)
and [`ObjectHandle.onAction`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleonaction).

### 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](https://diceytable.com/docs/reference/action-vocabularies); this entry is only about the declared union.

### Example

```ts
// 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`](https://diceytable.com/docs/scripting-api/types#coinobjectontossed); 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`](https://diceytable.com/docs/scripting-api/object-types#deckobjectonsearched) 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`](https://diceytable.com/docs/scripting-api/types#objectaction) — the 13 a script may request, and the four with no method.
- [`DeckObject.onSearched`](https://diceytable.com/docs/scripting-api/object-types#deckobjectonsearched) — the three `search*` observe-only names, and why they are observe-only.
- [`globalEvents.onObjectAction`](https://diceytable.com/docs/scripting-api/events#globaleventsonobjectaction) — the table-wide delegate declared with this type.
- [`ObjectHandle.onAction`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleonaction) — the entity-scoped one.
- [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) — engine, table script and mod compared.
- [Events and delegates](https://diceytable.com/docs/scripting/concepts/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"` — the `delete` action was applied (a menu, a peer, or a
  script's `destroy()`).
- `"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 own `onObjectCreated`.
- `"absorbed"` — a `combine` folded the entity into a stack.
  `context.containerId` names the surviving stack that took its cards.

Write a `default` branch: this union grows when the engine grows a removal path.

```ts
declare type ObjectDestroyedReason = "deleted" | "depleted" | "converted" | "absorbed";
```

The four ways an entity can leave the table, on `context.reason` of an
[`onObjectDestroyed`](https://diceytable.com/docs/scripting-api/events#globaleventsonobjectdestroyed) or
[`onDestroyed`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleondestroyed) 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`](https://diceytable.com/docs/scripting-api/events#eventcontextreason) 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`](https://diceytable.com/docs/scripting-api/events#eventcontextactor).

### Example

```ts
// 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`](https://diceytable.com/docs/scripting-api/events#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`](https://diceytable.com/docs/scripting-api/events#eventcontextreason) — the field this type lives on.
- [`EventContext.containerId`](https://diceytable.com/docs/scripting-api/events#eventcontextcontainerid) — the surviving stack, on `"absorbed"`.
- [`globalEvents.onObjectDestroyed`](https://diceytable.com/docs/scripting-api/events#globaleventsonobjectdestroyed) — the table-wide delegate.
- [`ObjectHandle.onDestroyed`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleondestroyed) — the entity-scoped twin.
- [Events and delegates](https://diceytable.com/docs/scripting/concepts/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`](https://diceytable.com/docs/scripting-api/events#globaleventsonobjectclicked) and
[`ObjectHandle.onClicked`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleonclicked) pass last: an
[`EventContext`](https://diceytable.com/docs/scripting-api/events#eventcontext) with two more fields, the clicker's
[`seat`](https://diceytable.com/docs/scripting-api/types#objectclickcontextseat) and the
[`input`](https://diceytable.com/docs/scripting-api/types#objectclickcontextinput) 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`](https://diceytable.com/docs/scripting-api/events#eventcontextactor).

**A fresh object per event.** Copy the strings out if you need them later, as with every `EventContext`.

### See also

- [`globalEvents.onObjectClicked`](https://diceytable.com/docs/scripting-api/events#globaleventsonobjectclicked) — the event that passes it.
- [`ObjectHandle.onClicked`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleonclicked) — the same click, on one entity.
- [`EventContext`](https://diceytable.com/docs/scripting-api/events#eventcontext) — the fields it inherits.
- [Highlights and clicks](https://diceytable.com/docs/scripting/concepts/highlights-and-clicks) — the guide.

### Members

| Signature | Description | Returns |
|---|---|---|
| [`seat`](https://diceytable.com/docs/scripting-api/types#objectclickcontextseat) | The clicker's seat (`"red"`, …), or `null` for a spectator or a host without a seat. | `string \| null` |
| [`input`](https://diceytable.com/docs/scripting-api/types#objectclickcontextinput) | How the click was made. Informational: treat all three alike. | `"mouse" \| "touch" \| "vr"` |

### objectclickcontext.seat

```ts
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`](https://diceytable.com/docs/scripting-api/world#worldgetturn), and pass it straight to
[`ui.prompt`](https://diceytable.com/docs/scripting-api/game-ui#uiprompt), 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`](https://diceytable.com/docs/scripting-api/types#objectclickcontext) — the object it lives on.
- [`ui.prompt`](https://diceytable.com/docs/scripting-api/game-ui#uiprompt) — ask that seat what the click should do.

### objectclickcontext.input

```ts
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`](https://diceytable.com/docs/ai-agents/reference/tools/table-actions#tableclick) tool
clicks the way the user's mouse would.

#### See also

- [`ObjectClickContext`](https://diceytable.com/docs/scripting-api/types#objectclickcontext) — the object it lives on.
- [Highlights and clicks](https://diceytable.com/docs/scripting/concepts/highlights-and-clicks#what-counts-as-a-click) — 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 `-`.

```ts
declare type HighlightStyle = "target" | "active" | "playable" | (string & {});
```

The name of an outline style, as [`world.setHighlight`](https://diceytable.com/docs/scripting-api/world#worldsethighlight) and
[`ClearHighlightsOptions.style`](https://diceytable.com/docs/scripting-api/types#clearhighlightsoptionsstyle) 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](https://diceytable.com/docs/editor/inspector/platform-panels#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`](https://diceytable.com/docs/scripting-api/world#worldsethighlight) — the call that uses it.
- [Highlight Styles](https://diceytable.com/docs/editor/inspector/platform-panels#highlight-styles) — defining your game's own styles.
- [Highlights and clicks](https://diceytable.com/docs/scripting/concepts/highlights-and-clicks) — the guide.

## HighlightTarget

_Surface A — table script · type_

What `world.setHighlight` outlines: entity ids or handles.

```ts
declare type HighlightTarget = string | { readonly id: string };
```

What [`world.setHighlight`](https://diceytable.com/docs/scripting-api/world#worldsethighlight) outlines: an entity id, or anything with
an `id`, such as an [`ObjectHandle`](https://diceytable.com/docs/scripting-api/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`](https://diceytable.com/docs/scripting-api/world#worldsethighlight) — the call that takes it.
- [`ObjectHandle`](https://diceytable.com/docs/scripting-api/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`](https://diceytable.com/docs/scripting-api/world#worldsethighlight): who sees the
outline ([`seats`](https://diceytable.com/docs/scripting-api/types#highlightoptionsseats)) and how long it lasts
([`seconds`](https://diceytable.com/docs/scripting-api/types#highlightoptionsseconds)). 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`](https://diceytable.com/docs/scripting-api/types#highlightoptionsseats) — private outlines.
- [`HighlightOptions.seconds`](https://diceytable.com/docs/scripting-api/types#highlightoptionsseconds) — timed outlines.
- [`world.setHighlight`](https://diceytable.com/docs/scripting-api/world#worldsethighlight) — the call that takes it.

### Members

| Signature | Description | Returns |
|---|---|---|
| [`seats`](https://diceytable.com/docs/scripting-api/types#highlightoptionsseats) | 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`](https://diceytable.com/docs/scripting-api/types#highlightoptionsseconds) | Remove the outline by itself after this many seconds (0.5 to 600). Default: until cleared. | `number` |

### highlightoptions.seats

```ts
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`](https://diceytable.com/docs/scripting-api/types#clearhighlightsoptionsseats) — clearing one seat's outlines.
- [Game UI audiences and privacy](https://diceytable.com/docs/scripting/concepts/game-ui#audiences-and-privacy) — the same privacy rule for HUD state.
- [Highlights and clicks](https://diceytable.com/docs/scripting/concepts/highlights-and-clicks#public-and-private-outlines) — the guide.

### highlightoptions.seconds

```ts
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`](https://diceytable.com/docs/scripting-api/world#worldwait) 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`](https://diceytable.com/docs/scripting-api/types#highlightoptions) — the other option.
- [`world.setHighlight`](https://diceytable.com/docs/scripting-api/world#worldsethighlight) — the call that takes it.

## ClearHighlightsOptions

_Surface A — table script · interface · 2 members_

Options for `world.clearHighlights`.

The optional argument of [`world.clearHighlights`](https://diceytable.com/docs/scripting-api/world#worldclearhighlights): narrow the
clear to one [`style`](https://diceytable.com/docs/scripting-api/types#clearhighlightsoptionsstyle), to some
[`seats`](https://diceytable.com/docs/scripting-api/types#clearhighlightsoptionsseats)' 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`](https://diceytable.com/docs/scripting-api/world#worldclearhighlights) — the call that takes it.
- [`world.setHighlight`](https://diceytable.com/docs/scripting-api/world#worldsethighlight) — passing `null` clears chosen entities instead.

### Members

| Signature | Description | Returns |
|---|---|---|
| [`style`](https://diceytable.com/docs/scripting-api/types#clearhighlightsoptionsstyle) | Only outlines of this style. | `HighlightStyle` |
| [`seats`](https://diceytable.com/docs/scripting-api/types#clearhighlightsoptionsseats) | Only these seats' private outlines. Without it, the public outlines AND every seat's go. | `string \| readonly string[]` |

### clearhighlightsoptions.style

```ts
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`](https://diceytable.com/docs/scripting-api/types#clearhighlightsoptionsseats) narrows it.

#### Returns

[`HighlightStyle`](https://diceytable.com/docs/scripting-api/types#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`](https://diceytable.com/docs/scripting-api/types#highlightstyle) — the built-in names.
- [`world.clearHighlights`](https://diceytable.com/docs/scripting-api/world#worldclearhighlights) — the call.

### clearhighlightsoptions.seats

```ts
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`](https://diceytable.com/docs/scripting-api/types#highlightoptionsseats) — setting private outlines.
- [`world.clearHighlights`](https://diceytable.com/docs/scripting-api/world#worldclearhighlights) — 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`](https://diceytable.com/docs/scripting-api/world#worldaddobjectmenuitem).

Two required fields — an `id` you choose and a `label` players read — plus an optional
[`match`](https://diceytable.com/docs/scripting-api/types#objectmenuitemregistrationmatch) 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`](https://diceytable.com/docs/scripting-api/events#globaleventsonobjectmenuitem).

### 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`](https://diceytable.com/docs/scripting-api/world#worldaddobjectmenuitem) — the call that takes it.
- [`globalEvents.onObjectMenuItem`](https://diceytable.com/docs/scripting-api/events#globaleventsonobjectmenuitem) — the click it produces.

### Members

| Signature | Description | Returns |
|---|---|---|
| [`id`](https://diceytable.com/docs/scripting-api/types#objectmenuitemregistrationid) | 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`](https://diceytable.com/docs/scripting-api/types#objectmenuitemregistrationlabel) | The caption on the button. | `string` |
| [`match`](https://diceytable.com/docs/scripting-api/types#objectmenuitemregistrationmatch) | 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`](https://diceytable.com/docs/scripting-api/types#objectmenuitemregistrationdanger) | Draw it as a destructive action, like Delete. | `boolean` |
| [`order`](https://diceytable.com/docs/scripting-api/types#objectmenuitemregistrationorder) | Sort order among script items. Script items always follow the built-in actions. | `number` |
| [`seats`](https://diceytable.com/docs/scripting-api/types#objectmenuitemregistrationseats) | Offer the item ONLY to players seated in one of these seats. Omit it to offer the item to everyone. | `string[]` |

### objectmenuitemregistration.id

```ts
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`](https://diceytable.com/docs/scripting-api/events#globaleventsonobjectmenuitem), and it is the key
[`removeObjectMenuItem`](https://diceytable.com/docs/scripting-api/world#worldremoveobjectmenuitem) 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`](https://diceytable.com/docs/scripting-api/world#worldaddobjectmenuitem) — where you set it.
- [`world.removeObjectMenuItem`](https://diceytable.com/docs/scripting-api/world#worldremoveobjectmenuitem) — which takes it back.

### objectmenuitemregistration.label

```ts
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`](https://diceytable.com/docs/scripting-api/types#objectmenuitemregistrationid) in the handler, never on the label.

#### See also

- [`objectMenuItemRegistration.danger`](https://diceytable.com/docs/scripting-api/types#objectmenuitemregistrationdanger) — how it is styled.
- [`world.addObjectMenuItem`](https://diceytable.com/docs/scripting-api/world#worldaddobjectmenuitem) — where you set it.

### objectmenuitemregistration.match

```ts
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](https://diceytable.com/docs/scripting-api/events#globaleventsonobjectmenuitem).

**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`](https://diceytable.com/docs/scripting-api/world#worldaddobjectmenuitem) — where you set it.
- [`globalEvents.onObjectMenuItem`](https://diceytable.com/docs/scripting-api/events#globaleventsonobjectmenuitem) — where runtime conditions go instead.

### objectmenuitemregistration.danger

```ts
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`](https://diceytable.com/docs/scripting-api/types#objectmenuitemregistrationlabel) — the text it styles.
- [`world.addObjectMenuItem`](https://diceytable.com/docs/scripting-api/world#worldaddobjectmenuitem) — where you set it.

### objectmenuitemregistration.order

```ts
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`](https://diceytable.com/docs/scripting-api/world#worldaddobjectmenuitem) — where you set it.

### objectmenuitemregistration.seats

```ts
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

```ts
// 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`](https://diceytable.com/docs/scripting-api/world#worldaddobjectmenuitem): 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`](https://diceytable.com/docs/scripting-api/world#worldsettextlabel) takes it: text drawn flat
on the table for every player to read.

Three required fields — an [`id`](https://diceytable.com/docs/scripting-api/types#textlabeloptionsid) you choose, the
[`text`](https://diceytable.com/docs/scripting-api/types#textlabeloptionstext) and a
[`position`](https://diceytable.com/docs/scripting-api/types#textlabeloptionsposition) in feet — plus five that decide how it looks:
[`rotationY`](https://diceytable.com/docs/scripting-api/types#textlabeloptionsrotationy),
[`size`](https://diceytable.com/docs/scripting-api/types#textlabeloptionssize),
[`color`](https://diceytable.com/docs/scripting-api/types#textlabeloptionscolor),
[`background`](https://diceytable.com/docs/scripting-api/types#textlabeloptionsbackground) and
[`bold`](https://diceytable.com/docs/scripting-api/types#textlabeloptionsbold).

### 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](https://diceytable.com/docs/editor/workflows/preview-and-photo-mode), **Text labels**, which a player can switch
off for a shot.

### See also

- [`world.setTextLabel`](https://diceytable.com/docs/scripting-api/world#worldsettextlabel) — the call that takes it, with an example.
- [`world.removeTextLabel`](https://diceytable.com/docs/scripting-api/world#worldremovetextlabel) — taking a label away again.

### Members

| Signature | Description | Returns |
|---|---|---|
| [`id`](https://diceytable.com/docs/scripting-api/types#textlabeloptionsid) | 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`](https://diceytable.com/docs/scripting-api/types#textlabeloptionstext) | What to show, up to 256 characters. A line break starts a new line (8 lines at most). | `string` |
| [`position`](https://diceytable.com/docs/scripting-api/types#textlabeloptionsposition) | Where the middle of the text sits, in table space. Use the table surface height for y. | `Vec3` |
| [`rotationY`](https://diceytable.com/docs/scripting-api/types#textlabeloptionsrotationy) | 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`](https://diceytable.com/docs/scripting-api/types#textlabeloptionssize) | Height of one line of text, in feet. Defaults to `0.12`. | `number` |
| [`color`](https://diceytable.com/docs/scripting-api/types#textlabeloptionscolor) | Text colour, `#rrggbb`. Defaults to white. | `string` |
| [`background`](https://diceytable.com/docs/scripting-api/types#textlabeloptionsbackground) | Draw a rounded plate of this colour behind the text. Omit or pass `null` for bare text. | `string \| null` |
| [`bold`](https://diceytable.com/docs/scripting-api/types#textlabeloptionsbold) | Draw the text bold. Defaults to `true`. | `boolean` |

### textlabeloptions.id

```ts
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`](https://diceytable.com/docs/scripting-api/world#worldremovetextlabel) 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`](https://diceytable.com/docs/scripting-api/world#worldgetobjectbyid).

**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`](https://diceytable.com/docs/scripting-api/world#worldsettextlabel) — where you set it.
- [`world.removeTextLabel`](https://diceytable.com/docs/scripting-api/world#worldremovetextlabel) — which takes it back.

### textlabeloptions.text

```ts
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`](https://diceytable.com/docs/scripting-api/types#textlabeloptionsposition), and each one is
[`size`](https://diceytable.com/docs/scripting-api/types#textlabeloptionssize) 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`](https://diceytable.com/docs/scripting-api/world#worldremovetextlabel).

**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`](https://diceytable.com/docs/scripting-api/types#textlabeloptionssize) — how tall each line is.
- [`world.setTextLabel`](https://diceytable.com/docs/scripting-api/world#worldsettextlabel) — where you set it.

### textlabeloptions.position

```ts
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`](https://diceytable.com/docs/scripting-api/types#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](https://diceytable.com/docs/scripting-api/world#worldgetsnappoints), a
[seat zone](https://diceytable.com/docs/scripting-api/world#worldgetseatzones) 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`](https://diceytable.com/docs/scripting-api/types#vec3) — the tuple, and its units.
- [`TextLabelOptions.rotationY`](https://diceytable.com/docs/scripting-api/types#textlabeloptionsrotationy) — which way the text faces.
- [`world.getSnapPoints`](https://diceytable.com/docs/scripting-api/world#worldgetsnappoints) — authored positions to place a label by.

### textlabeloptions.rotationY

```ts
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`](https://diceytable.com/docs/scripting-api/types#textlabeloptionsposition) — where it sits.
- [`world.getSeatZones`](https://diceytable.com/docs/scripting-api/world#worldgetseatzones) — where each seat is, to face a label toward it.

### textlabeloptions.size

```ts
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`](https://diceytable.com/docs/scripting-api/types#textlabeloptionstext) — lines, and what happens to a very long one.
- [`Vec3`](https://diceytable.com/docs/scripting-api/types#vec3) — the same unit, for positions.

### textlabeloptions.color

```ts
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`](https://diceytable.com/docs/scripting-api/types#textlabeloptionsbackground)
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`](https://diceytable.com/docs/scripting-api/types#textlabeloptionsbackground) — a plate to read it against.
- [`world.setTextLabel`](https://diceytable.com/docs/scripting-api/world#worldsettextlabel) — where you set it.

### textlabeloptions.background

```ts
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`](https://diceytable.com/docs/scripting-api/types#textlabeloptionscolor): 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`](https://diceytable.com/docs/scripting-api/types#textlabeloptionscolor) — the text drawn on it.
- [`world.setTextLabel`](https://diceytable.com/docs/scripting-api/world#worldsettextlabel) — where you set it.

### textlabeloptions.bold

```ts
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`](https://diceytable.com/docs/scripting-api/types#textlabeloptionssize) — the other way to make text stand out.
- [`world.setTextLabel`](https://diceytable.com/docs/scripting-api/world#worldsettextlabel) — 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.

```ts
declare type TooltipVariableValue = string | number | boolean;
```

What a tooltip variable can hold: a `string`, a `number` or a `boolean`. It is what
[`setTooltipVariable`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesettooltipvariable) accepts and what
[`TooltipData.variables`](https://diceytable.com/docs/scripting-api/types#tooltipdatavariables) 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`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesettooltipvariable) — setting one.
- [`TooltipOptions.variables`](https://diceytable.com/docs/scripting-api/types#tooltipoptionsvariables) — 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`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatatooltip) 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`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatatooltip) — where you read it.
- [`TooltipOptions`](https://diceytable.com/docs/scripting-api/types#tooltipoptions) — the shape you change it with.

### Members

| Signature | Description | Returns |
|---|---|---|
| [`enabled`](https://diceytable.com/docs/scripting-api/types#tooltipdataenabled) | Whether the tooltip shows at all. | `boolean` |
| [`title`](https://diceytable.com/docs/scripting-api/types#tooltipdatatitle) | The title template, or null for the entity's name. | `string \| null` |
| [`description`](https://diceytable.com/docs/scripting-api/types#tooltipdatadescription) | The description template (formatting and `{variables}`), or null for none. | `string \| null` |
| [`showDetails`](https://diceytable.com/docs/scripting-api/types#tooltipdatashowdetails) | Whether the built-in detail lines (die value, card count, counters, owner) show. | `boolean` |
| [`variables`](https://diceytable.com/docs/scripting-api/types#tooltipdatavariables) | The entity's own tooltip variables. | `Readonly<Record<string, TooltipVariableValue>>` |

### tooltipdata.enabled

```ts
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`](https://diceytable.com/docs/scripting-api/types#tooltipoptionsenabled) — changing it.
- [`ObjectData.tooltip`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatatooltip) — the record this is on.

### tooltipdata.title

```ts
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](https://diceytable.com/docs/scripting-api/types#tooltipdatadescription).

#### See also

- [`TooltipOptions.title`](https://diceytable.com/docs/scripting-api/types#tooltipoptionstitle) — changing it.
- [TOOLTIP template syntax](https://diceytable.com/docs/editor/inspector/platform-panels#tooltip-template-syntax) — what a template may contain.

### tooltipdata.description

```ts
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`](https://diceytable.com/docs/scripting-api/types#tooltipoptionsdescription) — changing it.
- [TOOLTIP template syntax](https://diceytable.com/docs/editor/inspector/platform-panels#tooltip-template-syntax) — bold, italic, colour, bullets and variables.

### tooltipdata.showDetails

```ts
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`](https://diceytable.com/docs/scripting-api/types#tooltipoptionsshowdetails) — changing it.

### tooltipdata.variables

```ts
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`](https://diceytable.com/docs/scripting-api/types#tooltipoptionsvariables) — changing several at once.
- [`ObjectHandle.setTooltipVariable`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesettooltipvariable) — 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()`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesettooltip) 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`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesettooltip) — the call that takes it, with an example.
- [`TooltipData`](https://diceytable.com/docs/scripting-api/types#tooltipdata) — the shape you read back.

### Members

| Signature | Description | Returns |
|---|---|---|
| [`enabled`](https://diceytable.com/docs/scripting-api/types#tooltipoptionsenabled) |  | `boolean` |
| [`title`](https://diceytable.com/docs/scripting-api/types#tooltipoptionstitle) | A title template — variables only, no formatting. null = use the entity's name. | `string \| null` |
| [`description`](https://diceytable.com/docs/scripting-api/types#tooltipoptionsdescription) | 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`](https://diceytable.com/docs/scripting-api/types#tooltipoptionsshowdetails) | Show the built-in detail lines. null resets to the default (shown). | `boolean \| null` |
| [`variables`](https://diceytable.com/docs/scripting-api/types#tooltipoptionsvariables) | Variables to set (merged into the existing ones); a null value deletes that variable. | `Record<string, TooltipVariableValue \| null>` |

### tooltipoptions.enabled

```ts
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`](https://diceytable.com/docs/scripting-api/types#tooltipdataenabled) — reading it.
- [`ObjectHandle.setTooltip`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesettooltip) — the call this belongs to.

### tooltipoptions.title

```ts
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](https://diceytable.com/docs/scripting-api/types#tooltipoptionsdescription).

**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`](https://diceytable.com/docs/scripting-api/types#tooltipdatatitle) — reading it.
- [TOOLTIP template syntax](https://diceytable.com/docs/editor/inspector/platform-panels#tooltip-template-syntax) — variables and fallbacks.

### tooltipoptions.description

```ts
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`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesettooltipvariable) 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`](https://diceytable.com/docs/scripting-api/types#tooltipdatadescription) — reading it.
- [TOOLTIP template syntax](https://diceytable.com/docs/editor/inspector/platform-panels#tooltip-template-syntax) — the full syntax, with escapes and colour names.

### tooltipoptions.showDetails

```ts
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`](https://diceytable.com/docs/scripting-api/types#tooltipdatashowdetails) — reading it, and the full list of lines.

### tooltipoptions.variables

```ts
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`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesettooltipvariable) 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`](https://diceytable.com/docs/scripting-api/types#tooltipdatavariables) — reading them back.
- [`TooltipVariableValue`](https://diceytable.com/docs/scripting-api/types#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`](https://diceytable.com/docs/scripting-api/types#objectactionoptionssilent).

### 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

- [`shuffle()`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleshuffle)

### Members

| Signature | Description | Returns |
|---|---|---|
| [`silent`](https://diceytable.com/docs/scripting-api/types#objectactionoptionssilent) | Perform the action without its animation or sound. | `boolean` |

### objectactionoptions.silent

```ts
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

```ts
// 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

- [`ObjectActionOptions`](https://diceytable.com/docs/scripting-api/types#objectactionoptions)

## 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`](https://diceytable.com/docs/scripting-api/object-types#bagobjectitems) 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`](https://diceytable.com/docs/scripting-api/world#worldgetobjectbyid) will accept. A piece only becomes an entity
again when [`takeObject`](https://diceytable.com/docs/scripting-api/object-types#bagobjecttakeobject) 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`](https://diceytable.com/docs/scripting-api/types#containeritemkey) addresses a run, [`name`](https://diceytable.com/docs/scripting-api/types#containeritemname) labels it,
[`kind`](https://diceytable.com/docs/scripting-api/types#containeritemkind) says what a drawn copy will be, and [`count`](https://diceytable.com/docs/scripting-api/types#containeritemcount) 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`](https://diceytable.com/docs/scripting-api/object-types#bagobjectitems) 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`](https://diceytable.com/docs/scripting-api/world#worldgetallobjects) 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`](https://diceytable.com/docs/scripting-api/object-types#containerobjectcards) as
[`ContainerCard`](https://diceytable.com/docs/scripting-api/object-types#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`](https://diceytable.com/docs/scripting-api/object-types#bagobjectitems) — the array these live in.
- [`BagObject.takeObject`](https://diceytable.com/docs/scripting-api/object-types#bagobjecttakeobject) — turning a run into an entity.
- [`ContainerCard`](https://diceytable.com/docs/scripting-api/object-types#containercard) — the card-lane equivalent.
- [Object kinds](https://diceytable.com/docs/mods/reference/object-kinds) — what a `bag` can hold.

### Members

| Signature | Description | Returns |
|---|---|---|
| [`key`](https://diceytable.com/docs/scripting-api/types#containeritemkey) | The identity key for this sort of piece — the handle `takeObject({ key })` takes to draw one deliberately rather than at random. | `string` |
| [`name`](https://diceytable.com/docs/scripting-api/types#containeritemname) | The piece's display name, falling back to its slug. What to put in a menu or a log line. | `string` |
| [`kind`](https://diceytable.com/docs/scripting-api/types#containeritemkind) |  | `ObjectKind` |
| [`count`](https://diceytable.com/docs/scripting-api/types#containeritemcount) | How many copies of this piece the container holds. Always 1 or more. | `number` |

### containeritem.key

```ts
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 })`](https://diceytable.com/docs/scripting-api/object-types#bagobjecttakeobject) 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`](https://diceytable.com/docs/scripting-api/object-types#bagobjectitems), 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`](https://diceytable.com/docs/scripting-api/types#containeritem) — the run this addresses.
- [`BagObject.takeObject`](https://diceytable.com/docs/scripting-api/object-types#bagobjecttakeobject) — the one call that takes a key.
- [`ContainerItem.name`](https://diceytable.com/docs/scripting-api/types#containeritemname) — what to show a player instead of the key.

### containeritem.name

```ts
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`](https://diceytable.com/docs/scripting-api/types#containeritemkey) is the identity half. Build a "what would you
like to draw?" list out of `name` and [`count`](https://diceytable.com/docs/scripting-api/types#containeritemcount), and carry `key` alongside it as the value
you pass back to [`takeObject`](https://diceytable.com/docs/scripting-api/object-types#bagobjecttakeobject). 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`](https://diceytable.com/docs/scripting-api/objecthandle#objectdataname) 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`](https://diceytable.com/docs/scripting-api/types#containeritemkey) — the identity to match on.
- [`ContainerItem.count`](https://diceytable.com/docs/scripting-api/types#containeritemcount) — the other half of a menu line.
- [Identity, names and tags](https://diceytable.com/docs/editor/concepts/ids-names-tags) — the three names and what each is for.

### containeritem.kind

```ts
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`](https://diceytable.com/docs/scripting-api/types#objectkind) of the entity
[`takeObject`](https://diceytable.com/docs/scripting-api/object-types#bagobjecttakeobject) 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`](https://diceytable.com/docs/scripting-api/object-types#containerobjectcards) 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`](https://diceytable.com/docs/scripting-api/types#objectkind) — the union, and why it is open.
- [`ContainerItem`](https://diceytable.com/docs/scripting-api/types#containeritem) — the run this describes.
- [`BagObject.takeObject`](https://diceytable.com/docs/scripting-api/object-types#bagobjecttakeobject) — where the kind becomes an entity.

### containeritem.count

```ts
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`](https://diceytable.com/docs/scripting-api/object-types#bagobjectitems) 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`](https://diceytable.com/docs/scripting-api/types#containeritemname) — "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`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatastackcount) 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`](https://diceytable.com/docs/scripting-api/types#containeritemname) — the label that goes beside it.
- [`BagObject.items`](https://diceytable.com/docs/scripting-api/object-types#bagobjectitems) — the array to sum.
- [`ObjectData.stackCount`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatastackcount) — 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`](https://diceytable.com/docs/scripting-api/objecthandle) is [`onTossed`](https://diceytable.com/docs/scripting-api/types#coinobjectontossed), so a
coin's own script can say "when this coin is tossed" without filtering
[`onAction`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleonaction) 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`](https://diceytable.com/docs/scripting-api/types#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`](https://diceytable.com/docs/scripting-api/object-types#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`](https://diceytable.com/docs/scripting-api/objecthandle) — everything a coin inherits.
- [Coin](https://diceytable.com/docs/mods/reference/object-kinds#coin) — the kind at the table: physics, size, sound, and the toss itself.
- [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) — why `toss` is observe-only.

### Members

| Signature | Description | Returns |
|---|---|---|
| [`onTossed`](https://diceytable.com/docs/scripting-api/types#coinobjectontossed) | 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

```ts
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`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleonaction) 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`](https://diceytable.com/docs/scripting-api/types#coinobject) | The same handle you subscribed on, as it was at the throw. |
| 2 | [`EventContext`](https://diceytable.com/docs/scripting-api/events#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`](https://diceytable.com/docs/scripting-api/events#globaleventsonobjectaction) 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

```ts
// 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`](https://diceytable.com/docs/scripting-api/types#coinobject) — the handle this is declared on.
- [Coin](https://diceytable.com/docs/mods/reference/object-kinds#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`](https://diceytable.com/docs/scripting-api/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 `locked` stops 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 pass `locked: true`. See [Object kinds § Table](https://diceytable.com/docs/mods/reference/object-kinds#table).

### See also

- [`globalEvents.onObjectDropped`](https://diceytable.com/docs/scripting-api/events#globaleventsonobjectdropped) - what most table rules watch.
- [`BoardObject`](https://diceytable.com/docs/scripting-api/object-types#boardobject) - the other fixture kind.
- [`SoundMaterial`](https://diceytable.com/docs/reference/enums/sound-material#struck-surface-tone) - 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`](https://diceytable.com/docs/scripting-api/types#buttonobjectonpressed). 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`](https://diceytable.com/docs/scripting-api/types#buttonobjecteventname); 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`](https://diceytable.com/docs/scripting-api/objecthandle) — everything a button inherits.
- [Button objects](https://diceytable.com/docs/mods/reference/object-kinds) — the configuration a button carries.

### Members

| Signature | Description | Returns |
|---|---|---|
| [`eventName`](https://diceytable.com/docs/scripting-api/types#buttonobjecteventname) | The configured event name for this button (default `"button-press"`). | `string` |
| [`onPressed`](https://diceytable.com/docs/scripting-api/types#buttonobjectonpressed) | Fires when a player presses this button. | `ScriptDelegate<[ButtonObject, EventContext]>` |

### buttonobject.eventName

```ts
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`](https://diceytable.com/docs/scripting-api/types#buttonobjectonpressed) — where you read this.

### buttonobject.onPressed

```ts
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`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleonaction) 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`](https://diceytable.com/docs/scripting-api/types#buttonobject) | The same handle you subscribed on. |
| 2 | [`EventContext`](https://diceytable.com/docs/scripting-api/events#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.

```ts
// 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`](https://diceytable.com/docs/scripting-api/types#buttonobjecteventname) — 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`](https://diceytable.com/docs/scripting-api/world#worldspawnobject). 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](https://diceytable.com/docs/reference/known-limitations#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`](https://diceytable.com/docs/scripting-api/world#worldspawnobject) — the call, its return value and what `null` means.
- [`ObjectKind`](https://diceytable.com/docs/scripting-api/types#objectkind) — the values `kind` accepts.
- [`Vec3`](https://diceytable.com/docs/scripting-api/types#vec3) — the shape of `position` and `rotation`.
- [Object state](https://diceytable.com/docs/mods/reference/object-state) — the full entity schema these ten fields are a slice of.
- [Known limitations](https://diceytable.com/docs/reference/known-limitations) — the full list of documented gaps.

### Members

| Signature | Description | Returns |
|---|---|---|
| [`kind`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionskind) |  | `ObjectKind` |
| [`name`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionsname) |  | `string` |
| [`position`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionsposition) |  | `Vec3` |
| [`rotation`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionsrotation) |  | `Vec3` |
| [`scale`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionsscale) | 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`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionspresetid) | Preset id from the standard object library (e.g. "die-d6", "deck-standard"). | `string` |
| [`color`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionscolor) | Tint, as a full `#rrggbb` string. Left out, the entity takes the default colour of its kind. | `string` |
| [`metadata`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionsmetadata) |  | `Record<string, unknown>` |
| [`tags`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionstags) |  | `string[]` |
| [`container`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionscontainer) | 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

```ts
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`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptions), and the only one whose absence stops the
call outright.

#### Returns

Accepts an [`ObjectKind`](https://diceytable.com/docs/scripting-api/types#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`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionstags).

#### 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`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionsname) and the
entity's slug is the kind string, so three unnamed dice all get the label `die`.

#### See also

- [`ObjectKind`](https://diceytable.com/docs/scripting-api/types#objectkind) — every value the field accepts.
- [`world.spawnObject`](https://diceytable.com/docs/scripting-api/world#worldspawnobject) — the only place this field is used.
- [`SpawnObjectOptions.presetId`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionspresetid) — how the entity gets a model.
- [Object kinds](https://diceytable.com/docs/mods/reference/object-kinds) — what each kind does.

### spawnobjectoptions.name

```ts
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`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionsmetadata) 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](https://diceytable.com/docs/reference/known-limitations#a-table-script-cannot-read-displayname).

**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`](https://diceytable.com/docs/scripting-api/objecthandle#objectdataname) — the read side, and which name it really is.
- [`SpawnObjectOptions.metadata`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionsmetadata) — where a display string belongs.
- [IDs, names and tags](https://diceytable.com/docs/editor/concepts/ids-names-tags) — `id`, `label` and `displayName`, defined once.
- [Known limitations](https://diceytable.com/docs/reference/known-limitations) — the full list of documented gaps.

### spawnobjectoptions.position

```ts
position?: Vec3;
```

| Badge | Value |
|---|---|
| Authority | `host-only` |
| Timing | `sync` |
| Capability | `none` |
| Availability | `both` |

Where the entity appears, as an absolute table-space [`Vec3`](https://diceytable.com/docs/scripting-api/types#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`](https://diceytable.com/docs/scripting-api/world#worldspawnobject)'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()`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandledeal) on a container, which
sends one item to every authored seat.

#### See also

- [`Vec3`](https://diceytable.com/docs/scripting-api/types#vec3) — the tuple shape and its coercion rules.
- [`SpawnObjectOptions.rotation`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionsrotation) — the same shape, with a different default behavior.
- [`ObjectHandle.setPosition`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesetposition) — moving an entity after it exists.
- [`world.spawnObject`](https://diceytable.com/docs/scripting-api/world#worldspawnobject) — a worked example that spaces several spawns out.

### spawnobjectoptions.rotation

```ts
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`](https://diceytable.com/docs/scripting-api/types#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`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionsposition). 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()`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlerotate) or
[`flip()`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleflip) 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`](https://diceytable.com/docs/scripting-api/types#vec3) — the tuple shape, and why rotations are absolute.
- [`SpawnObjectOptions.position`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionsposition) — the same shape, defaulted rather than dropped.
- [`ObjectHandle.setRotation`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesetrotation) — turning an entity after it exists.
- [`ObjectData.faceUp`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatafaceup) — reading which way up it ended.

### spawnobjectoptions.scale

```ts
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`](https://diceytable.com/docs/scripting-api/types#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`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatascale).
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`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatascale) — the value to copy from an existing entity.
- [`SpawnObjectOptions.rotation`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionsrotation) — the other field a replacement copies.

### spawnobjectoptions.presetId

```ts
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`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionsmetadata) — the bag this is written into, and why it wins.
- [`SpawnObjectOptions.kind`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionskind) — the field that actually decides behavior.
- [`world.spawnObject`](https://diceytable.com/docs/scripting-api/world#worldspawnobject) — a worked example using `die-d6`.
- [Object kinds](https://diceytable.com/docs/mods/reference/object-kinds) — the kind defaults a preset does not replace.

### spawnobjectoptions.color

```ts
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`](https://diceytable.com/docs/scripting-api/types#declarevariables) 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`](https://diceytable.com/docs/scripting-api/api#tableobjectstatecolor).

**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`](https://diceytable.com/docs/scripting-api/api#tableobjectstatecolor) — the replicated field this writes, and how a tint is applied.
- [`SpawnObjectOptions.presetId`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionspresetid) — the preset whose look an omitted color leaves alone.
- [`declareVariables`](https://diceytable.com/docs/scripting-api/types#declarevariables) — a `spawnable` bound to a prefab supplies this field for you.
- [`world.spawnObject`](https://diceytable.com/docs/scripting-api/world#worldspawnobject) — the call this is an option of.

### spawnobjectoptions.metadata

```ts
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`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatametadata).

#### 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`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionspresetid) 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`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionstags), 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`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesetsaveddata) 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`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatametadata) — the read side, and its `unknown` values.
- [`SpawnObjectOptions.tags`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionstags) — the field you can actually filter on.
- [`ObjectHandle.setSavedData`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesetsaveddata) — per-entity state that can change.
- [Object state](https://diceytable.com/docs/mods/reference/object-state) — where `metadata` sits in the full entity schema.

### spawnobjectoptions.tags

```ts
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`](https://diceytable.com/docs/scripting-api/world#worldgetallobjects) 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](https://diceytable.com/docs/reference/known-limitations#tag-validation-is-asymmetric).

**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`](https://diceytable.com/docs/scripting-api/world#worldgetallobjects) — the query this field exists for.
- [`ObjectData.tags`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatatags) — the read side.
- [`SpawnObjectOptions.metadata`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionsmetadata) — for data you read rather than query.
- [Tags and groups](https://diceytable.com/docs/editor/working/tags-and-groups) — the `dt:` namespace and the authoring rules.
- [Known limitations](https://diceytable.com/docs/reference/known-limitations) — the full list of documented gaps.

### spawnobjectoptions.container

```ts
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`](https://diceytable.com/docs/scripting-api/object-types#bagobjectform) and
[`infinite`](https://diceytable.com/docs/scripting-api/object-types#bagobjectinfinite) 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`](https://diceytable.com/docs/scripting-api/object-types#bagobjectputobject), 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`](https://diceytable.com/docs/scripting-api/object-types#bagobjectform) — what you are choosing between.
- [`BagObject.infinite`](https://diceytable.com/docs/scripting-api/object-types#bagobjectinfinite) — the dispenser behaviour.
- [`BagObject.putObject`](https://diceytable.com/docs/scripting-api/object-types#bagobjectputobject) — how to stock what you spawned.
- [`world.spawnObject`](https://diceytable.com/docs/scripting-api/world#worldspawnobject) — 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()`](https://diceytable.com/docs/scripting-api/world#worldgetseatzones) 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`](https://diceytable.com/docs/scripting-api/types#deckobjectdealto), 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

- [`world.getSeatZones()`](https://diceytable.com/docs/scripting-api/world#worldgetseatzones)

### Members

| Signature | Description | Returns |
|---|---|---|
| [`seat`](https://diceytable.com/docs/scripting-api/types#seatzoneinfoseat) | The owning seat, or `null` for a table zone that belongs to nobody. | `string \| null` |
| [`id`](https://diceytable.com/docs/scripting-api/types#seatzoneinfoid) |  | `string` |
| [`name`](https://diceytable.com/docs/scripting-api/types#seatzoneinfoname) |  | `string` |
| [`zoneType`](https://diceytable.com/docs/scripting-api/types#seatzoneinfozonetype) |  | `ZoneType` |
| [`primary`](https://diceytable.com/docs/scripting-api/types#seatzoneinfoprimary) | True for the seat's primary zone of its type (a seat may own several). | `boolean` |
| [`position`](https://diceytable.com/docs/scripting-api/types#seatzoneinfoposition) | World-space centre `[x, y, z]`. | `Vec3` |
| [`size`](https://diceytable.com/docs/scripting-api/types#seatzoneinfosize) | World-space box size `[x, y, z]`. | `Vec3` |
| [`rotationY`](https://diceytable.com/docs/scripting-api/types#seatzoneinforotationy) | 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

```ts
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()`](https://diceytable.com/docs/scripting-api/world#worldgetplayers) before dealing, or cards
land at an empty seat.

#### See also

- [`id`](https://diceytable.com/docs/scripting-api/types#seatzoneinfoid) — the other half of the identity.

### seatzoneinfo.id

```ts
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`](https://diceytable.com/docs/scripting-api/types#seatzoneinfoname) is the better key.

#### Gotchas

**Only unique within its seat.** Always qualify it with [`seat`](https://diceytable.com/docs/scripting-api/types#seatzoneinfoseat) — a bare
id matches a zone at every seat.

#### See also

- [`name`](https://diceytable.com/docs/scripting-api/types#seatzoneinfoname) — usually what you want instead.

### seatzoneinfo.name

```ts
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`](https://diceytable.com/docs/scripting-api/types#dealtooptionszonename) 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

- [`DealToOptions.zoneName`](https://diceytable.com/docs/scripting-api/types#dealtooptionszonename)

### seatzoneinfo.zoneType

```ts
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`](https://diceytable.com/docs/scripting-api/types#seatzoneinfoprimary) — which of several zones of a type is the main one.

### seatzoneinfo.primary

```ts
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

- [`zoneType`](https://diceytable.com/docs/scripting-api/types#seatzoneinfozonetype)

### seatzoneinfo.position

```ts
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`](https://diceytable.com/docs/scripting-api/types#deckobjectdealto). Combine with [`size`](https://diceytable.com/docs/scripting-api/types#seatzoneinfosize) 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

- [`size`](https://diceytable.com/docs/scripting-api/types#seatzoneinfosize)

### seatzoneinfo.size

```ts
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`](https://diceytable.com/docs/scripting-api/types#seatzoneinfoposition).

#### See also

- [`position`](https://diceytable.com/docs/scripting-api/types#seatzoneinfoposition)

### seatzoneinfo.rotationY

```ts
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()`](https://diceytable.com/docs/scripting-api/types#deckobjectdealto) — applies this for you.
- [Which way is "up"](https://diceytable.com/docs/editor/working/zones-and-seats#which-way-is-up-the-arrow-head) — 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`](https://diceytable.com/docs/scripting-api/world#worldgetsnappoints) and
[`world.getSnapPointAt`](https://diceytable.com/docs/scripting-api/world#worldgetsnappointat).

### 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`](https://diceytable.com/docs/scripting-api/world#worldgetsnappointat) — which point a position is on.
- [`world.getSnapPoints`](https://diceytable.com/docs/scripting-api/world#worldgetsnappoints) — all of them.

### Members

| Signature | Description | Returns |
|---|---|---|
| [`id`](https://diceytable.com/docs/scripting-api/types#snappointinfoid) |  | `string` |
| [`label`](https://diceytable.com/docs/scripting-api/types#snappointinfolabel) | The author's label, e.g. `"e4"`. Snap points nobody named read `"Snap point"`. | `string` |
| [`position`](https://diceytable.com/docs/scripting-api/types#snappointinfoposition) | World-space position `[x, y, z]`. | `Vec3` |
| [`rotationY`](https://diceytable.com/docs/scripting-api/types#snappointinforotationy) | Yaw in degrees a piece is turned to when it snaps here. | `number` |
| [`snapRadius`](https://diceytable.com/docs/scripting-api/types#snappointinfosnapradius) | How close (horizontally, in feet) a drop has to land to be pulled here. | `number` |

### snappointinfo.id

```ts
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`](https://diceytable.com/docs/scripting-api/types#snappointinfolabel).

#### See also

- [`SnapPointInfo.label`](https://diceytable.com/docs/scripting-api/types#snappointinfolabel) — the human name.

### snappointinfo.label

```ts
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`](https://diceytable.com/docs/scripting-api/types#snappointinfoid)
to tell them apart.

#### See also

- [`world.getSnapPoints`](https://diceytable.com/docs/scripting-api/world#worldgetsnappoints) — checking a whole board is labelled.

### snappointinfo.position

```ts
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`](https://diceytable.com/docs/scripting-api/world#worldgetsnappoints), 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`](https://diceytable.com/docs/scripting-api/types#snappointinfosnapradius) — how far from here a drop still counts.

### snappointinfo.rotationY

```ts
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`](https://diceytable.com/docs/scripting-api/types#snappointinfoposition) — where it is.

### snappointinfo.snapRadius

```ts
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`](https://diceytable.com/docs/scripting-api/world#worldgetsnappointat) applies, and the one the table snaps with.

#### See also

- [`world.getSnapPointAt`](https://diceytable.com/docs/scripting-api/world#worldgetsnappointat) — the rule this feeds.

## DealToOptions

_Surface A — table script · interface · 4 members_

What `DeckObject.dealTo` accepts.

What [`deck.dealTo()`](https://diceytable.com/docs/scripting-api/types#deckobjectdealto) 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

- [`deck.dealTo()`](https://diceytable.com/docs/scripting-api/types#deckobjectdealto)

### Members

| Signature | Description | Returns |
|---|---|---|
| [`seat`](https://diceytable.com/docs/scripting-api/types#dealtooptionsseat) | Target seat, e.g. `"red"`. | `string` |
| [`zoneName`](https://diceytable.com/docs/scripting-api/types#dealtooptionszonename) | 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`](https://diceytable.com/docs/scripting-api/types#dealtooptionsfacedown) | Face the card down. Defaults to the card's own facing in the deck. | `boolean` |
| [`stack`](https://diceytable.com/docs/scripting-api/types#dealtooptionsstack) | 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

```ts
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()`](https://diceytable.com/docs/scripting-api/world#worldgetplayers) 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

- [`deck.dealTo()`](https://diceytable.com/docs/scripting-api/types#deckobjectdealto)

### dealtooptions.zoneName

```ts
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()`](https://diceytable.com/docs/scripting-api/world#worldgetseatzones) — what names exist.

### dealtooptions.faceDown

```ts
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

- [`deck.dealTo()`](https://diceytable.com/docs/scripting-api/types#deckobjectdealto)

### dealtooptions.stack

```ts
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

- [`deck.dealTo()`](https://diceytable.com/docs/scripting-api/types#deckobjectdealto)

## 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`](https://diceytable.com/docs/scripting-api/events#globaleventsondicerollresult) 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`](https://diceytable.com/docs/scripting-api/world#worldgetobjectbyid) 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`](https://diceytable.com/docs/scripting-api/events#globaleventsondicerollresult) — the only thing that hands you one.
- [`globalEvents.onDiceRolled`](https://diceytable.com/docs/scripting-api/events#globaleventsondicerolled) — the per-die event that fires first.
- [`manifest.dice`](https://diceytable.com/docs/mods/manifest/reference#dice) — which dice a game offers the roller.

### Members

| Signature | Description | Returns |
|---|---|---|
| [`rollId`](https://diceytable.com/docs/scripting-api/types#dicerollsummaryrollid) | Correlates with the roll request that produced it. | `string` |
| [`actorPeerId`](https://diceytable.com/docs/scripting-api/types#dicerollsummaryactorpeerid) |  | `string` |
| [`actorName`](https://diceytable.com/docs/scripting-api/types#dicerollsummaryactorname) |  | `string` |
| [`seat`](https://diceytable.com/docs/scripting-api/types#dicerollsummaryseat) | The roller's seat, or `null` when they hold none. | `string \| null` |
| [`target`](https://diceytable.com/docs/scripting-api/types#dicerollsummarytarget) | `"tray"` (the roller's own bounded region) or `"table"`. | `"tray" \| "table"` |
| [`notation`](https://diceytable.com/docs/scripting-api/types#dicerollsummarynotation) | Dice notation, e.g. `"3d6+1d20"`. | `string` |
| [`dice`](https://diceytable.com/docs/scripting-api/types#dicerollsummarydice) |  | `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; }>` |
| [`total`](https://diceytable.com/docs/scripting-api/types#dicerollsummarytotal) | Sum of the dice that reported a NUMBER. Text results are not added. | `number` |
| [`cocked`](https://diceytable.com/docs/scripting-api/types#dicerollsummarycocked) | How many dice could not be read (a die with a text result WAS read and is not counted). | `number` |

### dicerollsummary.rollId

```ts
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`](https://diceytable.com/docs/scripting-api/types#dicerollsummarydice) — the dice this roll produced.
- [`globalEvents.onDiceRollResult`](https://diceytable.com/docs/scripting-api/events#globaleventsondicerollresult) — where the summary arrives.

### dicerollsummary.actorPeerId

```ts
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`](https://diceytable.com/docs/scripting-api/world#worldgetturn)'s `activePeerId`.

#### Gotchas

**It is a peer id, not a player record.** Turn it into something human with
[`world.getPlayers`](https://diceytable.com/docs/scripting-api/world#worldgetplayers), 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`](https://diceytable.com/docs/scripting-api/types#dicerollsummaryactorname) — the printable half.
- [`DiceRollSummary.seat`](https://diceytable.com/docs/scripting-api/types#dicerollsummaryseat) — the seat, when they hold one.
- [`PlayerInfo.peerId`](https://diceytable.com/docs/scripting-api/types#playerinfopeerid) — the same identity on the roster.

### dicerollsummary.actorName

```ts
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`](https://diceytable.com/docs/scripting-api/types#dicerollsummaryactorpeerid).

**It is frozen at emit.** A rename after the roll does not rewrite a summary you kept.

#### See also

- [`DiceRollSummary.actorPeerId`](https://diceytable.com/docs/scripting-api/types#dicerollsummaryactorpeerid) — the identity to key on.
- [`PlayerInfo.displayName`](https://diceytable.com/docs/scripting-api/types#playerinfodisplayname) — the same name on the roster.

### dicerollsummary.seat

```ts
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`](https://diceytable.com/docs/scripting-api/types#dicerollsummaryactorpeerid) 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`](https://diceytable.com/docs/scripting-api/types#dicerollsummarytarget), not this.

**A seat can change hands mid-session.** A summary you stored records who sat there *then*.

#### See also

- [`DiceRollSummary.actorPeerId`](https://diceytable.com/docs/scripting-api/types#dicerollsummaryactorpeerid) — the identity that is always present.
- [`PlayerInfo.seat`](https://diceytable.com/docs/scripting-api/types#playerinfoseat) — the same seat on the roster.
- [`globalEvents.onSeatChanged`](https://diceytable.com/docs/scripting-api/events#globaleventsonseatchanged) — when it changes.

### dicerollsummary.target

```ts
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`](https://diceytable.com/docs/scripting-api/types#dicerollsummaryseat) — whose region a `"tray"` roll used.
- [`tableObjectDefinitionSchema.diceTray`](https://diceytable.com/docs/mods/reference/object-state#dicetray) — the custody field on a die that is still the roller's.

### dicerollsummary.notation

```ts
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`](https://diceytable.com/docs/scripting-api/types#dicerollsummarydice) 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`](https://diceytable.com/docs/scripting-api/types#dicerollsummarydice) — the structured form of the same throw.
- [`manifest.dice`](https://diceytable.com/docs/mods/manifest/reference#dice) — which dice a game offers in the first place.

### dicerollsummary.dice

```ts
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`](https://diceytable.com/docs/scripting-api/world#worldgetobjectbyid) 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](https://diceytable.com/docs/editor/item-editors/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 `null`s
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`](https://diceytable.com/docs/scripting-api/types#dicerollsummarytotal) and counted in
[`cocked`](https://diceytable.com/docs/scripting-api/types#dicerollsummarycocked). 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`](https://diceytable.com/docs/scripting-api/world#worldgetobjectbyid) 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`](https://diceytable.com/docs/scripting-api/types#dicerollsummarytotal) — the sum of the readable faces.
- [`DiceRollSummary.cocked`](https://diceytable.com/docs/scripting-api/types#dicerollsummarycocked) — how many of these reported nothing.
- [`tableObjectDefinitionSchema.faceValue`](https://diceytable.com/docs/mods/reference/object-state#facevalue) — the same number as it rides in the snapshot.

### dicerollsummary.total

```ts
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`](https://diceytable.com/docs/scripting-api/types#dicerollsummarycocked) 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`](https://diceytable.com/docs/scripting-api/events#globaleventsondicerolled). 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`](https://diceytable.com/docs/scripting-api/types#dicerollsummarydice).

**`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`](https://diceytable.com/docs/scripting-api/types#dicerollsummarycocked) — read this before trusting the total.
- [`DiceRollSummary.dice`](https://diceytable.com/docs/scripting-api/types#dicerollsummarydice) — the faces the total came from.

### dicerollsummary.cocked

```ts
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 `null`s 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`](https://diceytable.com/docs/scripting-api/types#dicerollsummarytotal) — what the readable dice came to.
- [`DiceRollSummary.dice`](https://diceytable.com/docs/scripting-api/types#dicerollsummarydice) — which die reported `null`.
- [`globalEvents.onDiceRolled`](https://diceytable.com/docs/scripting-api/events#globaleventsondicerolled) — 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`](https://diceytable.com/docs/scripting-api/world#worldrequestroll): 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`](https://diceytable.com/docs/scripting-api/types#rollrequestspecdice) — where these go.
- [`manifest.dice`](https://diceytable.com/docs/mods/manifest/reference#dice) — the game's dice and their ids.

### Members

| Signature | Description | Returns |
|---|---|---|
| [`sides`](https://diceytable.com/docs/scripting-api/types#rollrequestdiesides) | Face count: 4, 6, 8, 10, 12, 20, or any face count one of your dice has. | `number` |
| [`count`](https://diceytable.com/docs/scripting-api/types#rollrequestdiecount) | How many (default 1). | `number` |
| [`die`](https://diceytable.com/docs/scripting-api/types#rollrequestdiedie) | A die by its key. With `sides` too, the two must agree. | `string` |

### rollrequestdie.sides

```ts
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`](https://diceytable.com/docs/scripting-api/types#rollrequestdiedie) — pick an exact die instead.

### rollrequestdie.count

```ts
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`](https://diceytable.com/docs/scripting-api/types#rollrequestspecdice) — several entries in one roll.

### rollrequestdie.die

```ts
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`](https://diceytable.com/docs/mods/manifest/reference#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`](https://diceytable.com/docs/scripting-api/types#rollrequestdiesides) — ask by face count instead.

## RollRequestSpec

_Surface A — table script · interface · 6 members_

What `world.requestRoll` asks a seat to roll.

What [`world.requestRoll`](https://diceytable.com/docs/scripting-api/world#worldrequestroll) asks a seat to roll.

| Field | Meaning |
|---|---|
| `dice` | One [`RollRequestDie`](https://diceytable.com/docs/scripting-api/types#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`](https://diceytable.com/docs/scripting-api/world#worldrequestroll) — the call that takes it.
- [`RollRequestResult`](https://diceytable.com/docs/scripting-api/types#rollrequestresult) — what comes back.

### Members

| Signature | Description | Returns |
|---|---|---|
| [`dice`](https://diceytable.com/docs/scripting-api/types#rollrequestspecdice) | One die type, or several. At most 8 types and 40 dice in all. | `RollRequestDie \| readonly RollRequestDie[]` |
| [`area`](https://diceytable.com/docs/scripting-api/types#rollrequestspecarea) | Where they land: the seat's walled `"tray"` (the default) or the open `"table"`. | `"tray" \| "table"` |
| [`label`](https://diceytable.com/docs/scripting-api/types#rollrequestspeclabel) | Shown on the seat's dice button with the roll, e.g. `"Attack roll"`. At most 60 characters. | `string` |
| [`timeoutSeconds`](https://diceytable.com/docs/scripting-api/types#rollrequestspectimeoutseconds) | Close the request after this many seconds (1 to 600). Default: it waits. | `number` |
| [`onTimeout`](https://diceytable.com/docs/scripting-api/types#rollrequestspecontimeout) | When it times out: `"roll"` (the default) — the host rolls for the seat; `"cancel"` — no roll. | `"roll" \| "cancel"` |
| [`clearAfterSeconds`](https://diceytable.com/docs/scripting-api/types#rollrequestspecclearafterseconds) | 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

```ts
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`](https://diceytable.com/docs/scripting-api/types#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`](https://diceytable.com/docs/scripting-api/types#rollrequestdie) — one entry.

### rollrequestspec.area

```ts
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`](https://diceytable.com/docs/scripting-api/world#worldrequestroll) — the request.

### rollrequestspec.label

```ts
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`](https://diceytable.com/docs/scripting-api/world#worldrequestroll) — the request.

### rollrequestspec.timeoutSeconds

```ts
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`](https://diceytable.com/docs/scripting-api/types#rollrequestspecontimeout) 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`](https://diceytable.com/docs/scripting-api/types#rollrequestspecontimeout) — what the timeout does.

### rollrequestspec.onTimeout

```ts
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`](https://diceytable.com/docs/scripting-api/types#rollrequestspectimeoutseconds) 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`](https://diceytable.com/docs/scripting-api/types#rollrequestresulttimedout) — how a timeout shows in the result.

### rollrequestspec.clearAfterSeconds

```ts
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`](https://diceytable.com/docs/mods/manifest/reference#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`](https://diceytable.com/docs/mods/manifest/reference#diceclearafterseconds) — the game-wide setting.

## RollRequestResult

_Surface A — table script · interface · 9 members_

How a `world.requestRoll` ended.

How a [`world.requestRoll`](https://diceytable.com/docs/scripting-api/world#worldrequestroll) 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`](https://diceytable.com/docs/scripting-api/types#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`](https://diceytable.com/docs/scripting-api/world#worldrequestroll) — the call that returns it.
- [`DiceRollSummary`](https://diceytable.com/docs/scripting-api/types#dicerollsummary) — the finished roll.

### Members

| Signature | Description | Returns |
|---|---|---|
| [`requestId`](https://diceytable.com/docs/scripting-api/types#rollrequestresultrequestid) | The request's id. It is also the finished roll's `rollId`. | `string` |
| [`seat`](https://diceytable.com/docs/scripting-api/types#rollrequestresultseat) |  | `string` |
| [`rolled`](https://diceytable.com/docs/scripting-api/types#rollrequestresultrolled) | The dice were rolled, and `result` holds them. | `boolean` |
| [`result`](https://diceytable.com/docs/scripting-api/types#rollrequestresultresult) | The finished roll (the same summary `onDiceRollResult` hands you), or `null` when not rolled. | `DiceRollSummary \| null` |
| [`byHost`](https://diceytable.com/docs/scripting-api/types#rollrequestresultbyhost) | The host rolled for the seat: a bot's or empty seat, its person left, or a timeout that rolls. | `boolean` |
| [`bot`](https://diceytable.com/docs/scripting-api/types#rollrequestresultbot) | The seat is a bot's (always rolled by the host). | `boolean` |
| [`timedOut`](https://diceytable.com/docs/scripting-api/types#rollrequestresulttimedout) | The timeout ran out (with `onTimeout: "roll"` the dice were still rolled). | `boolean` |
| [`cancelled`](https://diceytable.com/docs/scripting-api/types#rollrequestresultcancelled) | Closed without rolling: replaced, cancelled, timed out with `"cancel"`, or your scripts restarted. | `boolean` |
| [`replaced`](https://diceytable.com/docs/scripting-api/types#rollrequestresultreplaced) | Cancelled because a newer `requestRoll` for the same seat replaced it. | `boolean` |

### rollrequestresult.requestId

```ts
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`](https://diceytable.com/docs/scripting-api/events#globaleventsondicerollresult), which fires for it too.

#### Gotchas

**It is not a seat or a player id.** It names one request only.

#### See also

- [`DiceRollSummary.rollId`](https://diceytable.com/docs/scripting-api/types#dicerollsummaryrollid) — the same id on the roll.

### rollrequestresult.seat

```ts
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`](https://diceytable.com/docs/scripting-api/types#rollrequestresultbyhost) — who rolled.

### rollrequestresult.rolled

```ts
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`](https://diceytable.com/docs/scripting-api/types#rollrequestresultcancelled).**

#### See also

- [`RollRequestResult.result`](https://diceytable.com/docs/scripting-api/types#rollrequestresultresult) — the roll.

### rollrequestresult.result

```ts
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`](https://diceytable.com/docs/scripting-api/types#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`](https://diceytable.com/docs/scripting-api/types#dicerollsummary) — every field of the roll.

### rollrequestresult.byHost

```ts
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`](https://diceytable.com/docs/scripting-api/types#rollrequestresultbot) — a bot's seat.

### rollrequestresult.bot

```ts
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`](https://diceytable.com/docs/scripting-api/types#rollrequestresultbyhost) — rolled by the host.

### rollrequestresult.timedOut

```ts
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`](https://diceytable.com/docs/scripting-api/types#rollrequestspecontimeout) — what a timeout does.

### rollrequestresult.cancelled

```ts
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`](https://diceytable.com/docs/scripting-api/types#rollrequestresultreplaced)), taken back with
[`world.cancelRollRequest`](https://diceytable.com/docs/scripting-api/world#worldcancelrollrequest), 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`](https://diceytable.com/docs/scripting-api/types#rollrequestresultrolled) — the other side.

### rollrequestresult.replaced

```ts
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`](https://diceytable.com/docs/scripting-api/world#worldrequestroll) — 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

```ts
// 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`](https://diceytable.com/docs/scripting-api/events#globaleventsonplayerleft).

### See also

- [`world.getPlayers`](https://diceytable.com/docs/scripting-api/world#worldgetplayers) — the call that returns these.
- [`globalEvents.onPlayerJoined`](https://diceytable.com/docs/scripting-api/events#globaleventsonplayerjoined) — the arrival, with a `PlayerInfo` payload.
- [`globalEvents.onSeatChanged`](https://diceytable.com/docs/scripting-api/events#globaleventsonseatchanged) — how to keep a seat map that outlives the roster.
- [`TurnInfo`](https://diceytable.com/docs/scripting-api/types#turninfo) — whose turn it is, which is a separate question.
- [Host authority](https://diceytable.com/docs/scripting/concepts/host-authority) — why the script sees the table from the host's side.

### Members

| Signature | Description | Returns |
|---|---|---|
| [`peerId`](https://diceytable.com/docs/scripting-api/types#playerinfopeerid) |  | `string` |
| [`displayName`](https://diceytable.com/docs/scripting-api/types#playerinfodisplayname) |  | `string \| null` |
| [`seat`](https://diceytable.com/docs/scripting-api/types#playerinfoseat) |  | `string \| null` |
| [`team`](https://diceytable.com/docs/scripting-api/types#playerinfoteam) |  | `string \| null` |
| [`isHost`](https://diceytable.com/docs/scripting-api/types#playerinfoishost) |  | `boolean` |
| [`isBot`](https://diceytable.com/docs/scripting-api/types#playerinfoisbot) | `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`](https://diceytable.com/docs/scripting-api/types#playerinfobotid) | The bot's id from the manifest's `bots` list, or `null` for a person. | `string \| null` |
| [`difficultyId`](https://diceytable.com/docs/scripting-api/types#playerinfodifficultyid) | The difficulty the bot is playing at, or `null` for a person or a bot that declares none. | `string \| null` |
| [`deckId`](https://diceytable.com/docs/scripting-api/types#playerinfodeckid) | 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

```ts
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`](https://diceytable.com/docs/scripting-api/events#eventcontextactor) carries for a player-caused event, what
`onTurnStarted` and `onTurnEnded` report, and what [`TurnInfo.activePeerId`](https://diceytable.com/docs/scripting-api/types#turninfoactivepeerid)
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`](https://diceytable.com/docs/scripting-api/events#eventcontextactor) — where a peer id arrives from an event.
- [`PlayerInfo.displayName`](https://diceytable.com/docs/scripting-api/types#playerinfodisplayname) — the value to print instead.
- [`TurnInfo.activePeerId`](https://diceytable.com/docs/scripting-api/types#turninfoactivepeerid) — the same id, in the turn state.
- [`world.setSavedData`](https://diceytable.com/docs/scripting-api/world#worldsetsaveddata) — persisting per-player state that must outlive a connection.

### playerinfo.displayName

```ts
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`](https://diceytable.com/docs/scripting-api/types#playerinfopeerid) 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`](https://diceytable.com/docs/reference/known-limitations#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`](https://diceytable.com/docs/scripting-api/types#playerinfobotid) and [`difficultyId`](https://diceytable.com/docs/scripting-api/types#playerinfodifficultyid); key on those (or `peerId`), never on
the name.

#### See also

- [`PlayerInfo.peerId`](https://diceytable.com/docs/scripting-api/types#playerinfopeerid) — the identity to key on.
- [`world.broadcast`](https://diceytable.com/docs/scripting-api/world#worldbroadcast) — where a name belongs.
- [`globalEvents.onChatMessage`](https://diceytable.com/docs/scripting-api/events#globaleventsonchatmessage) — the other `displayName`, and why it differs.
- [IDs, names and tags](https://diceytable.com/docs/editor/concepts/ids-names-tags) — the three names an entity has, which are a separate story.

### playerinfo.seat

```ts
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`](https://diceytable.com/docs/scripting-api/events#globaleventsonseatchanged) 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`](https://diceytable.com/docs/scripting-api/types#playerinfoteam).

**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`](https://diceytable.com/docs/scripting-api/events#globaleventsonseatchanged) — the event that changes this value.
- [`PlayerInfo.team`](https://diceytable.com/docs/scripting-api/types#playerinfoteam) — the other assignment.
- [`world.getPlayers`](https://diceytable.com/docs/scripting-api/world#worldgetplayers) — the current roster.
- [`ObjectHandle.deal`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandledeal) — the action that sends one item to every authored seat.

### playerinfo.team

```ts
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`](https://diceytable.com/docs/scripting-api/events#globaleventsonteamchanged).

**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`](https://diceytable.com/docs/scripting-api/events#globaleventsonteamchanged) — the event that changes this value.
- [`PlayerInfo.seat`](https://diceytable.com/docs/scripting-api/types#playerinfoseat) — the other assignment.
- [`world.getPlayers`](https://diceytable.com/docs/scripting-api/world#worldgetplayers) — the current roster.
- [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) — why `reveal-team-a` and `reveal-team-b` are not scriptable.

### playerinfo.isHost

```ts
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`](https://diceytable.com/docs/scripting-api/types#playerinfopeerid) — the identity the comparison is made against.
- [`world.getPlayers`](https://diceytable.com/docs/scripting-api/world#worldgetplayers) — the roster, and who is in it.
- [Host authority](https://diceytable.com/docs/scripting/concepts/host-authority) — why a script is always on the host already.

### playerinfo.isBot

```ts
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`](https://diceytable.com/docs/scripting-api/bots-and-ai#botslist) 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`](https://diceytable.com/docs/scripting-api/types#playerinfodisplayname); read [`botId`](https://diceytable.com/docs/scripting-api/types#playerinfobotid) for which bot it is.

#### See also

- [`PlayerInfo.botId`](https://diceytable.com/docs/scripting-api/types#playerinfobotid) and [`PlayerInfo.difficultyId`](https://diceytable.com/docs/scripting-api/types#playerinfodifficultyid) — the two fields only a bot fills in.
- [Bots and AI](https://diceytable.com/docs/scripting-api/bots-and-ai) — registering what a bot does.

### playerinfo.botId

```ts
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`](https://diceytable.com/docs/mods/manifest/reference#modmanifestschemabots) 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`](https://diceytable.com/docs/scripting-api/types#playerinfodisplayname) 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`](https://diceytable.com/docs/scripting-api/types#playerinfoisbot) — the flag to check first.
- [`BotTurnContext.botId`](https://diceytable.com/docs/scripting-api/bots-and-ai#botturncontextbotid) — the same value inside a bot's turn.

### playerinfo.difficultyId

```ts
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`](https://diceytable.com/docs/mods/manifest/reference#modmanifestschemabotsdifficulties).

#### 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`](https://diceytable.com/docs/scripting-api/bots-and-ai#botturncontextdifficultyid) — the value your bot's turn reads.

### playerinfo.deckId

```ts
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`](https://diceytable.com/docs/mods/manifest/reference#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`](https://diceytable.com/docs/scripting-api/world#worldreaddata) (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`](https://diceytable.com/docs/scripting-api/types#playerinfodifficultyid), 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`](https://diceytable.com/docs/mods/manifest/reference#modmanifestschemalobbyrequirementsdistinctby)
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](https://diceytable.com/docs/mods/concepts/bots#players-listings-and-rewards) — how the owner hands a bot a deck.
- [`gameDecks`](https://diceytable.com/docs/mods/manifest/reference#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()`](https://diceytable.com/docs/scripting-api/world#worldgetturn), 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

```ts
// 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`](https://diceytable.com/docs/scripting-api/events#eventcontextactor).

**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`](https://diceytable.com/docs/scripting-api/world#worldgetturn) — the call that returns this.
- [`globalEvents.onTurnStarted`](https://diceytable.com/docs/scripting-api/events#globaleventsonturnstarted) — the transition, with the seat and team.
- [`globalEvents.onTurnEnded`](https://diceytable.com/docs/scripting-api/events#globaleventsonturnended) — the other half of the transition.
- [`PlayerInfo`](https://diceytable.com/docs/scripting-api/types#playerinfo) — turning `activePeerId` into a name.
- [`EventContext.actor`](https://diceytable.com/docs/scripting-api/events#eventcontextactor) — why an actor is not always a peer id.

### Members

| Signature | Description | Returns |
|---|---|---|
| [`enabled`](https://diceytable.com/docs/scripting-api/types#turninfoenabled) |  | `boolean` |
| [`activePeerId`](https://diceytable.com/docs/scripting-api/types#turninfoactivepeerid) |  | `string \| null` |
| [`seats`](https://diceytable.com/docs/scripting-api/types#turninfoseats) | 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

```ts
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`](https://diceytable.com/docs/scripting-api/types#turninfoactivepeerid). 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`](https://diceytable.com/docs/scripting-api/types#turninfoactivepeerid) — the field to read once this is `true`.
- [`world.getTurn`](https://diceytable.com/docs/scripting-api/world#worldgetturn) — the call that returns both.
- [`globalEvents.onTurnStarted`](https://diceytable.com/docs/scripting-api/events#globaleventsonturnstarted) — the only event raised when turns begin.

### turninfo.activePeerId

```ts
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`](https://diceytable.com/docs/scripting-api/types#turninfoenabled) 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`](https://diceytable.com/docs/scripting-api/events#globaleventsonturnstarted) 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`](https://diceytable.com/docs/scripting-api/events#eventcontextactor).

**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`](https://diceytable.com/docs/scripting-api/types#turninfoenabled) — the field that disambiguates `null`.
- [`PlayerInfo.peerId`](https://diceytable.com/docs/scripting-api/types#playerinfopeerid) — the same identity, on the roster side.
- [`globalEvents.onTurnStarted`](https://diceytable.com/docs/scripting-api/events#globaleventsonturnstarted) — the event that changes this value.
- [`EventContext.actor`](https://diceytable.com/docs/scripting-api/events#eventcontextactor) — why a comparison against it needs care.

### turninfo.seats

```ts
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`](https://diceytable.com/docs/scripting-api/world#worldsetturn) 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`](https://diceytable.com/docs/scripting-api/world#worldsetturn) — set it.
- [`TurnInfo.activePeerId`](https://diceytable.com/docs/scripting-api/types#turninfoactivepeerid) — 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`](https://diceytable.com/docs/scripting-api/types#botturncontextdifficulty) 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`](https://diceytable.com/docs/scripting-api/types#aimcts) 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`](https://diceytable.com/docs/mods/manifest/reference#modmanifestschemaaimodelsdifficulties) — where the dials are declared.

### Members

| Signature | Description | Returns |
|---|---|---|
| [`id`](https://diceytable.com/docs/scripting-api/types#botdifficultyinfoid) | The difficulty's id (the same as `ctx.difficultyId`). | `string` |
| [`label`](https://diceytable.com/docs/scripting-api/types#botdifficultyinfolabel) | Its name as players see it. | `string` |
| [`simsPerMove`](https://diceytable.com/docs/scripting-api/types#botdifficultyinfosimspermove) | Searches per move (`simsPerMove`): pass it to `ai.mcts` as `simulations`. `null` when not declared. | `number \| null` |
| [`temperature`](https://diceytable.com/docs/scripting-api/types#botdifficultyinfotemperature) | How adventurously to pick among good moves (`temperature`): pass it to `ai.mcts`. `null` when not declared. | `number \| null` |
| [`params`](https://diceytable.com/docs/scripting-api/types#botdifficultyinfoparams) | Your own numeric settings for this difficulty (`params`), by name. Empty when none are declared. | `Readonly<Record<string, number>>` |

### botdifficultyinfo.id

```ts
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`](https://diceytable.com/docs/scripting-api/types#botturncontextdifficultyid).

#### 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`](https://diceytable.com/docs/scripting-api/types#botdifficultyinfo).

### botdifficultyinfo.label

```ts
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`](https://diceytable.com/docs/scripting-api/types#botdifficultyinfo).

### botdifficultyinfo.simsPerMove

```ts
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`](https://diceytable.com/docs/scripting-api/types#aimcts) as [`simulations`](https://diceytable.com/docs/scripting-api/types#mctsspecsimulations).

#### 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`](https://diceytable.com/docs/scripting-api/types#botdifficultyinfo).

### botdifficultyinfo.temperature

```ts
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`](https://diceytable.com/docs/scripting-api/types#aimcts) as [`temperature`](https://diceytable.com/docs/scripting-api/types#mctsspectemperature).

#### 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`](https://diceytable.com/docs/scripting-api/types#botdifficultyinfo).

### botdifficultyinfo.params

```ts
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

- [`BotDifficultyInfo`](https://diceytable.com/docs/scripting-api/types#botdifficultyinfo).

## 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.

```ts
declare type UiWidgetPatch = {
  [K in Exclude<keyof UiWidget, "id" | "kind">]?: UiWidget[K] | null;
} & { kind?: UiWidget["kind"] };
```

A change to a widget: what [`ui.update`](https://diceytable.com/docs/scripting-api/game-ui#uiupdate) takes as its
`patch`, and what [`ui.show`](https://diceytable.com/docs/scripting-api/game-ui#uishow) takes as `overrides` when it
re-shows a widget by id. It has every [`UiWidget`](https://diceytable.com/docs/scripting-api/game-ui#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`](https://diceytable.com/docs/scripting-api/game-ui#uishow) 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`](https://diceytable.com/docs/scripting-api/game-ui#uiupdate) — with an example that removes `timing`.
- [`ui.show`](https://diceytable.com/docs/scripting-api/game-ui#uishow) — `overrides` on a re-show.
- [`UiWidget`](https://diceytable.com/docs/scripting-api/game-ui#uiwidget) — every field.
- [`ModUiWidgetPatch`](https://diceytable.com/docs/scripting-api/api#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.

```ts
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`](https://diceytable.com/docs/scripting-api/types#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`](https://diceytable.com/docs/scripting-api/types#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`](https://diceytable.com/docs/scripting-api/types#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`](https://diceytable.com/docs/scripting-api/types#declarevariables) does.

**Thirty-two declarations per script, and the whole literal is rejected past that.** See
[`declareVariables`](https://diceytable.com/docs/scripting-api/types#declarevariables) for why the cap exists.

### See also

- [`declareVariables`](https://diceytable.com/docs/scripting-api/types#declarevariables) — the call these specs go into.
- [`ScriptVariableValue`](https://diceytable.com/docs/scripting-api/types#scriptvariablevalue) — what each `type` reads back as.
- [`ObjectKind`](https://diceytable.com/docs/scripting-api/types#objectkind) — the kinds a `kind` filter may name.
- [`SeatZoneInfo`](https://diceytable.com/docs/scripting-api/types#seatzoneinfo) — what a `zone` variable 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.

```ts
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`](https://diceytable.com/docs/scripting-api/types#declarevariables) turns each [`ScriptVariableSpec`](https://diceytable.com/docs/scripting-api/types#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`](https://diceytable.com/docs/scripting-api/world#worldgetobjectbyid).

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`](https://diceytable.com/docs/scripting-api/types#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`](https://diceytable.com/docs/scripting-api/types#declarevariables) — where these values come from.
- [`ScriptVariableSpec`](https://diceytable.com/docs/scripting-api/types#scriptvariablespec) — the declaration each of these is derived from.
- [`ObjectHandle`](https://diceytable.com/docs/scripting-api/objecthandle) — what an `object` variable hands you.
- [`SeatZoneInfo`](https://diceytable.com/docs/scripting-api/types#seatzoneinfo) — what a `zone` variable hands you.
- [Async and snapshots](https://diceytable.com/docs/scripting/concepts/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.

```ts
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`](https://diceytable.com/docs/scripting-api/types#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`](https://diceytable.com/docs/scripting-api/types#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

```ts
// 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`](https://diceytable.com/docs/scripting-api/types#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`](https://diceytable.com/docs/scripting-api/types#scriptvariablespec) — the ten declaration shapes and the filters each one accepts.
- [`ScriptVariableValue`](https://diceytable.com/docs/scripting-api/types#scriptvariablevalue) — what each declared type reads back as, and when it reads `null`.
- [`world.spawnObject`](https://diceytable.com/docs/scripting-api/world#worldspawnobject) — where a `spawnable` template goes.
- [`SpawnObjectOptions`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptions) — the shape a `spawnable` reads as.
- [Host authority](https://diceytable.com/docs/scripting/concepts/host-authority) — why the values are resolved on one peer.
