# ObjectHandle

> A live handle to one entity on the table - the ten read-only fields a table script can see, and the fourteen methods it can call to move, act on and read it.

- Source: https://diceytable.com/docs/scripting-api/objecthandle
- Last verified: 2026-07-30

An `ObjectHandle` is one entity on the table, as a table script sees it. Every handle carries the ten read-only
fields of [`ObjectData`](https://diceytable.com/docs/scripting-api/objecthandle#objectdata), fourteen methods, and eight event delegates that fire only for that entity.
A handle whose entity is a card, a deck, a bag or a card holder is also one of the narrower types on
[Object Types](https://diceytable.com/docs/scripting-api/object-types), which add the members only that kind has.

Handles come from four places: [`world.getObjectById`](https://diceytable.com/docs/scripting-api/world#worldgetobjectbyid),
[`world.getAllObjects`](https://diceytable.com/docs/scripting-api/world#worldgetallobjects),
[`world.spawnObject`](https://diceytable.com/docs/scripting-api/world#worldspawnobject), and the payload of a `globalEvents` delegate.
In an object script, `refObject` is the handle for the entity the script is attached to.

**A handle is a cache, not a live view.** Its `ObjectData` fields hold the state the host last reported, and they
update when the handle is delivered by a query, delivered by an event, or refreshed with
[`refresh()`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlerefresh). The twelve mutators all return `void` immediately: they post an intent and do
not wait, so the handle you called one on still reports the old value on the next line.

The sandbox keeps **one handle object per id**. Two lookups of the same entity give you the same JavaScript
object, so holding a handle in a variable and refreshing it is equivalent to looking it up again.

## Nine of the fourteen methods are object actions

[Members](https://diceytable.com/docs/scripting-api/objecthandle#members) below is the generated signature table for all fourteen, followed by a full entry for each.
It is derived from the declarations, so it cannot drift from them.

`flip`, `rotate`, `lock`, `unlock`, `roll`, `shuffle`, `draw`, `deal` and `destroy` each post an `object-action`
intent. `destroy()` is the one whose method name differs from its action name — it sends `delete`.

Four action names in the table-script vocabulary have **no method here at all**: `tap`, `untap`, `split` and
`combine`. They are in the `ObjectAction` type union and the script host's allowlist accepts them, so nothing
below the typed API is missing — only the calling surface is. Do not write code that assumes a method for them.
[Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) has the full three-way comparison and classifies each
gap; [Known limitations](https://diceytable.com/docs/reference/known-limitations#actions-with-no-objecthandle-method) lists them
alongside every other documented gap.

## Events

This page also carries `ObjectHandle`'s eight object-scoped delegates — `onCreated`, `onDestroyed`, `onPickedUp`,
`onDropped`, `onAction`, `onRolled`, `onCardDrawn` and `onShuffled`. Each is the entity-scoped twin of a
`globalEvents` delegate and fires only when the event's entity is this one — with one deliberate exception:
`onCardDrawn` is routed to the **container** the card came from, not to the card, because `deck.onCardDrawn` is
what an author means. See
[Events](https://diceytable.com/docs/scripting-api/events) for how delegates work, which peer fires them, and how many times.

## What a handle can see

[`ObjectData`](https://diceytable.com/docs/scripting-api/objecthandle#objectdata) is the read-only state every handle carries, and it is also what `refresh()` resolves
with — as a plain copy with no methods and no delegates. Its ten fields, with an entry for each, are in the
`ObjectData` section below.

Three things a table script **cannot** see about an entity: its `displayName`, its `parentId`, and its engine
components. All three exist on the replicated entity state and none is published here. Mod scripting is not
affected — a mod reads all three off the state its peer received, subject to hidden-information redaction
(which deletes `displayName` from a card that peer may not identify). See
[Parenting is invisible to table scripts](https://diceytable.com/docs/reference/known-limitations#parenting-is-invisible-to-table-scripts)
and [A table script cannot read displayName](https://diceytable.com/docs/reference/known-limitations#a-table-script-cannot-read-displayname).

## See also

- [`World`](https://diceytable.com/docs/scripting-api/world) — where handles come from.
- [Events](https://diceytable.com/docs/scripting-api/events) — the delegates that hand you a handle, and the eight on this page.
- [Types](https://diceytable.com/docs/scripting-api/types) — `Vec3`, `ObjectKind`, `ObjectAction`.
- [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) — 27 engine actions, 13 a script may request, 9 with
  a method.
- [Object kinds](https://diceytable.com/docs/mods/reference/object-kinds) — what each kind is and how it behaves.
- [Object state](https://diceytable.com/docs/mods/reference/object-state) — the full replicated state, including the fields
  `ObjectData` omits.
- [Host authority](https://diceytable.com/docs/scripting/concepts/host-authority) — why a mutator returns before anything has changed.
- [Known limitations](https://diceytable.com/docs/reference/known-limitations) — every documented gap, in one list.

## ObjectHandle

_Surface A — table script · interface · 26 members_

An `ObjectHandle` is the sandbox's cached record of one entity, wrapped in the methods and delegates that act on
it. The twelve [`ObjectData`](https://diceytable.com/docs/scripting-api/objecthandle#objectdata) fields on it are **getter-only accessors** over a record the sandbox
owns and rewrites: there is no setter behind any of them, so `handle.position = [0, 2, 0]` moves nothing and
never reaches the host. `setPosition` is the only way to move an entity, and it moves the entity rather than the
handle.

The sandbox keys handles by id in a map it never prunes, which is what makes "one handle object per id" true for
the whole session — the handle an event gives you in minute one is identity-equal to the one a query gives you in
minute forty, and refreshing either updates both. It also means a handle outlives the entity: after `destroy()`
the object is still in the map, still answers its twelve fields with the last state anyone saw, and its
`refresh()` resolves `null`.

### How, why and when to use it

You are writing the rule that fires when a card lands in a zone, and you need to know what that card is before you
decide what to do. The delegate hands you a handle rather than an id precisely so you do not have to go back to
`world.getObjectById` for the state you already have — the sandbox populated the handle from the same event
payload. Reach for `world.getObjectById` only when all you were given is an id (`onObjectDestroyed` hands you a
bare `string`), and reach for `refresh()` when time has passed inside your handler and you need the host's
current answer rather than the one that arrived with the event.

### Gotchas

**A handle reaches the table through only three intent types.** `setPosition` and `setRotation` post a
`transform`; `flip`, `rotate`, `lock`, `unlock`, `roll`, `shuffle`, `draw`, `deal` and `destroy` post an
`object-action`; `setTooltip` and `setTooltipVariable` post a host-only `set-object-tooltip`. Nothing else on a
handle writes to the table, which is why an entity's tags, metadata and `label` are fixed at spawn.

**Do not hold a handle as a "before" value.** A `refresh()`, a query or an event anywhere in your script rewrites
the same record you are reading, so comparing a stored handle against the live table compares an object with
itself. Copy the fields you want to compare into your own variables.

**An entity's `displayName`, `parentId` and engine components are not on it.** All three exist on the replicated
entity state and none is published to a table script. See
[A table script cannot read `displayName`](https://diceytable.com/docs/reference/known-limitations#a-table-script-cannot-read-displayname)
and [Parenting is invisible to table scripts](https://diceytable.com/docs/reference/known-limitations#parenting-is-invisible-to-table-scripts).

### See also

- [`ObjectData`](https://diceytable.com/docs/scripting-api/objecthandle#objectdata) — the twelve fields, and what each one is populated from.
- [`world.getObjectById`](https://diceytable.com/docs/scripting-api/world#worldgetobjectbyid) — resolving a handle from an id.
- [`refObject`](https://diceytable.com/docs/scripting-api/objecthandle#refobject) — the handle an object script starts with.
- [`ObjectHandle.refresh`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlerefresh) — re-reading an entity from the host.
- [Async and snapshots](https://diceytable.com/docs/scripting/concepts/async-and-snapshots) — what an `await` invalidates.

### Members

| Signature | Description | Returns |
|---|---|---|
| [`onCreated`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleoncreated) |  | `ScriptDelegate<[ObjectHandle, EventContext]>` |
| [`onDestroyed`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleondestroyed) | Fires when this entity leaves the table. `context.reason` says why, and for `"absorbed"` `context.containerId` names the stack that took it. | `ScriptDelegate<[EventContext]>` |
| [`onPickedUp`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleonpickedup) |  | `ScriptDelegate<[ObjectHandle, EventContext]>` |
| [`onDropped`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleondropped) |  | `ScriptDelegate<[ObjectHandle, EventContext]>` |
| [`onAction`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleonaction) |  | `ScriptDelegate<[ObjectHandle, ObservedObjectAction, EventContext]>` |
| [`onRolled`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleonrolled) | Fires when this die settles after a roll. `value` is the face value when known. | `ScriptDelegate<[ObjectHandle, number \| null, EventContext]>` |
| [`onCardDrawn`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleoncarddrawn) | Fires on a CONTAINER when a card is drawn from it: the handle argument is the newly created card, and `context.containerId` is this container's id. | `ScriptDelegate<[ObjectHandle, EventContext]>` |
| [`onShuffled`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleonshuffled) |  | `ScriptDelegate<[ObjectHandle, EventContext]>` |
| [`onMenuItem`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleonmenuitem) | A player clicked one of this script's menu entries ON THIS ENTITY. The string is your own item id. The item still has to `match` this entity to be offered at all. | `ScriptDelegate<[ObjectHandle, string, EventContext]>` |
| [`onClicked`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleonclicked) | A player clicked THIS entity: pressed and released it without dragging (a mouse click, a touch tap, a VR trigger tap). Fires for locked entities too. See `globalEvents.onObjectClicked`. | `ScriptDelegate<[ObjectHandle, ObjectClickContext]>` |
| [`refresh()`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlerefresh) | Refresh and return this object's latest state (null if it no longer exists). | `Promise<ObjectData \| null>` |
| [`setPosition(position: Vec3)`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesetposition) |  | `void` |
| [`setRotation(rotation: Vec3)`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesetrotation) |  | `void` |
| [`flip()`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleflip) |  | `void` |
| [`rotate()`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlerotate) |  | `void` |
| [`lock()`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlelock) |  | `void` |
| [`unlock()`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleunlock) |  | `void` |
| [`roll()`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleroll) | Roll this object (dice). | `void` |
| [`shuffle(options?: ObjectActionOptions)`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleshuffle) | Shuffle this container/deck. Pass { silent: true } to reorder without the spin or the riffle — for setup a player is not meant to be watching. | `void` |
| [`draw()`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandledraw) | Draw the top item from this deck/bag. | `void` |
| [`deal()`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandledeal) | Deal cards from this deck to players. | `void` |
| [`destroy()`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandledestroy) | Remove this object from the table. | `void` |
| [`setTooltip(options: TooltipOptions)`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesettooltip) | Change this entity's hover tooltip. Only the fields you pass change. Tooltips are off by default, so pass `enabled: true` to show one. | `void` |
| [`setTooltipVariable(name: string, value: TooltipVariableValue \| null)`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesettooltipvariable) | Set one tooltip variable, read in the title or description as `{name}`. A name is a letter or `_` followed by up to 31 letters, digits or `_`; `null` deletes it. The value is shown as plain text — formatting characters in it are not interpreted. | `void` |
| [`getSavedData(key?: string)`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlegetsaveddata) |  | `Promise<string \| null>` |
| [`setSavedData(value: string, key?: string)`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesetsaveddata) |  | `Promise<void>` |

### objecthandle.onCreated

```ts
readonly onCreated: ScriptDelegate<[ObjectHandle, EventContext]>;
```

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

Fires when the entity this handle addresses comes into existence — a `spawn` intent, or one of the gameplay
paths that creates an entity. It is the entity-scoped twin of
[`globalEvents.onObjectCreated`](https://diceytable.com/docs/scripting-api/events#globaleventsonobjectcreated), and it fires
immediately after it, for the same event.

#### Parameters

The handler receives two arguments, transcribed from `ScriptDelegate<[ObjectHandle, EventContext]>`:

| Position | Type | Notes |
|---|---|---|
| 1 | [`ObjectHandle`](https://diceytable.com/docs/scripting-api/objecthandle) | The same handle you subscribed on. The sandbox keeps one handle per id, so this is the identical object, refilled from the host's state. |
| 2 | [`EventContext`](https://diceytable.com/docs/scripting-api/events#eventcontext) | Who spawned it — `"Script"` for a `world.spawnObject` call, `"You"` for the local Add menu, or a peer id. |

**Applies to: every object kind.**

#### How, why and when to use it

This delegate has exactly one moment where it can fire, and it is a genuinely useful one: the handle
[`world.spawnObject`](https://diceytable.com/docs/scripting-api/world#worldspawnobject) hands back resolves **before** the host has
validated anything, so a non-`null` handle only means the request was well-formed. Subscribing `onCreated` on
that handle turns the optimistic result into a confirmation — when it fires, the entity really is on the table.
The alternative is `await handle.refresh()` and a `null` check, which is what to reach for when you want a single
answer *now*; use `onCreated` when you want to carry on and be told later, without holding an `await` open.

#### Example

```ts
// content/scripting-api/examples/objecthandle.onCreated.ts

// Scene script: confirm a spawn landed. spawnObject resolves optimistically,
// so the handle exists before the host has applied anything; onCreated on that
// same handle is the host confirming the entity is really on the table.

async function spawnConfirmedDie(): Promise<void> {
  const die = await world.spawnObject({
    kind: "die",
    name: "confirmed-die",
    presetId: "die-d6",
    position: [0, 1, 0]
  });

  if (!die) {
    world.log("spawnObject refused the request: kind must be a non-empty string.");
    return;
  }

  world.log(`Requested ${die.id}; waiting for the host to confirm it.`);

  die.onCreated.add((entity, context) => {
    world.log(`Confirmed ${entity.id} (${entity.kind}) created by ${context.actor}.`);
    entity.roll();
  });

  // If the host rejected the definition, no event ever arrives - check.
  await world.wait(3);
  const applied = await die.refresh();
  if (applied === null) {
    world.log(`${die.id} was never created - read the script console for the diagnostic.`);
  }
}

void spawnConfirmedDie();
```

The script console prints `Requested script-1f2e3d4c5b6a7089; waiting for the host to confirm it.` and then
`Confirmed script-1f2e3d4c5b6a7089 (die) created by Script.`

#### Gotchas

**An object script attached at start never sees its own `refObject.onCreated`.** That entity was created before
the script host booted, so there is nothing to fire for, and the top of the script body is the "this entity is
ready" moment. The exception is an entity created *while* scripts are running: its object script is attached
before the event is dispatched, so `refObject.onCreated` does fire — see
[Execution order](https://diceytable.com/docs/scripting/concepts/execution-order).

**You have to hold the handle before the entity exists.** Otherwise the only way to subscribe in time is to have
the handle already, which in practice means the one `world.spawnObject` returned. A handle you fetch afterwards
with `world.getObjectById` is too late.

**No event arrives when the host rejects the spawn.** A definition that fails schema validation — an over-long
tag is the usual cause — produces a diagnostic and nothing else. Pair the subscription with a timeout and a
`refresh()`, as the example does. See
[Tag validation is asymmetric](https://diceytable.com/docs/reference/known-limitations#tag-validation-is-asymmetric).

**The table-wide delegate fires first.** `globalEvents.onObjectCreated` fans out before this one, for the same
event.

#### See also

- [`globalEvents.onObjectCreated`](https://diceytable.com/docs/scripting-api/events#globaleventsonobjectcreated) — the table-wide twin, and the two paths that raise it.
- [`world.spawnObject`](https://diceytable.com/docs/scripting-api/world#worldspawnobject) — where the handle comes from.
- [`ObjectHandle.refresh`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlerefresh) — the one-shot alternative to subscribing.
- [Async and snapshots](https://diceytable.com/docs/scripting/concepts/async-and-snapshots) — what "optimistic" means in full.
- [Execution order](https://diceytable.com/docs/scripting/concepts/execution-order) — why an object script's own entity is already there.

### objecthandle.onDestroyed

```ts
readonly onDestroyed: ScriptDelegate<[EventContext]>;
```

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

Fires when this entity leaves the table. `context.reason` says why, and for
`"absorbed"` `context.containerId` names the stack that took it.

Fires when the entity this handle addresses leaves the table. It is the one delegate whose signature differs from
its table-wide twin: it receives **only** the context, because the handle is already the subject and there is
nothing left to hand you. Immediately after the fan-out the sandbox discards the handle from its cache, so this
is the last moment the entity exists as far as your script is concerned.

#### Parameters

The handler receives one argument, transcribed from `ScriptDelegate<[EventContext]>`:

| Position | Type | Notes |
|---|---|---|
| 1 | [`EventContext`](https://diceytable.com/docs/scripting-api/events#eventcontext) | Who removed it, and why. `actor` is `"Script"` for a `destroy()` call, a peer id for a player, `"You"` on a solo table. [`reason`](https://diceytable.com/docs/scripting-api/events#eventcontextreason) is one of `"deleted"`, `"depleted"`, `"converted"` or `"absorbed"`, and on `"absorbed"` `containerId` names the stack that took this entity. |

**Applies to: every object kind.** A deck also raises it when a draw empties it or reduces it to one card, and
any card-like entity raises it when a combine folds it into a stack.

#### How, why and when to use it

An object script is holding a running total for its own piece — a token's hit points, a deck's shuffle count —
and the piece is about to disappear. This is where you flush it: write it to saved data, tell the table, hand a
replacement out. The alternative is checking for a `null` from `refresh()` on the next read, which tells you the
entity is gone but not when, not who, and not in time to say anything about it. Use `onDestroyed` when the
disappearance is worth reacting to; rely on a `null` from `refresh()` when you only need the current answer.

#### Example

```ts
// content/scripting-api/examples/objecthandle.onDestroyed.ts

// Object script: this delegate receives the context and nothing else - the
// handle is the subject, so there is nothing to hand you. Read whatever you
// need from the entity BEFORE it goes, because the sandbox drops the handle
// immediately after this fan-out.

const label = refObject.name ?? refObject.kind;
const startedAt = Date.now();

refObject.onDestroyed.add((context) => {
  const lifetime = Math.round((Date.now() - startedAt) / 1000);
  world.broadcast(`${label} was removed by ${context.actor} after ${lifetime}s.`);
  world.log(`${label}: handle discarded; further reads would address nothing.`);
});

refObject.onPickedUp.add((entity, context) => {
  // Cached values stay valid while the entity exists - the event refreshes
  // the handle just before your handler runs.
  world.log(`${label} lifted by ${context.actor} from [${entity.position.join(", ")}] ft.`);
});

world.log(`Watching the lifetime of ${label} (${refObject.id}).`);
```

Deleting the piece puts `red-token was removed by You after 47s.` into the table chat and prints
`red-token: handle discarded; further reads would address nothing.` to the script console.

#### Gotchas

**The handle is dropped from the cache right after your handler returns.** The sandbox deletes the entry once the
entity-scoped fan-out finishes (`apps/web/src/scripting/sandbox/tableScriptSandbox.html`,
`routeLifecycleEvent`), so a later `world.getObjectById` on that id builds a **new**, empty handle rather than
returning yours — and your registered handlers are not on it. Read what you need inside the handler.

**No handle argument, by design of the payload.** Read the entity's fields from the outer `refObject`, or cache
what you need at startup as the example caches `label`. They still hold the last state the host reported.

**`onAction` with `"delete"` fires first, and so does the table-wide `onObjectDestroyed`.** For a delete the
order is `globalEvents.onObjectAction`, `ObjectHandle.onAction`, `globalEvents.onObjectDestroyed`, then this.

**A deck can be destroyed without anyone deleting it.** Drawing the last card removes the deck
(`reason: "depleted"`), drawing down to one card converts the remainder to a card and removes the deck entity
(`reason: "converted"`), and a combine folds a card or a deck into another stack (`reason: "absorbed"`). Check
[`context.reason`](https://diceytable.com/docs/scripting-api/events#eventcontextreason) before you treat the disappearance as a loss —
an absorbed entity's cards are still in play inside `context.containerId`, and they come back out as **new
entities with new ids**.

#### See also

- [`ObjectDestroyedReason`](https://diceytable.com/docs/scripting-api/types#objectdestroyedreason) — the four causes, and the runtime path behind each.

- [`globalEvents.onObjectDestroyed`](https://diceytable.com/docs/scripting-api/events#globaleventsonobjectdestroyed) — the table-wide twin, which receives an id.
- [`ObjectHandle.destroy`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandledestroy) — the call that raises this from a script.
- [`ObjectHandle.setSavedData`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesetsaveddata) — where a per-entity total should be flushed to.
- [`EventContext`](https://diceytable.com/docs/scripting-api/events#eventcontext) — the only argument this delegate passes.
- [Events and delegates](https://diceytable.com/docs/scripting/concepts/events-and-delegates) — why this delegate's two scopes differ.

### objecthandle.onPickedUp

```ts
readonly onPickedUp: ScriptDelegate<[ObjectHandle, EventContext]>;
```

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

Fires when the entity this handle addresses is lifted off the table. It is the entity-scoped twin of
[`globalEvents.onObjectPickedUp`](https://diceytable.com/docs/scripting-api/events#globaleventsonobjectpickedup) and fires immediately
after it, with the same two arguments — a remote player's drag, a desktop grab and a VR grab all reach it.

#### Parameters

The handler receives two arguments, transcribed from `ScriptDelegate<[ObjectHandle, EventContext]>`:

| Position | Type | Notes |
|---|---|---|
| 1 | [`ObjectHandle`](https://diceytable.com/docs/scripting-api/objecthandle) | The same handle you subscribed on, refilled from the event's state — so `position` is where the entity was picked up from. |
| 2 | [`EventContext`](https://diceytable.com/docs/scripting-api/events#eventcontext) | A peer id for a remote player, `"You"` for a grab on the host machine. Never `"Script"`. |

**Applies to: every object kind.**

#### How, why and when to use it

An object script on a piece wants to remember where that piece started, so a bad placement can be undone. On the
handle there is nothing to filter: the delegate fires only for this entity, so the handler has no `if
(entity.id === …)` at the top. The alternative is `globalEvents.onObjectPickedUp` plus that comparison, which is
the right choice when one script watches many pieces or when the set of pieces is not known at author time.
Subscribe on the handle when the rule belongs to the piece; subscribe on `globalEvents` when the rule belongs to
the game.

#### Example

```ts
// content/scripting-api/examples/objecthandle.onPickedUp.ts

// Object script: remember where this piece started so a drop can put it back.
// Attaching the script to the piece means no id filtering - this delegate
// fires only for the entity the script is attached to.

let home: Vec3 | null = null;

refObject.onPickedUp.add((entity, context) => {
  if (home === null) {
    home = [entity.position[0], entity.position[1], entity.position[2]];
    world.log(`${entity.name ?? entity.id}: home recorded at [${home.join(", ")}] ft.`);
  }
  world.log(`${entity.name ?? entity.id} lifted by ${context.actor}.`);
});

refObject.onDropped.add((entity, context) => {
  if (home === null) {
    return;
  }

  const drift = Math.abs(entity.position[0] - home[0]) + Math.abs(entity.position[2] - home[2]);
  if (drift > 4) {
    entity.setPosition(home);
    world.broadcast(`${entity.name ?? entity.id} went too far and was returned.`);
  } else {
    world.log(`${entity.name ?? entity.id} placed by ${context.actor}; drift ${drift.toFixed(2)} ft.`);
  }
});

world.log(`Home-position keeper is watching ${refObject.id}.`);
```

Lifting the piece prints `red-token: home recorded at [1, 0.35, -2] ft.` and `red-token lifted by You.`;
releasing it more than four feet away puts `red-token went too far and was returned.` into the table chat.

#### Gotchas

> **By design.** A grab on a member of a parented assembly escalates to the **root ancestor**
> (`apps/web/src/playcanvas/TabletopRuntime.ts`, `resolveGrabTarget`), so an object script attached to a *child*
> is never told its own piece was picked up — the root's delegate fires instead. Escalation stops at the first
> ancestor that is locked or that the actor may not drag; Alt+grab targets the child on desktop, and **a VR grab
> escalates unconditionally, because a headset has no Alt**. Mark a child that genuinely should move on its own
> with `grabbableWhileParented` in its `metadata` — the exemption is ignored while the assembly is welded or an
> ancestor is restricted. Attach a script that cares about pickups to the piece a player actually grabs.

**A scripted move raises nothing.** `setPosition` teleports without a hold, so the correction in the example
cannot re-enter its own handler.

**`refObject` exists only in an object script.** The declaration types it as always present and it is
`undefined` in a scene script. In a scene script, get a handle from `world.getObjectById` and subscribe on that.
See [Known limitations](https://diceytable.com/docs/reference/known-limitations#refobject-is-undefined-in-scene-scripts).

#### See also

- [`globalEvents.onObjectPickedUp`](https://diceytable.com/docs/scripting-api/events#globaleventsonobjectpickedup) — the table-wide twin, and multiplicity for a group drag.
- [`ObjectHandle.onDropped`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleondropped) — the end of the same hold.
- [`ObjectHandle.setPosition`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesetposition) — putting a piece back.
- [Grab events report the assembly root](https://diceytable.com/docs/reference/known-limitations#grab-events-report-the-assembly-root) — escalation, in full.
- [Events and delegates](https://diceytable.com/docs/scripting/concepts/events-and-delegates) — scope, ordering and multiplicity.

### objecthandle.onDropped

```ts
readonly onDropped: ScriptDelegate<[ObjectHandle, EventContext]>;
```

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

Fires when the entity this handle addresses is released. It is the entity-scoped twin of
[`globalEvents.onObjectDropped`](https://diceytable.com/docs/scripting-api/events#globaleventsonobjectdropped) and fires immediately
after it. The entity has been let go but has not settled — the position you read is the release point.

#### Parameters

The handler receives two arguments, transcribed from `ScriptDelegate<[ObjectHandle, EventContext]>`:

| Position | Type | Notes |
|---|---|---|
| 1 | [`ObjectHandle`](https://diceytable.com/docs/scripting-api/objecthandle) | The same handle you subscribed on, refilled from the event's state. |
| 2 | [`EventContext`](https://diceytable.com/docs/scripting-api/events#eventcontext) | A peer id for a remote player's release, `"You"` for a release on the host machine. Never `"Script"`. |

**Applies to: every object kind.**

#### How, why and when to use it

A piece has to sit in one of four lanes, and players are not going to place it exactly. This delegate is where a
piece enforces its own placement rule: it fires only for this entity, so the handler is the rule and nothing
else. The alternative is `globalEvents.onObjectDropped` with an id comparison, which is what you want when the
rule is about the board rather than the piece — a zone that accepts anything, say. Put the rule on the piece when
every copy of that piece needs it; put it on `globalEvents` when the rule is about where things land.

#### Example

```ts
// content/scripting-api/examples/objecthandle.onDropped.ts

// Object script: snap this piece to the nearest lane when a player lets go.
// Nothing can refuse a drop, so the pattern is always react-and-correct: let
// it land, then push it where the rules say it belongs.

const LANES = [-3, -1, 1, 3];

function nearestLane(x: number): number {
  let best = LANES[0];
  for (const lane of LANES) {
    if (Math.abs(lane - x) < Math.abs(best - x)) {
      best = lane;
    }
  }
  return best;
}

refObject.onDropped.add((entity, context) => {
  const [x, y, z] = entity.position;
  const lane = nearestLane(x);

  if (Math.abs(lane - x) < 0.05) {
    world.log(`${entity.name ?? entity.id} already sits in lane ${lane}.`);
    return;
  }

  entity.setPosition([lane, y, z]);
  world.log(`${context.actor} dropped ${entity.name ?? entity.id} at x=${x.toFixed(2)}; snapped to lane ${lane}.`);
});

world.log(`Lane snapper is watching ${refObject.id}.`);
```

Dropping the piece anywhere near a lane prints `You dropped red-token at x=-2.62; snapped to lane -3.`

#### Gotchas

**The position is the release point, not the resting place.** Physics continues after the event, so a piece
dropped at speed keeps travelling. Snap immediately, as the example does, or `await world.wait(1)` and
`await entity.refresh()` if the rule depends on where it actually stops.

**Nothing can refuse the drop.** By the time this runs the host has applied it and broadcast it. React and
correct. See [Nothing can cancel an action](https://diceytable.com/docs/reference/known-limitations#nothing-can-cancel-an-action).

> **By design.** A drop on a member of a parented assembly reports the **root ancestor**, so an object script on
> a child is never told about the drop — the root's delegate fires instead
> (`apps/web/src/playcanvas/TabletopRuntime.ts`, `resolveGrabTarget`). Escalation stops at the first ancestor
> that is locked or that the actor may not drag, Alt+grab targets the child on desktop, and a VR grab escalates
> unconditionally. Attach a placement rule to the piece a player actually grabs, or mark the child
> `grabbableWhileParented` in its `metadata`.

**A group drag raises this once per surviving member.** A piece consumed by a combine or a shuffle during the
hold raises `onDestroyed` instead.

#### See also

- [`globalEvents.onObjectDropped`](https://diceytable.com/docs/scripting-api/events#globaleventsonobjectdropped) — the table-wide twin, and turn accounting.
- [`ObjectHandle.onPickedUp`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleonpickedup) — the start of the same hold.
- [`ObjectHandle.setPosition`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesetposition) — the correction itself.
- [Grab events report the assembly root](https://diceytable.com/docs/reference/known-limitations#grab-events-report-the-assembly-root) — escalation, in full.
- [Events and delegates](https://diceytable.com/docs/scripting/concepts/events-and-delegates) — scope, ordering and multiplicity.

### objecthandle.onAction

```ts
readonly onAction: ScriptDelegate<[ObjectHandle, ObservedObjectAction, EventContext]>;
```

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

Fires for every object action applied to the entity this handle addresses. It is the entity-scoped twin of
[`globalEvents.onObjectAction`](https://diceytable.com/docs/scripting-api/events#globaleventsonobjectaction) and fires immediately
after it, with the same three arguments. Like its twin, it fires *in addition to* the semantic delegate for that
action — one `roll` on this entity calls `onAction` and then `onRolled`.

#### Parameters

The handler receives three arguments, transcribed from
`ScriptDelegate<[ObjectHandle, ObservedObjectAction, EventContext]>`:

| Position | Type | Notes |
|---|---|---|
| 1 | [`ObjectHandle`](https://diceytable.com/docs/scripting-api/objecthandle) | The same handle you subscribed on, refilled from the event's state. For `delete` it carries the entity's **last known state**, because the entity is already gone. |
| 2 | [`ObservedObjectAction`](https://diceytable.com/docs/scripting-api/types#observedobjectaction) | The action name — any of the 27 engine actions: the 13 a script may request plus the 14 it can only observe (`lift`, `flick`, `press`, `toss`, `peek`, the three `search*`, the three `reveal-*`, `tip-out`, `empty`, `clear-source`). |
| 3 | [`EventContext`](https://diceytable.com/docs/scripting-api/events#eventcontext) | A peer id, or `"Script"` / `"Host"` / `"You"` / `"System"`. |

**Applies to: every object kind.** The event fires whether or not the runtime does anything with the action for
this kind — see [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies).

#### How, why and when to use it

A card that should not be flipped face-up until it is played, a token that locks itself after three flips, a
piece that logs everything done to it: all of these are rules that belong to one entity, and this is the one
delegate on the handle that sees every kind of interference. The alternative is subscribing to `onRolled`,
`onShuffled` and `onDestroyed` individually, which gives you nothing at all for flips, rotations, locks or
reveals — those have no semantic delegate. Use the semantic delegate when only one action matters; use `onAction`
when "something was done to this piece" is the rule.

#### Example

```ts
// content/scripting-api/examples/objecthandle.onAction.ts

// Object script: react to what happens to this one entity. The action is an
// ObservedObjectAction - the engine's full vocabulary, not the narrower list a
// script may request - so handle the extras in a default branch.

let flips = 0;

refObject.onAction.add((entity, action, context) => {
  switch (action) {
    case "flip":
      flips += 1;
      world.log(`${entity.name ?? entity.id} flipped ${flips}x; faceUp is now ${String(entity.faceUp)}.`);
      if (flips >= 3) {
        world.broadcast(`${entity.name ?? entity.id} has been flipped ${flips} times - locking it.`);
        entity.lock();
      }
      break;
    case "lock":
      world.log(`${context.actor} locked ${entity.id}; further actions are refused until unlock.`);
      break;
    case "delete":
      world.log(`${context.actor} is removing ${entity.id}; onDestroyed fires next.`);
      break;
    default:
      world.log(`${context.actor} performed "${action}" on ${entity.id}.`);
      break;
  }
});

world.log(`Action watcher is attached to ${refObject.id}.`);
```

Flipping the card three times prints three `… flipped Nx; faceUp is now …` lines, then puts
`ace-of-spades has been flipped 3 times - locking it.` into the table chat and immediately logs the resulting
`lock` action.

#### Gotchas

**The action you receive is not the action you can pass back.** The argument is an `ObservedObjectAction`, which
includes the observe-only names no script may request — `lift`, `flick`, `press`, `toss`, the reveals and the rest — so handing it to a
helper that requests an action does not compile. Narrow first, and keep a `default` branch — the engine's list and the
declared union live in two files (`packages/shared/src/tableObjects/intents.ts`,
`packages/shared/src/scripting.ts`), so a `never` check is a promise about a list this script does not own. See
[`ObservedObjectAction`](https://diceytable.com/docs/scripting-api/types#observedobjectaction).

**A mutator called from this handler re-enters it.** `entity.lock()` inside an `onAction` handler produces a
`lock` action, which raises `onAction` again with `actor: "Script"`. The example is safe because the `lock`
branch does not act; guard on `context.actor === "Script"` for anything that could recurse.

**Locking restricts players, not scripts.** A locked entity refuses player actions, and the host — including
every table script — bypasses that gate entirely.

**For `delete` the handle addresses nothing.** Mutators called on it do nothing, and `onDestroyed` fires next.

#### See also

- [`globalEvents.onObjectAction`](https://diceytable.com/docs/scripting-api/events#globaleventsonobjectaction) — the table-wide twin.
- [`ObservedObjectAction`](https://diceytable.com/docs/scripting-api/types#observedobjectaction) — the 27 names this delegate can deliver.
- [`ObjectAction`](https://diceytable.com/docs/scripting-api/types#objectaction) — the 13 a script may request, and the 4 with no method.
- [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) — 27 engine actions, 13 a script may request, 10 a mod may.
- [`ObjectHandle.onDestroyed`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleondestroyed) — what follows a `delete`.
- [Events and delegates](https://diceytable.com/docs/scripting/concepts/events-and-delegates) — the per-action ordering table.

### objecthandle.onRolled

```ts
readonly onRolled: ScriptDelegate<[ObjectHandle, number | null, EventContext]>;
```

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

Fires when this die settles after a roll. `value` is the face value when known.

Fires when the die this handle addresses **comes to rest after tumbling**, carrying the number printed on the
face it settled on. It is the entity-scoped twin of
[`globalEvents.onDiceRolled`](https://diceytable.com/docs/scripting-api/events#globaleventsondicerolled) and fires immediately after
it — both roughly a second after the throw that started the tumble, not at the moment the impulse was applied.

#### Parameters

The handler receives three arguments, transcribed from
`ScriptDelegate<[ObjectHandle, number | null, EventContext]>`:

| Position | Type | Notes |
|---|---|---|
| 1 | [`ObjectHandle`](https://diceytable.com/docs/scripting-api/objecthandle) | The same handle you subscribed on, refilled from the event's state — the pose is the **settled** pose, because the die has already stopped. |
| 2 | `number \| null` | The printed face value, verbatim. `null` means no readable value: the die is cocked, or it is a custom model with no face table. |
| 3 | [`EventContext`](https://diceytable.com/docs/scripting-api/events#eventcontext) | `"Script"`, `"Host"`, `"You"`, or a peer id. A die that tumbled to rest with no `roll` action behind it — a physical shake-throw, or a die knocked hard enough to spin — is attributed to `"Host"`, because no actor is knowable. |

**Applies to: `die`.** The number comes from the die's face table, so nothing else can raise this by settling. A
`card` or `board` given `roll()` is still launched with the same impulse and still raises
`onAction`/`onObjectAction`, but it has no faces to read and never reaches this delegate.

#### How, why and when to use it

One die at the table is *the* die — the initiative die, the timer die — and only its result matters. Subscribing
on its handle means the handler never has to check which die was thrown, which is exactly the check that goes
wrong when a second die is added later. The alternative is `globalEvents.onDiceRolled` plus an id comparison, and
that is the right choice when any die can be thrown and you are scoring all of them. Put the rule on the handle
when the die is a fixture of the game; put it on `globalEvents` when dice come and go.

Because the event now arrives on the settle rather than on the throw, this is also the moment to read the die's
pose: there is no tumble left to wait out and no `world.wait` to guess at.

#### Example

```ts
// content/scripting-api/examples/objecthandle.onRolled.ts

// Object script on a die: keep a running tally of what this one die lands on.
// The event fires when the die comes to REST - roughly a second after the
// throw - and `value` is the number printed on the face it settled on.

let throws = 0;
let total = 0;

refObject.onRolled.add((die, value, context) => {
  throws += 1;
  if (value === null) {
    // Cocked: leaning on a piece or wedged against something, so no face is
    // squarely upright. Nothing readable happened - do not invent a number.
    world.broadcast(`${die.name ?? die.id} landed cocked. Roll it again.`);
    return;
  }
  total += value;
  world.log(`${context.actor} rolled ${value} (throw ${throws}, total ${total}).`);
  if (value === 20) {
    world.broadcast(`${context.actor} rolled a natural 20!`);
  }
});

world.log(`Roll tally attached to ${refObject.id}.`);
```

Rolling the die prints `You rolled 14 (throw 1, total 14).` about a second after the throw lands.

#### Gotchas

**"Rolled" now means the die has stopped, not that the throw was applied.** This changed: the event used to fire
from the `roll` action at the instant of the impulse, and `value` was a literal `null` every time. It now fires
on the settle. A handler that assumed it ran beside `onAction` runs about a second later than it used to, and
`onAction` no longer implies this delegate is about to fire.

**A nudge is not a roll.** A die has to actually spin to raise this. Bumping one across the table updates the
face it is showing and raises nothing here — which is what stops a busy table from scoring a round every time
somebody pushes a die aside.

**A roll nobody asked for still fires.** A die shaken by hand or knocked hard enough to tumble settles into this
event with `context.actor === "Host"`. Do not treat the event as proof that a script or a player called `roll()`.

**`null` means unreadable, not unimplemented.** Two cases produce it: a cocked die (leaning past half the angle
between two of its faces, where the winning face would be a coin toss between neighbours) and a die imported as
a custom model, which carries no face table at all. Both are honest "no answer" results; ask for a re-roll
rather than substituting a number.

**`onAction` with `"roll"` fires first on this same handle, and much earlier.** The full order for one roll is
`globalEvents.onObjectAction` and `ObjectHandle.onAction` at the throw, then — once the die stops —
`globalEvents.onDiceRolled` and this.

**Physics has to be running.** A throw with the simulation frozen goes nowhere, so nothing ever settles and this
never fires. Edit Mode switches from Frozen to Live when you press ▶ Play Scripts.

#### See also

- [`globalEvents.onDiceRolled`](https://diceytable.com/docs/scripting-api/events#globaleventsondicerolled) — the table-wide twin.
- [`ObjectHandle.roll`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleroll) — the call that raises this from a script.
- [`ObjectHandle.refresh`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlerefresh) — reading the settled pose back.
- [`tableObjectDefinitionSchema.faceValue`](https://diceytable.com/docs/mods/reference/object-state#facevalue) — the same number as it rides in the snapshot.
- [Events and delegates](https://diceytable.com/docs/scripting/concepts/events-and-delegates) — the per-action ordering table.

### objecthandle.onCardDrawn

```ts
readonly onCardDrawn: ScriptDelegate<[ObjectHandle, EventContext]>;
```

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

Fires on a CONTAINER when a card is drawn from it: the handle argument is
the newly created card, and `context.containerId` is this container's id.

Fires on a **container** when a card is drawn from it. It is the entity-scoped twin of
[`globalEvents.onCardDrawn`](https://diceytable.com/docs/scripting-api/events#globaleventsoncarddrawn), and it is the one entity-scoped
delegate whose subject is not the event's entity: the `cardDrawn` event names the newly created *card*, and the
sandbox deliberately routes the delegate to the deck or bag named by `context.containerId`
(`apps/web/src/scripting/sandbox/tableScriptSandbox.html`, `routeLifecycleEvent`) — because `deck.onCardDrawn`
is what an author means.

#### Parameters

The handler receives two arguments, transcribed from `ScriptDelegate<[ObjectHandle, EventContext]>`:

| Position | Type | Notes |
|---|---|---|
| 1 | [`ObjectHandle`](https://diceytable.com/docs/scripting-api/objecthandle) | The **drawn card**, not the container. The container is the handle you subscribed on. |
| 2 | [`EventContext`](https://diceytable.com/docs/scripting-api/events#eventcontext) | `context.containerId` is this container's id — the value the routing was done by — and `context.actor` is whoever drew. |

**Applies to: `deck` and `bag`.** Subscribing on any other kind is legal and the delegate never fires, because
nothing else is drawn from.

#### How, why and when to use it

You are writing an object script on a deck and want to know when a card comes off *this* deck — a reshuffle after
five draws, a "the deck is running low" warning, a per-deck draw log. This delegate is that, with no filtering:
the routing has already narrowed the event to your container. The alternative is
`globalEvents.onCardDrawn` plus a `context.containerId` comparison, which is the right shape when one handler has
to serve several decks or when the script is a scene script with no `refObject`. Use the entity-scoped delegate
in an object script; use the table-wide one when you are watching more than one container.

`refObject.onAction` filtered to `"draw"` is a third option and answers a different question: it fires for a draw
that produced nothing, so it counts *attempts* rather than cards.

#### Example

```ts
// content/scripting-api/examples/objecthandle.onCardDrawn.ts

// Object script on a deck: the entity-scoped delegate is routed to the
// CONTAINER, so it fires for every card drawn off this deck and for no other.
// The handle argument is the new card; refObject is still the deck.

let drawn = 0;

refObject.onCardDrawn.add((card, context) => {
  drawn += 1;
  world.log(`${context.actor} drew ${card.name ?? card.id} from ${refObject.id} (${drawn} so far).`);

  if (drawn >= 5) {
    world.broadcast(`Five cards are out of ${refObject.name ?? refObject.id} - shuffling the rest.`);
    refObject.shuffle();
    drawn = 0;
  }
});

refObject.onShuffled.add(() => {
  world.log(`${refObject.id} was shuffled; the draw counter stays at ${drawn}.`);
});

world.log(`Draw counter is attached to deck ${refObject.id}.`);
```

Each draw prints `a1b2c3d4 drew ace-of-spades from obj-2 (1 so far).`; the fifth puts a line in the table chat
and shuffles what is left.

#### Gotchas

**The sandbox has to know the container's handle for this to fire.** Routing looks the container up in the
sandbox's handle cache, so a container no script has ever taken a handle to receives nothing — which is harmless,
because nothing can have subscribed to it either. In an object script `refObject` is that handle, so this is only
a consideration if you build handles dynamically.

**The argument order surprises people.** The handle you *get* is the card; the handle you *subscribed on* is the
container. Reach for `refObject` when you mean the deck.

**A draw can consume the deck.** Drawing the last card removes the container, and drawing it down to one card
converts the remainder into a plain card and removes the deck entity. Either way `onDestroyed` fires on this
handle after the draw, and the sandbox then drops the handle.

**Nothing fires for a card produced by a split.** A split is not a draw: it raises `onObjectCreated` and
`onObjectAction`, and no `cardDrawn`. If your game splits decks, count both.

#### See also

- [`globalEvents.onCardDrawn`](https://diceytable.com/docs/scripting-api/events#globaleventsoncarddrawn) — the table-wide twin, for watching several containers.
- [`EventContext.containerId`](https://diceytable.com/docs/scripting-api/events#eventcontextcontainerid) — the field this delegate is routed by.
- [`ObjectHandle.onAction`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleonaction) — the deck-scoped alternative, counting `"draw"` attempts.
- [`ObjectHandle.draw`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandledraw) — asking the container for a card.
- [Events and delegates](https://diceytable.com/docs/scripting/concepts/events-and-delegates) — the per-action ordering table.

### objecthandle.onShuffled

```ts
readonly onShuffled: ScriptDelegate<[ObjectHandle, EventContext]>;
```

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

Fires when a `shuffle` action is applied to the entity this handle addresses. It is the entity-scoped twin of
[`globalEvents.onContainerShuffled`](https://diceytable.com/docs/scripting-api/events#globaleventsoncontainershuffled) and fires
immediately after it, once the contents have already been reordered with a host-private seed.

#### Parameters

The handler receives two arguments, transcribed from `ScriptDelegate<[ObjectHandle, EventContext]>`:

| Position | Type | Notes |
|---|---|---|
| 1 | [`ObjectHandle`](https://diceytable.com/docs/scripting-api/objecthandle) | The same handle you subscribed on, refilled from the event's state. |
| 2 | [`EventContext`](https://diceytable.com/docs/scripting-api/events#eventcontext) | `"Script"` for a `shuffle()` call, `"You"` for a menu click or a shake gesture at the host machine, or the peer id of the player who shuffled. |

**Applies to: `deck`, and nothing else.** Only a `deck` has its card entries reshuffled, and a deck with fewer
than two cards is left alone (the delegate still fires — there was nothing to reorder, but the shuffle happened).
**A `shuffle` addressed to any other kind is refused before anything runs, so this delegate never fires for one.**
Attaching it to a `bag` is dead code: a bag draws at random and has no order to shuffle.

#### How, why and when to use it

The draw pile in your game has a rule of its own — reshuffle the discard back in, announce the count, refuse to
be shuffled twice in a turn. Attaching an object script to that deck means the handler is the rule and there is
no id to compare. The alternative, `globalEvents.onContainerShuffled` with a filter, is what you want when
several decks share one rule or when decks are created during play. Put it on the handle when the deck is a
fixture; put it on `globalEvents` when containers come and go.

#### Example

```ts
// content/scripting-api/examples/objecthandle.onShuffled.ts

// Object script on a deck: react when this container is reordered. Attaching
// to the deck means no id comparison - the delegate only fires for it.

let shuffles = 0;

refObject.onShuffled.add((deck, context) => {
  shuffles += 1;
  world.broadcast(`${deck.name ?? deck.kind} shuffled by ${context.actor} (${shuffles}x).`);
  void recordShuffle();
});

async function recordShuffle(): Promise<void> {
  await world.setSavedData(String(shuffles), "shuffles");
  const stored = await world.getSavedData("shuffles");
  world.log(`Shuffle count stored for this table: ${stored ?? "0"}.`);
}

globalEvents.onChatMessage.add((message) => {
  if (message.text.trim() === "!shuffle") {
    refObject.shuffle();
    world.log(`${message.displayName ?? message.peerId} asked for a shuffle.`);
  }
});

world.log(`Shuffle watcher is attached to ${refObject.id}.`);
```

Typing `!shuffle` puts `draw-pile shuffled by Script (1x).` into the table chat and prints
`Shuffle count stored for this table: 1.` to the script console.

#### Gotchas

**Calling `shuffle()` from inside the handler recurses.** The example's chat handler is safe because it is a
different delegate; a `refObject.shuffle()` inside `onShuffled` would raise the event again with
`actor: "Script"` and never stop. Guard on the actor if you need to reshuffle from here.

**The resulting order is host-private and unreadable from a script.** There is no method that lists a
container's contents. Track what you need from
[`globalEvents.onCardDrawn`](https://diceytable.com/docs/scripting-api/events#globaleventsoncarddrawn) instead.

**A shake gesture counts.** Shaking a deck at the table applies the same action, so the event fires for gestures
as well as menu clicks and script calls.

**`onAction` with `"shuffle"` fires first on this same handle**, after the table-wide pair.

#### See also

- [`globalEvents.onContainerShuffled`](https://diceytable.com/docs/scripting-api/events#globaleventsoncontainershuffled) — the table-wide twin.
- [`ObjectHandle.shuffle`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleshuffle) — the call that raises this from a script.
- [`world.setSavedData`](https://diceytable.com/docs/scripting-api/world#worldsetsaveddata) — persisting a count across a save.
- [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) — what `shuffle` does on each kind.
- [Events and delegates](https://diceytable.com/docs/scripting/concepts/events-and-delegates) — the per-action ordering table.

### objecthandle.onMenuItem

```ts
readonly onMenuItem: ScriptDelegate<[ObjectHandle, string, EventContext]>;
```

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

A player clicked one of this script's menu entries ON THIS ENTITY. The string is your own
item id. The item still has to `match` this entity to be offered at all.

The object-scoped twin of
[`globalEvents.onObjectMenuItem`](https://diceytable.com/docs/scripting-api/events#globaleventsonobjectmenuitem): fires only when the
clicked entry was on **this** entity. In an object script that is almost always what you want — `refObject` is
the piece the script is attached to, so there is nothing left to filter.

#### Parameters

| Parameter | Type | Notes |
|---|---|---|
| `object` | [`ObjectHandle`](https://diceytable.com/docs/scripting-api/objecthandle) | This entity. |
| `itemId` | `string` | Your id, as registered. |
| `context` | [`EventContext`](https://diceytable.com/docs/scripting-api/events#eventcontext) | `context.actor` is the peer who clicked. |

#### How, why and when to use it

Use it in an **object script** when the verb belongs to one particular piece. Use the global delegate in a
**scene script** when one handler serves a whole class of entities — a rule about every pawn is one handler on
the scene, not sixteen identical object scripts.

#### Example

```ts
// content/scripting-api/examples/objecthandle.onMenuItem.ts

// Object script on a single entity: the menu entry is registered globally, but
// narrowed to THIS entity, and the callback is narrowed to it as well.
//
// `match: { objectIds: [refObject.id] }` is the narrowest filter there is - one
// entity, by id. Registration is always a `world` call; only the CALLBACK is
// object-scoped.
world.addObjectMenuItem({
  id: "rally",
  label: "Rally to this banner",
  match: { objectIds: [refObject.id] }
});

// Fires only when the clicked entry was on this entity, so there is nothing left
// to filter - in an object script that is almost always what you want.
refObject.onMenuItem.add((object, itemId, context) => {
  if (itemId !== "rally") {
    return;
  }
  world.broadcast(`${context.actor} rallies to ${object.name ?? "the banner"}.`);
});
```

See [`world.addObjectMenuItem`](https://diceytable.com/docs/scripting-api/world#worldaddobjectmenuitem) for the
registration side of the same pair.

#### Gotchas

**Registering is still global.** There is no per-entity `addObjectMenuItem`: you register the entry on `world`
with a `match` that selects this entity (`match: { objectIds: [refObject.id] }` is the narrowest form), and this
delegate then narrows the *callback* to it.

**The entry still has to `match` this entity** to be offered at all. This delegate cannot surface an item whose
filter excludes the entity it is attached to — if nothing appears in the menu, the filter is where to look, not
the handler.

#### See also

- [`world.addObjectMenuItem`](https://diceytable.com/docs/scripting-api/world#worldaddobjectmenuitem) — register the entry.
- [`globalEvents.onObjectMenuItem`](https://diceytable.com/docs/scripting-api/events#globaleventsonobjectmenuitem) — every click, for every matching entity.

### objecthandle.onClicked

```ts
readonly onClicked: ScriptDelegate<[ObjectHandle, ObjectClickContext]>;
```

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

A player clicked THIS entity: pressed and released it without dragging (a mouse click, a
touch tap, a VR trigger tap). Fires for locked entities too. See `globalEvents.onObjectClicked`.

The entity-scoped twin of
[`globalEvents.onObjectClicked`](https://diceytable.com/docs/scripting-api/events#globaleventsonobjectclicked): fires only when a player
clicked **this** entity. In an object script, `refObject.onClicked` turns the entity the script is attached to
into something a player can press.

#### Parameters

| Parameter | Type | Notes |
|---|---|---|
| `object` | [`ObjectHandle`](https://diceytable.com/docs/scripting-api/objecthandle) | This entity. |
| `context` | [`ObjectClickContext`](https://diceytable.com/docs/scripting-api/types#objectclickcontext) | `context.seat` is the clicker's seat, or `null`. |

#### How, why and when to use it

Use it in an **object script** when the click belongs to one particular entity: a bell that ends the turn, a
deck that deals to whoever clicks it, a scoring track. Use the global delegate in a **scene script** when one
rule serves many entities, such as every card a seat could play.

#### Example

```ts
// content/scripting-api/examples/objecthandle.onClicked.ts

// Object script on a locked bell: clicking it ends the clicker's turn. Clicks
// reach locked entities too, so the bell stays put and still works as a button.
refObject.onClicked.add((bell, context) => {
  if (context.seat === null) {
    // A spectator, or a host who has not taken a seat.
    return;
  }
  const seats = world.getPlayers()
    .map((player) => player.seat)
    .filter((seat): seat is string => seat !== null);
  if (!world.getTurn().seats.includes(context.seat) || seats.length === 0) {
    world.log(`${context.seat} rang ${bell.name ?? "the bell"} out of turn.`);
    return;
  }
  const next = seats[(seats.indexOf(context.seat) + 1) % seats.length] ?? seats[0];
  world.setHighlight(bell, "active", { seconds: 1.5 });
  world.broadcast(`${context.seat} ends their turn.`);
  world.setTurn(next ?? null);
});
```

#### Gotchas

**Locked entities are clickable.** Lock the entity so it cannot be dragged away, and it still raises clicks.

**Every rule of the global event applies.** It fires on the host, a click passes regardless of turn or owner,
each player is limited to 8 clicks a second, and clicks do not fire in the Edit Mode viewport. See
[`globalEvents.onObjectClicked`](https://diceytable.com/docs/scripting-api/events#globaleventsonobjectclicked).

#### See also

- [`globalEvents.onObjectClicked`](https://diceytable.com/docs/scripting-api/events#globaleventsonobjectclicked) — every click, on any entity.
- [`ObjectClickContext`](https://diceytable.com/docs/scripting-api/types#objectclickcontext) — who clicked.
- [Highlights and clicks](https://diceytable.com/docs/scripting/concepts/highlights-and-clicks) — the guide.

### objecthandle.refresh

```ts
refresh(): Promise<ObjectData | null>;
```

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

Refresh and return this object's latest state (null if it no longer exists).

Asks the host for this entity's current state, updates the handle's own properties from the answer, and resolves
with a plain copy of them. This is how a handle stops being stale — everything on `ObjectData` is a cached value
until something refreshes it.

#### Returns

`Promise<ObjectData | null>`.

`null` means **the host's current snapshot has no object with this handle's id.** The entity was destroyed, or the
`world.spawnObject` that produced this handle was rejected by the host. A `null` answer leaves the handle's cached
properties exactly as they were — they are the last state you saw, not a cleared record — so do not read
`handle.position` after a `null` refresh and expect anything meaningful.

A non-`null` answer is a **plain data copy**, not the handle. It has the twelve `ObjectData` fields (plus the
kind-specific ones the sandbox fills on every handle) and nothing else: no methods, no event delegates. The handle you called it on is updated in place at the same time, so
`handle.faceUp` and `result.faceUp` agree immediately afterwards.

#### How, why and when to use it

You called `handle.flip()` and want to know which way the card ended up. The mutators return `void` immediately —
they post an intent and do not wait — so the handle you are holding still reports the pre-flip state.
`refresh()` is the read that closes that loop, and because the sandbox delivers the intent and the read to the
host in order, a `refresh()` issued after a mutator always sees that mutator applied. The alternative is
`world.getObjectById(handle.id)`, which costs the same round trip and hands back the very same handle — so it
tells you nothing extra and reads worse. Use `refresh()` after any mutation whose result you need, and after any
`await`, because the table moved while you were suspended.

#### Example

```ts
// content/scripting-api/examples/objecthandle.refresh.ts

// Scene script: turn every card face down, then confirm each one changed.
// Mutators return immediately, so refresh() is how you read the result back.

async function faceEverythingDown(): Promise<void> {
  const cards = await world.getAllObjects({ kind: "card" });
  if (cards.length === 0) {
    world.log("No cards on the table.");
    return;
  }

  for (const card of cards) {
    if (card.faceUp === false) {
      continue;
    }

    card.flip();
    const after = await card.refresh();
    if (after === null) {
      world.log(`${card.id} is gone - refresh found no such entity.`);
      continue;
    }
    world.log(`${after.id} faceUp is now ${String(after.faceUp)}.`);
  }
}

globalEvents.onChatMessage.add((message) => {
  if (message.text.trim() === "!facedown") {
    void faceEverythingDown();
  }
});

void faceEverythingDown();
```

With two face-up cards on the table the script console prints two lines like
`script-1f2e3d4c5b6a7089 faceUp is now false.`

#### Gotchas

**Resolves after a round-trip to the host, so the value is the host's state at the moment it answered — not
necessarily still true when your handler continues.** A player can pick the entity up on the next line.

**One refresh pulls the whole snapshot across the sandbox boundary.** Refreshing fifty handles in a loop is fifty
serializations of the entire table. When you need many, call `world.getAllObjects` once — it refreshes every
handle it returns in a single round trip.

**A `null` does not invalidate the handle.** The JavaScript object stays usable and its cached fields keep their
last values, so a stale `handle.id` will keep addressing a deleted entity. Drop your reference when a refresh
returns `null`.

#### See also

- [`ObjectData`](https://diceytable.com/docs/scripting-api/objecthandle#objectdata) — the twelve fields a refresh updates.
- [`world.getAllObjects`](https://diceytable.com/docs/scripting-api/world#worldgetallobjects) — refreshing many handles at once.
- [`world.getObjectById`](https://diceytable.com/docs/scripting-api/world#worldgetobjectbyid) — the same round trip when you have only
  an id.
- [Async and snapshots](https://diceytable.com/docs/scripting/concepts/async-and-snapshots) — why a handle is a cache and not a live
  view.

### objecthandle.setPosition

```ts
setPosition(position: Vec3): void;
```

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

Teleports this entity to an absolute point in table space. The sandbox posts a `transform` intent carrying the
position; the host validates it, moves the rigidbody there and wakes it.

#### Parameters

| Name | Type | Required | Notes |
|---|---|---|---|
| `position` | `Vec3` | yes | `[x, y, z]` in **feet**, absolute table-space coordinates — not an offset from where the entity is now. `[0, 1, 0]` is one foot above the table origin. Individual entries that are not finite numbers become `0`, so `[NaN, 1, 0]` puts the entity on the center line. A value that is not an array of at least three entries is dropped **before any intent is sent**: nothing moves, nothing is logged, and the call still returns normally. |

**Applicability:** every object kind. Nothing about the move changes with `kind`.

#### How, why and when to use it

A card has just been drawn and you want it in the middle of the table rather than beside the deck the host
dropped it next to. `setPosition` is the only way a script can place an entity at a coordinate it chose. The
alternative is to spawn things where you want them in the first place — `world.spawnObject` takes a `position`,
and for anything your script creates that is the better answer, because it costs one intent instead of two and
never shows the entity in the wrong place first. Use `setPosition` when the entity already exists and something
that just happened decided where it belongs: a drawn card, a turn marker, a piece returning to its start square.

#### Example

```ts
// content/scripting-api/examples/objecthandle.setPosition.ts

// Scene script: line the table's dice up in a row on demand. Coordinates are
// absolute table-space FEET, and setPosition is a teleport, not a nudge.

const ROW_Z = -2;
const SPACING = 1.25;
const REST_HEIGHT = 0.6;

async function lineUpDice(): Promise<void> {
  const dice = await world.getAllObjects({ kind: "die" });
  if (dice.length === 0) {
    world.log("No dice on the table to line up.");
    return;
  }

  const firstX = -((dice.length - 1) * SPACING) / 2;
  dice.forEach((die, index) => {
    die.setPosition([firstX + index * SPACING, REST_HEIGHT, ROW_Z]);
  });
  world.log(`Lined up ${dice.length} dice along z = ${ROW_Z} ft.`);

  // The move is not readable on the handle until the host answers, so ask.
  const settled = await dice[0].refresh();
  world.log(settled === null
    ? "The first die vanished before it could be read back."
    : `First die is now at [${settled.position.join(", ")}] ft.`);
}

globalEvents.onChatMessage.add((message) => {
  if (message.text.trim() === "!lineup") {
    void lineUpDice();
  }
});

void lineUpDice();
```

With three dice on the table, the script console prints `Lined up 3 dice along z = -2 ft.` then
`First die is now at [-1.25, 0.6, -2] ft.`

#### Gotchas

**This returns immediately. The change is not visible in `ObjectData` — including this handle's own properties —
until the host has applied it. Call `await handle.refresh()` if you need to read the result**, and remember other
players only see the move on the host's next snapshot.

**It is a teleport, not a constraint.** The host moves the rigidbody and then re-activates it, so physics takes
over from the new pose: a dynamic entity placed above the surface falls to it, and one placed inside another is
pushed out. Give the height you want it to come to rest at, or `lock()` it first.

**A malformed position is dropped in silence.** The sandbox never sends a `transform` intent it cannot build a
vector from, and it does not report that it declined. If a position is coming from data rather than a literal,
validate it yourself — a missing third entry looks exactly like a call that did nothing.

**A locked entity still moves.** The per-kind and locked-state gate (`packages/shared/src/tableObjects.ts`,
`isObjectActionAllowedForTarget`) runs on intents arriving from a player or spectator. A script's intents are
raised on the host and do not pass through it, so `lock()` protects an entity from players, not from your script.

#### See also

- [`ObjectHandle.setRotation`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesetrotation) — the other half of a
  transform.
- [`ObjectData.position`](https://diceytable.com/docs/scripting-api/objecthandle#objectdataposition) — reading the current point.
- [`world.spawnObject`](https://diceytable.com/docs/scripting-api/world#worldspawnobject) — placing an entity when you create it.
- [Moving, rotating and scaling entities](https://diceytable.com/docs/editor/working/transform-and-gizmos) — the same coordinates in
  Edit Mode.
- [Host authority](https://diceytable.com/docs/scripting/concepts/host-authority) — why a move is a request that the host applies.

### objecthandle.setRotation

```ts
setRotation(rotation: Vec3): void;
```

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

Turns this entity to an absolute orientation. The sandbox posts a `transform` intent carrying the Euler angles;
the host keeps the entity where it is and re-seats it at the new rotation.

#### Parameters

| Name | Type | Required | Notes |
|---|---|---|---|
| `rotation` | `Vec3` | yes | `[x, y, z]` Euler angles in **degrees**, absolute — not a delta from the current orientation. `[0, 90, 0]` is a quarter turn about the vertical axis from the table's zero, whatever the entity was doing before. Entries that are not finite numbers become `0`. A value that is not an array of at least three entries is dropped **before any intent is sent**: nothing turns and nothing is logged. |

**Applicability:** every object kind.

#### How, why and when to use it

A board has been dragged around all game and is sitting at 37°, and you want it square to the table again.
`setRotation` sets the angle you name. The alternative is `rotate()`, which most authors try first because it is
shorter — but it applies a fixed 90° step to whatever the entity is currently at, so from 37° it takes you to
127°, not to 90°. Use `setRotation` when you know the orientation you want; use `rotate()` when you want the same
quarter-turn a player would get from the object menu.

#### Example

```ts
// content/scripting-api/examples/objecthandle.setRotation.ts

// Scene script: square every board up to the table axes. Rotation is absolute
// Euler degrees, so this snaps to an angle rather than stepping by one.

function nearestRightAngle(degrees: number): number {
  const snapped = Math.round(degrees / 90) * 90;
  return ((snapped % 360) + 360) % 360;
}

async function squareUpBoards(): Promise<void> {
  const boards = await world.getAllObjects({ kind: "board" });
  if (boards.length === 0) {
    world.log("No boards on the table.");
    return;
  }

  for (const board of boards) {
    const yaw = nearestRightAngle(board.rotation[1]);
    board.setRotation([0, yaw, 0]);

    const after = await board.refresh();
    world.log(after === null
      ? `${board.id} vanished before it could be read back.`
      : `${after.id} squared up to yaw ${nearestRightAngle(after.rotation[1])} degrees.`);
  }
}

globalEvents.onChatMessage.add((message) => {
  if (message.text.trim() === "!square") {
    void squareUpBoards();
  }
});

void squareUpBoards();
```

With one board sitting at 37° the script console prints
`script-1f2e3d4c5b6a7089 squared up to yaw 0 degrees.`

#### Gotchas

**This returns immediately. The change is not visible in `ObjectData` — including this handle's own properties —
until the host has applied it. Call `await handle.refresh()` if you need to read the result**, and remember other
players only see the turn on the host's next snapshot.

**Rotating a card 180° does not flip it.** `faceUp` is a separate flag on the entity, and the transform path never
touches it: a card turned to `[180, 0, 0]` faces the other way and still reports the face state it had. Only
`flip()` changes `faceUp`, and it does both at once. Never infer face state from `rotation`.

**A malformed rotation is dropped in silence,** exactly like `setPosition`. Validate data-driven angles yourself.

**Angles are not normalized.** `[0, 450, 0]` is accepted and the host applies it; the entity ends up where 90°
would have put it, but what you read back afterwards is whatever the engine reports for its world orientation, not
the number you sent. Normalize before you compare.

#### See also

- [`ObjectHandle.rotate`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlerotate) — the fixed 90° step.
- [`ObjectHandle.flip`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleflip) — the one that changes `faceUp`.
- [`ObjectData.rotation`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatarotation) — reading the current angles.
- [Moving, rotating and scaling entities](https://diceytable.com/docs/editor/working/transform-and-gizmos) — the same angles in Edit
  Mode.

### objecthandle.flip

```ts
flip(): void;
```

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

Turns this entity over. The sandbox posts an `object-action` intent with the action `flip`; the host toggles the
entity's face state and rotates it 180° about its own X axis.

#### How, why and when to use it

A round has ended and every card in play should be face up so scores can be read. `flip()` is the action that
turns one over, and it is a *toggle*, so a scoring pass checks `faceUp` first and only calls it on the cards that
need it. The alternative is `setRotation`, which will physically turn a card over and looks right — and is wrong,
because it does not change `faceUp`, so the hidden-information system still treats the card as face down and
peers may not be shown its face at all. Use `flip()` whenever the *face* matters; use `setRotation` only for
orientation that has nothing to do with which side is showing.

#### Example

```ts
// content/scripting-api/examples/objecthandle.flip.ts

// Scene script: turn every card face up at the end of a round. flip is a
// toggle, so read faceUp first rather than calling it blindly.

async function revealAllCards(): Promise<void> {
  const cards = await world.getAllObjects({ kind: "card" });
  if (cards.length === 0) {
    world.log("No cards in play.");
    return;
  }

  let flipped = 0;
  for (const card of cards) {
    if (card.faceUp === true) {
      continue;
    }
    card.flip();
    flipped += 1;
  }

  world.log(`Flipped ${flipped} of ${cards.length} cards.`);
  if (flipped > 0) {
    world.broadcast(`${flipped} card(s) turned face up.`);
  }
}

globalEvents.onTurnEnded.add(() => {
  void revealAllCards();
});

globalEvents.onChatMessage.add((message) => {
  if (message.text.trim() === "!reveal") {
    void revealAllCards();
  }
});
```

With four cards down and one already up, the script console prints `Flipped 4 of 5 cards.` and every player's
chat shows `4 card(s) turned face up.`

#### Gotchas

**This returns immediately. The change is not visible in `ObjectData` — including this handle's own properties —
until the host has applied it. Call `await handle.refresh()` if you need to read the result.**

**Applies to: every object kind, and only a `token` is checked.** On a `card` it turns the card over. On a `deck`
it turns the whole stack over *and* flips every card entry inside it, so the deck's order is preserved but every
entry's face state inverts. On a `token` it turns the piece over in place — collider centre and resting height
kept — and leaves `faceUp` exactly as it was, because a token has no hidden face; and on a token that may **not**
flip (a meeple-shaped piece, or one marked `flippable: false`) the host refuses it outright, so the call does
nothing at all and `onAction` does not fire. See [Flipping a token](https://diceytable.com/docs/mods/reference/object-kinds#flipping-a-token). On a `die`, `board`, `bag`, `custom` or
`card-holder` the host still toggles the face flag and rotates the entity 180° — you get an upside-down die
reporting `faceUp: false`, which is almost never what you meant. Read `handle.kind` before flipping anything your
script did not spawn.

**Flipping is not revealing.** `flip()` changes which way the entity is facing; it does not touch the reveal state
the hidden-information system uses to decide which peers may see a card's face. Scripts cannot request the
`reveal-*` actions at all — see [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) for why that boundary
exists and what to model instead.

**Two flips in the same handler cancel out.** Each call is a separate intent and the host applies both, so a
double toggle is a visible no-op with two snapshots' cost.

#### See also

- [`ObjectData.faceUp`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatafaceup) — the flag this toggles.
- [`ObjectHandle.setRotation`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesetrotation) — orientation without
  face state.
- [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) — the 27 engine actions, the 13 a script may request,
  and why `reveal-*` is not one of them.
- [Object kinds](https://diceytable.com/docs/mods/reference/object-kinds) — what each kind is and which ones have a face.

### objecthandle.rotate

```ts
rotate(): void;
```

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

Turns this entity a quarter turn. The sandbox posts an `object-action` intent with the action `rotate`; the host
rotates the entity 90° about its own vertical axis. It is a step, not an angle — there is nothing to pass.

#### How, why and when to use it

A tile has to face the next player each time the turn moves, and the table is laid out so that "the next player"
is always 90° round. `rotate()` is exactly the step a player gets from the object menu, so a script using it
produces motion that looks like something a person did. The alternative is `setRotation`, which is the right tool
the moment you know the absolute angle you want — `rotate()` composes with whatever the entity is currently at,
so on an entity a player has nudged you end up 90° from a random starting point rather than at a clean multiple.
Use `rotate()` for repeated quarter turns from wherever the entity is; use `setRotation` to snap to an angle.

#### Example

```ts
// content/scripting-api/examples/objecthandle.rotate.ts

// Scene script: give every token a quarter turn when a round starts. rotate is
// a fixed 90-degree step; setRotation is the one that takes an angle.

async function quarterTurnTokens(): Promise<void> {
  const tokens = await world.getAllObjects({ kind: "token" });
  if (tokens.length === 0) {
    world.log("No tokens on the table.");
    return;
  }

  const yawBefore = tokens[0].rotation[1];
  for (const token of tokens) {
    token.rotate();
  }

  const after = await tokens[0].refresh();
  if (after === null) {
    world.log(`Turned ${tokens.length} token(s); the first one has left the table.`);
    return;
  }
  world.log(`Turned ${tokens.length} token(s). First yaw ${yawBefore} -> ${after.rotation[1]} degrees.`);
}

globalEvents.onTurnStarted.add(() => {
  void quarterTurnTokens();
});

globalEvents.onChatMessage.add((message) => {
  if (message.text.trim() === "!turn") {
    void quarterTurnTokens();
  }
});
```

With two tokens on the table the script console prints
`Turned 2 token(s). First yaw 0 -> 90 degrees.`

#### Gotchas

**This returns immediately. The change is not visible in `ObjectData` — including this handle's own properties —
until the host has applied it. Call `await handle.refresh()` if you need to read the result.**

**Applies to: every object kind.** The host turns whatever you address, including a board or a deck. Nothing about
the step varies by kind, and nothing about it is refused.

**The step is about the entity's own axis, not the table's.** On an entity that is already tilted, four calls do
not necessarily return it to where it started in world terms. When you need a guaranteed orientation, name it with
`setRotation`.

**It does not change the face.** A card rotated four times is back where it started and has never changed
`faceUp`. Use `flip()` for that.

#### See also

- [`ObjectHandle.setRotation`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesetrotation) — the absolute-angle
  version.
- [`ObjectHandle.flip`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleflip) — the turn that changes `faceUp`.
- [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) — what the host does for each of the 27 engine actions.
- [Moving, rotating and scaling entities](https://diceytable.com/docs/editor/working/transform-and-gizmos) — the same rotation by hand.

### objecthandle.lock

```ts
lock(): void;
```

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

Pins this entity in place. The sandbox posts an `object-action` intent with the action `lock`; the host marks the
entity locked and switches its rigidbody to static, so physics stops moving it and players stop being able to.

#### How, why and when to use it

The board is the thing everything else sits on, and a player who grabs the wrong pixel drags the whole play area
out from under the pieces. Locking it at load removes that failure mode for the rest of the session. The
alternative most authors reach for is authoring the board with a static rigidbody in Edit Mode, which stops
physics pushing it but leaves it draggable — locking is what actually stops the hand. Lock anything a player
should not be able to move: boards, backgrounds, seat markers, a deck that must stay where you put it. Leave
everything a player is meant to pick up unlocked, because a locked entity refuses almost everything they can ask
of it.

#### Example

```ts
// content/scripting-api/examples/objecthandle.lock.ts

// Scene script: pin the boards down at load and keep new ones pinned, so a
// stray drag cannot slide the play area out from under everything else.

async function lockBoards(): Promise<void> {
  const boards = await world.getAllObjects({ kind: "board" });
  if (boards.length === 0) {
    world.log("No boards to lock.");
    return;
  }

  let locked = 0;
  for (const board of boards) {
    if (board.locked) {
      continue;
    }
    board.lock();
    locked += 1;
  }
  world.log(`Locked ${locked} of ${boards.length} board(s).`);

  const first = await boards[0].refresh();
  if (first !== null) {
    world.log(`${first.id} locked = ${String(first.locked)}.`);
  }
}

globalEvents.onObjectCreated.add((handle) => {
  if (handle.kind === "board" && !handle.locked) {
    handle.lock();
    world.log(`Locked newly created board ${handle.id}.`);
  }
});

void lockBoards();
```

With one unlocked board the script console prints `Locked 1 of 1 board(s).` then
`script-1f2e3d4c5b6a7089 locked = true.`

#### Gotchas

**This returns immediately. The change is not visible in `ObjectData` — including this handle's own properties —
until the host has applied it. Call `await handle.refresh()` if you need to read the result.**

**Applies to: every object kind.** Any entity can be locked, and locking one that is already locked is a no-op
that still costs an intent and a snapshot — check `handle.locked` first, as the example does.

**A lock stops players, not scripts.** The gate that refuses actions on a locked entity
(`packages/shared/src/tableObjects.ts`, `isObjectActionAllowedForTarget`) runs on intents arriving from a player
or spectator. Intents raised on the host — your script, a mod running on the host, the host's own UI — do not pass
through it. Your script can still flip, move and delete an entity it just locked.

**Locking changes the physics body, not only a flag.** The rigidbody becomes static, so the entity stops falling,
stops being pushed and stops pushing back. `unlock()` restores the body type it was authored with, which is not
necessarily dynamic.

#### See also

- [`ObjectHandle.unlock`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleunlock) — the only action a locked entity
  accepts from a player.
- [`ObjectData.locked`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatalocked) — reading the current state.
- [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) — the per-kind gate and the two rules above it.
- [RIGIDBODY](https://diceytable.com/docs/editor/inspector/rigidbody) — the body type a lock temporarily replaces.

### objecthandle.unlock

```ts
unlock(): void;
```

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

Releases this entity. The sandbox posts an `object-action` intent with the action `unlock`; the host clears the
locked flag and restores the rigidbody type the entity was authored with, so physics and players can move it
again.

#### How, why and when to use it

The game is over and every piece your script pinned down during play should go back to being draggable, because
the next thing anybody wants to do is push the board around and put things away. `unlock()` is the release.
The alternative is to leave the table locked and let players unlock pieces one at a time from the object menu —
they can, because `unlock` is the one action a locked entity still accepts from a player — but that is a chore you
can spare them. Unlock in bulk at the end of a game or a phase; leave individual unlocking to players when the
lock is theirs rather than yours.

#### Example

```ts
// content/scripting-api/examples/objecthandle.unlock.ts

// Scene script: release every locked entity when the game is over, so players
// can tidy up by hand. unlock is the one action a locked entity still accepts.

async function unlockEverything(): Promise<void> {
  const everything = await world.getAllObjects();
  const locked = everything.filter((handle) => handle.locked);

  if (locked.length === 0) {
    world.log("Nothing on the table is locked.");
    return;
  }

  for (const handle of locked) {
    handle.unlock();
    world.log(`Unlocked ${handle.kind} ${handle.id}.`);
  }
  world.broadcast(`${locked.length} piece(s) unlocked - the table is free to rearrange.`);

  const check = await locked[0].refresh();
  if (check !== null) {
    world.log(`${check.id} locked = ${String(check.locked)}.`);
  }
}

globalEvents.onChatMessage.add((message) => {
  if (message.text.trim() === "!unlockall") {
    void unlockEverything();
  }
});
```

With two locked entities the script console prints one `Unlocked …` line each, then
`script-1f2e3d4c5b6a7089 locked = false.`, and every player's chat shows
`2 piece(s) unlocked - the table is free to rearrange.`

#### Gotchas

**This returns immediately. The change is not visible in `ObjectData` — including this handle's own properties —
until the host has applied it. Call `await handle.refresh()` if you need to read the result.**

**Applies to: every object kind.** Unlocking an entity that is not locked is a no-op that still costs an intent
and a snapshot — filter on `handle.locked` first, as the example does.

**Unlocking restores the authored body type, not "dynamic".** A board authored as a static rigidbody is static
again after the unlock; it has stopped refusing player actions and nothing else. If you expected it to start
falling, the
lock was never what was holding it up.

**The entity may resume moving immediately.** An unlocked dynamic entity that was locked in mid-air falls the
moment the host applies this. Place it where it should rest before you release it.

#### See also

- [`ObjectHandle.lock`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlelock) — the other half.
- [`ObjectData.locked`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatalocked) — reading the current state.
- [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) — why `unlock` is the exception to the locked rule.
- [RIGIDBODY](https://diceytable.com/docs/editor/inspector/rigidbody) — the authored body type this restores.

### objecthandle.roll

```ts
roll(): void;
```

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

Roll this object (dice).

Throws this die. The sandbox posts an `object-action` intent with the action `roll`; the host applies a randomized
impulse and lets the physics simulation decide where it lands and which face is up.

#### How, why and when to use it

A round starts and the game rolls for everyone rather than asking each player to throw their own die.
`roll()` gives you the same throw a player gets — a real physics tumble, visible to everyone as it happens, and
unpredictable in the way a die is supposed to be. The alternative is to compute a number with `Math.random()` and
put it somewhere, which is faster and completely deterministic to implement — and looks like nothing at the table,
because no die moves. Roll when the throw is part of the game people are watching; generate a number yourself when
you need a random value that no player is supposed to see land.

#### Example

```ts
// content/scripting-api/examples/objecthandle.roll.ts

// Scene script: roll every die on the table on request. roll() applies a
// randomized throw impulse and returns straight away; each die reports what
// it landed on through onDiceRolled, about a second later, when it stops.

async function rollAllDice(): Promise<void> {
  const dice = await world.getAllObjects({ kind: "die" });
  if (dice.length === 0) {
    world.log("No dice on the table.");
    return;
  }

  for (const die of dice) {
    die.roll();
  }
  world.broadcast(`Rolling ${dice.length} dice...`);
}

globalEvents.onDiceRolled.add((handle, value) => {
  world.log(value === null
    ? `${handle.id} landed cocked; no value to read.`
    : `${handle.id} settled showing ${value}.`);
});

globalEvents.onChatMessage.add((message) => {
  if (message.text.trim() === "!roll") {
    void rollAllDice();
  }
});
```

With two dice the chat shows `Rolling 2 dice...`, and about a second later the script console prints one
`obj-1 settled showing 4.` line per die as each one stops.

#### Gotchas

**This returns immediately. The change is not visible in `ObjectData` — including this handle's own properties —
until the host has applied it, and the die keeps moving long after that. Do not poll for the result: subscribe to
[`globalEvents.onDiceRolled`](https://diceytable.com/docs/scripting-api/events#globaleventsondicerolled) (or `onRolled` on the die's own
handle), which fires when the die stops and hands you the number it landed on.**

**Applies to: `die`. The host does not check, and every other kind is thrown anyway.** There is no guard on the
action — roll a `card` and the host launches the card across the table with a die's impulse; roll a `board` and it
takes off too. Check `handle.kind` before rolling anything your script did not spawn.

**The result arrives on the settle, about a second later.** `globalEvents.onDiceRolled` and
`ObjectHandle.onRolled` no longer fire beside the `roll` action — they fire when the die comes to rest, carrying
the printed face value. A die that lands cocked, and a die imported as a custom model with no face table, report
`value: null`; that is "no readable value", not "not implemented".

**Physics has to be running.** A throw with the simulation frozen goes nowhere. Edit Mode switches from Frozen to
Live automatically when you press ▶ Play Scripts, and says so in the script console.

**Rolling several dice in one loop is one impulse each, not a shared throw.** They will collide with each other if
they are close together, which is realistic and occasionally sends one off the table — the host nudges strays back
onto the surface, but a die that lands on another die stays there.

#### See also

- [`globalEvents.onDiceRolled`](https://diceytable.com/docs/scripting-api/events#globaleventsondicerolled) — the number the die landed on, once it stops.
- [`ObjectData.position`](https://diceytable.com/docs/scripting-api/objecthandle#objectdataposition) — where the die came to rest.
- [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) — what the host does for `roll` on each kind.
- [Object kinds](https://diceytable.com/docs/mods/reference/object-kinds) — the `die` kind and its physics defaults.

### objecthandle.shuffle

```ts
shuffle(options?: ObjectActionOptions): void;
```

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

Shuffle this container/deck. Pass { silent: true } to reorder without the spin or the
riffle — for setup a player is not meant to be watching.

Reorders this deck's contents. The sandbox posts an `object-action` intent with the action `shuffle`; the host
shuffles the card entries with a seed only it knows, then re-derives which card is showing.

#### How, why and when to use it

A hand has ended, the discards have been combined back into the deck, and the next deal must not be predictable
from the last one. `shuffle()` is the reorder, and the seed is host-private on purpose: no peer — including a
player reading their own network traffic — can reproduce the order or work out what is coming. The alternative is
to draw everything and spawn it back in a random order of your own, which costs one intent per card, loses the
deck's identity, and uses a random number generator every client can see. Shuffle when the deck should become
unknown; use `draw` and `deal` when you want cards to leave it.

#### Example

```ts
// content/scripting-api/examples/objecthandle.shuffle.ts

// Scene script: shuffle every deck at the start of a round. Only decks are
// queried - the host reorders a deck's contents and nothing else's.

async function shuffleDecks(): Promise<void> {
  const decks = await world.getAllObjects({ kind: "deck" });
  if (decks.length === 0) {
    world.log("No decks on the table.");
    return;
  }

  let shuffled = 0;
  for (const deck of decks) {
    const before = await deck.refresh();
    if (before === null) {
      world.log(`${deck.id} left the table before it could be shuffled.`);
      continue;
    }
    deck.shuffle();
    shuffled += 1;
    world.log(`Shuffled deck ${deck.id} (label "${before.name ?? "none"}").`);
  }

  if (shuffled > 0) {
    world.broadcast(`${shuffled} deck(s) shuffled.`);
  }
}

globalEvents.onTurnStarted.add(() => {
  void shuffleDecks();
});

globalEvents.onChatMessage.add((message) => {
  if (message.text.trim() === "!shuffledecks") {
    void shuffleDecks();
  }
});
```

With one deck on the table the script console prints
`Shuffled deck script-1f2e3d4c5b6a7089 (label "deck-standard").` and every player's chat shows
`1 deck(s) shuffled.`

#### Gotchas

**This returns immediately. The change is not visible in `ObjectData` — including this handle's own properties —
until the host has applied it. Call `await handle.refresh()` if you need to read the result.**

**Applies to: `deck`, and only while it holds at least two cards.** A deck of one card, or an empty one, is left
alone. On **every other kind, including `bag`**, the host refuses the action outright: nothing moves, no sound
plays, no `onShuffled` fires, and you get no error — the call resolves and nothing happened. If you are shuffling
a container, check that `handle.kind` is `"deck"` first. A `bag` draws at **random**, so there is no order for a
shuffle to change; if you wanted the visual, use `handle.rotate()`.

**The order is deliberately unknowable.** The shuffle is seeded from host-private state, and peers learn the
result only through the snapshot they are allowed to see. Your script runs on the host, so it *could* read the
order back — do not build a game on that, because a player's client cannot, and any logic that depends on it will
behave differently for the host than for everyone else.

**A shuffle does not change what is on top by itself.** The host re-derives the visible face from the new first
entry, so the deck's appearance updates — but nothing about position, rotation or lock state changes.

#### See also

- [`ObjectHandle.draw`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandledraw) — taking one card off the container.
- [`ObjectHandle.deal`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandledeal) — one card to every seat.
- [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) — what the host does for `shuffle` on each kind.
- [Deck Editor](https://diceytable.com/docs/editor/item-editors/deck) — building the deck this shuffles.

### objecthandle.draw

```ts
draw(): void;
```

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

Draw the top item from this deck/bag.

Takes one item off this container. The sandbox posts an `object-action` intent with the action `draw`; the host
removes the next entry according to the container's draw mode, spawns it as a new `card` entity, and shrinks the
container's stack.

#### How, why and when to use it

A player has landed on a space that says "draw a chance card", and the card should come off the deck without
anybody reaching for it. `draw()` is the take. The alternative is `deal()`, which most authors try when they want
cards to go to people — and which does something quite different: it gives one card to *every* seat, not one card
to the container's owner. Use `draw()` for a single card leaving a specific container; use `deal()` for a round of
cards going to the whole table.

#### Example

```ts
// content/scripting-api/examples/objecthandle.draw.ts

// Scene script: pull one card off each deck into the middle of the table. A
// script's draw is not attributed to a player, so place the card yourself.

const RIVER_Z = 0;
const RIVER_HEIGHT = 0.6;

async function drawToRiver(): Promise<void> {
  const decks = await world.getAllObjects({ kind: "deck" });
  if (decks.length === 0) {
    world.log("No decks to draw from.");
    return;
  }

  for (const deck of decks) {
    deck.draw();
  }
  world.log(`Requested one card from each of ${decks.length} deck(s).`);
}

globalEvents.onCardDrawn.add((card, context) => {
  world.log(`${context.actor} drew ${card.name ?? card.id}; moving it to the river.`);
  card.setPosition([0, RIVER_HEIGHT, RIVER_Z]);
  world.broadcast(`A card was turned to the river: ${card.name ?? "unnamed"}.`);
});

globalEvents.onChatMessage.add((message) => {
  if (message.text.trim() === "!draw") {
    void drawToRiver();
  }
});
```

With one deck the script console prints `Requested one card from each of 1 deck(s).` then
`Script drew AS; moving it to the river.`

#### Gotchas

**This returns immediately. The change is not visible in `ObjectData` — including this handle's own properties —
until the host has applied it. Call `await handle.refresh()` if you need to read the result**, and note the drawn
card is a **new entity** with its own id, not something you can reach from this handle at all.

**Applies to: `deck` and `bag`, and only while the container still holds something.** The host returns without
doing anything for every other kind and for an empty container — there is no error and no log line, so a `draw()`
that appears to do nothing means one of exactly those two things: the wrong kind, or nothing left to take.

**A script's draw is not attributed to a player.** The host resolves the destination from the *actor*, and a
script's actor has no seat. The card therefore goes into a seat's hand only when the container itself is owned by
an active seat; otherwise it lands on the table about 0.9 ft to the +X side of the container. There is no
parameter for "draw to this player" — handle `globalEvents.onCardDrawn`, which fires with the newly created card
and the container's id, and place it yourself as the example does.

**The container's draw mode decides which item comes off.** A deck draws from its front by default; a bag can be
configured to draw at random. `draw()` takes no say in it.

#### See also

- [`ObjectHandle.deal`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandledeal) — one card to every authored seat.
- [`ObjectHandle.shuffle`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleshuffle) — making the next draw unknown.
- [`ObjectHandle.setPosition`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesetposition) — placing the card the
  draw created.
- [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) — what the host does for `draw` on each kind.
- [Object kinds](https://diceytable.com/docs/mods/reference/object-kinds) — the `deck` and `bag` container kinds.

### objecthandle.deal

```ts
deal(): void;
```

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

Deal cards from this deck to players.

Deals one item from this container to every seat. The sandbox posts an `object-action` intent with the action
`deal`; the host walks the table's active seat zones, takes one entry off the container for each and places it in
that seat's hand.

#### How, why and when to use it

The game is starting and everybody needs an opening hand. `deal()` is one pass around the table — one card to each
seat, in seat order, stopping if the container runs out. The alternative is `draw()` in a loop with a
`setPosition` per card, which is what you end up writing if you need to deal *different* numbers to different
seats — but for an even deal it is far more code and it puts the cards on the table rather than in hands. Use
`deal()` for even distribution to everyone; use `draw()` when one specific card is going to one specific place.

#### Example

```ts
// content/scripting-api/examples/objecthandle.deal.ts

// Scene script: deal an opening hand. Each deal() sends ONE card to every
// authored seat, so a five-card hand is five calls with a beat between them.

const OPENING_HAND = 5;

async function dealOpeningHands(): Promise<void> {
  const decks = await world.getAllObjects({ kind: "deck" });
  if (decks.length === 0) {
    world.log("No deck to deal from.");
    return;
  }

  const deck = decks[0];
  world.broadcast("Dealing opening hands...");

  for (let pass = 1; pass <= OPENING_HAND; pass += 1) {
    const state = await deck.refresh();
    if (state === null) {
      world.log(`Deck ${deck.id} left the table mid-deal.`);
      return;
    }

    deck.deal();
    world.log(`Deal pass ${pass} of ${OPENING_HAND} sent from ${deck.id}.`);
    await world.wait(0.4);
  }

  world.broadcast(`Opening hands dealt - ${OPENING_HAND} cards each.`);
}

globalEvents.onChatMessage.add((message) => {
  if (message.text.trim() === "!deal") {
    void dealOpeningHands();
  }
});
```

With a deck and two seated players, chat shows `Dealing opening hands...`, the script console prints five
`Deal pass N of 5 sent from …` lines, and chat finishes with `Opening hands dealt - 5 cards each.`

#### Gotchas

**This returns immediately. The change is not visible in `ObjectData` — including this handle's own properties —
until the host has applied it. Call `await handle.refresh()` if you need to read the result** — and note each
dealt card is a **new entity** with its own id.

**Applies to: `deck` and `bag`, and only while the container still holds something.** Every other kind is ignored
without an error.

**One call is one card per seat, not a whole hand.** For a five-card opening hand you call it five times, as the
example does. The pass stops early and silently when the container empties partway round, so the last seats can
end up short.

**The seats come from the table's authored seat zones, not from who is sitting in them.** A table with no seat
zones deals nothing at all — the host has nowhere to put a card — and a table whose zones are empty of players
still deals into those empty hands. Author the seats before you rely on this.

**Nothing about the deal is aimed.** There is no parameter for a seat, a count, or a starting player. If your game
deals unevenly, or clockwise from the dealer, build it out of `draw()` and `setPosition` instead.

#### See also

- [`ObjectHandle.draw`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandledraw) — one card, one destination.
- [`ObjectHandle.shuffle`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleshuffle) — before the deal, not after.
- [`world.wait`](https://diceytable.com/docs/scripting-api/world#worldwait) — pacing the passes so the table can follow them.
- [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) — what the host does for `deal` on each kind.

### objecthandle.destroy

```ts
destroy(): void;
```

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

Remove this object from the table.

Removes this entity from the table. The sandbox posts an `object-action` intent with the action **`delete`** — the
one action whose name does not match its method — and the host destroys the entity, re-parents any children it
had onto its own ancestor, and drops any joints attached to it.

#### How, why and when to use it

A round has ended and the cards played into the middle have to go, because next round starts from a clean table
and nobody wants to drag twenty cards into a corner. `destroy()` is how a script takes something off the table.
The alternative is to move the pieces somewhere out of the way with `setPosition`, which most authors do first
because it feels safer — and it is worse in the long run: every hidden entity still costs space in every snapshot
for the rest of the session and can still be found and dragged back. Destroy anything the game is genuinely
finished with; move things aside only when a player has a real reason to want them back.

#### Example

```ts
// content/scripting-api/examples/objecthandle.destroy.ts

// Scene script: clear the discard pile on command. destroy() sends the "delete"
// action - the one action whose name does not match its method.

const DISCARD_TAG = "discard";

async function clearDiscards(): Promise<void> {
  const discards = await world.getAllObjects({ tag: DISCARD_TAG });
  if (discards.length === 0) {
    world.log(`Nothing tagged "${DISCARD_TAG}" to clear.`);
    return;
  }

  for (const handle of discards) {
    world.log(`Removing ${handle.kind} ${handle.id}.`);
    handle.destroy();
  }

  const check = await discards[0].refresh();
  world.log(check === null
    ? `Cleared ${discards.length} entity(ies).`
    : `${check.id} is still on the table - the host refused the delete.`);
  world.broadcast(`Cleared ${discards.length} discarded piece(s).`);
}

globalEvents.onObjectAction.add((handle, action) => {
  if (action === "delete") {
    world.log(`delete applied to ${handle.id}.`);
  }
});

globalEvents.onChatMessage.add((message) => {
  if (message.text.trim() === "!cleardiscard") {
    void clearDiscards();
  }
});
```

With three tagged cards the script console prints three `Removing card …` lines, three
`delete applied to …` lines and `Cleared 3 entity(ies).`, and chat shows
`Cleared 3 discarded piece(s).`

#### Gotchas

**This returns immediately. The removal is not visible in `ObjectData` — including this handle's own properties —
until the host has applied it. Call `await handle.refresh()` and expect `null` if you need to confirm it.** The
handle keeps its cached values afterwards, so `handle.id` will go on addressing something that no longer exists.

**Applies to: every object kind.** Nothing refuses a delete, including a locked entity when the request comes from
a script.

**The action is `delete`, not `destroy`.** `globalEvents.onObjectAction` and `ObjectHandle.onAction` report the
string `"delete"`, and so does anything else reading the action vocabulary. The method name is the odd one out.

**Children are re-parented, not destroyed.** An entity with pieces parented to it hands them up to its own
ancestor — or leaves them as roots if it had none. Destroying the base of an assembly leaves the assembly's pieces
on the table, loose. Walk the pieces yourself if the whole thing should go.

**A mod cannot do this at all.** `delete` is not on the mod action allowlist, so a game that needs to remove
entities belongs in a table script. See [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies).

#### See also

- [`ObjectHandle.refresh`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlerefresh) — confirming the entity is gone.
- [`world.spawnObject`](https://diceytable.com/docs/scripting-api/world#worldspawnobject) — the other end of an entity's life.
- [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) — why `delete` is the one action a mod is refused.
- [Parenting](https://diceytable.com/docs/editor/working/parenting) — what happens to an assembly when its base is removed.

### objecthandle.setTooltip

```ts
setTooltip(options: TooltipOptions): void;
```

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

Change this entity's hover tooltip. Only the fields you pass change. Tooltips are off by
default, so pass `enabled: true` to show one.

Changes this entity's hover tooltip — whether it shows, its title, its description, whether the built-in detail
lines appear under it, and its variables. It is a **patch**: only the fields you pass change, and everything you
leave out keeps its current value. The sandbox posts a `set-object-tooltip` intent; the host validates it, merges
it onto the entity's `tooltip` field and replicates the result to every player.

#### Parameters

| Name | Type | Required | Notes |
|---|---|---|---|
| `options` | [`TooltipOptions`](https://diceytable.com/docs/scripting-api/types#tooltipoptions) | yes | Any subset of `enabled`, `title`, `description`, `showDetails` and `variables`. `null` clears a field back to its default; a `null` variable deletes that variable; `variables` **merges** into the existing ones rather than replacing them. |

**Applicability:** every object kind.

#### How, why and when to use it

Tooltips are **off by default** — an entity shows nothing on hover until an author or a script turns its tooltip
on — so the first call on an entity almost always includes `enabled: true`. Use this call when a script owns what a
tooltip says: a board that summarises its rules, a unit card whose description changes with its state, a marker
that explains what it counts. It is the only way to change a tooltip at play time; the Inspector's
[TOOLTIP section](https://diceytable.com/docs/editor/inspector/platform-panels#tooltip) edits the same field in the scene draft, which
is the right place for text that never changes.

Because it is a patch, two scripts can each own part of the same tooltip — one writes the description at load,
another keeps a variable current — without either erasing the other. When all you are changing is one variable,
[`setTooltipVariable`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesettooltipvariable) says so more plainly.

#### Example

```ts
// content/scripting-api/examples/objecthandle.setTooltip.ts

// Scene script: give every board a hover tooltip that sums up the rules, and
// let players switch those tooltips off and on again from chat.

const RULES = [
  "**Goal:** first to {target|10} points wins.",
  "- Roll, then move that many spaces.",
  "- [color=red]Red[/color] spaces cost a point.",
].join("\n");

async function describeBoards(): Promise<void> {
  const boards = await world.getAllObjects({ kind: "board" });
  for (const board of boards) {
    board.setTooltip({
      enabled: true,
      title: "{name}: how to play",
      description: RULES,
      showDetails: false,
      variables: { target: 12 },
    });
  }
  world.log(`Tooltip set on ${boards.length} board(s).`);
}

globalEvents.onChatMessage.add((message) => {
  const text = message.text.trim();
  if (text !== "!tips on" && text !== "!tips off") {
    return;
  }
  const enabled = text === "!tips on";
  void world.getAllObjects({ kind: "board" }).then((boards) => {
    for (const board of boards) {
      board.setTooltip({ enabled });
    }
    world.log(`Board tooltips ${enabled ? "on" : "off"}.`);
  });
});

void describeBoards();
```

With one board on the table the script console prints `Tooltip set on 1 board(s).`, and hovering the board shows
its name followed by `: how to play`, a bold **Goal:** line reading `first to 12 points wins.`, and two bullets.
`!tips off` hides it again without losing the text, so `!tips on` brings back exactly the same tooltip.

#### Gotchas

**This returns immediately. The change is not visible in `ObjectData` — including this handle's own `tooltip` —
until the host has applied it and the next snapshot arrives. Call `await handle.refresh()` if you need to read the
result.**

**Mistakes are errors, not silent no-ops.** The host validates the patch against a strict schema: a misspelt key
(`descripton`), a variable name that is not an identifier, a title over 120 characters, a description over 1,000
or a string variable over 200 is refused whole, with a diagnostic in the script console reading
`Invalid tooltip change from script: …` and naming the offending field (`apps/web/src/scripting/TableScriptHost.ts`,
`validateScriptIntent`). Nothing in the patch is applied.

**More than 32 variables refuses the whole change.** The cap is counted after the merge, against the entity's
current variables, and a patch that would push it past 32 is refused with an error in the script console. Delete
variables you no longer need (pass them as `null`) before adding new ones. Two calls inside the same snapshot
interval can both pass that check; the host then refuses the second one without a message.

**Turning a tooltip off keeps its text.** `enabled: false` hides the tooltip but leaves `title`, `description` and
`variables` where they were, which is why toggling `enabled` is the cheap way to show and hide one. To remove a
tooltip entirely, clear every field: once it is disabled *and* holds nothing, the field disappears and
`handle.tooltip` reads `null` again.

**The title takes variables, not formatting.** `**`, `*` and `[color=…]` in a title are shown exactly as typed;
only the description is formatted. See the [template syntax](https://diceytable.com/docs/editor/inspector/platform-panels#tooltip-template-syntax).

**Setting the same value again costs nothing.** The host compares the merged result with what the entity already
has and does not broadcast a snapshot when they match, so a script may re-assert a tooltip every turn. Tooltip
changes are also deliberately kept out of the table's event log.

**Hidden information applies.** A tooltip is treated as part of an entity's identity: a player who may not see a
face-down card's face does not receive its tooltip at all. Do not rely on that to keep a secret on a card that
may later be turned face up — everything in its tooltip becomes visible with it. A deck's own tooltip describes
the pile and stays visible while the deck is face down, unless the deck sits in a hidden zone.

#### See also

- [`TooltipOptions`](https://diceytable.com/docs/scripting-api/types#tooltipoptions) — every field this accepts.
- [`ObjectHandle.setTooltipVariable`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesettooltipvariable) — change one variable.
- [`ObjectData.tooltip`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatatooltip) — reading the current tooltip back.
- [TOOLTIP](https://diceytable.com/docs/editor/inspector/platform-panels#tooltip) — authoring the same field in the Inspector, and the template syntax.
- [Host authority](https://diceytable.com/docs/scripting/concepts/host-authority) — why a change lands on the next snapshot.

### objecthandle.setTooltipVariable

```ts
setTooltipVariable(name: string, value: TooltipVariableValue | null): void;
```

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

Set one tooltip variable, read in the title or description as `{name}`. A name is a
letter or `_` followed by up to 31 letters, digits or `_`; `null` deletes it. The
value is shown as plain text — formatting characters in it are not interpreted.

Sets one of this entity's tooltip variables — the value a `{name}` in its tooltip title or description is replaced
with — or deletes it when `value` is `null`. It is shorthand for
`setTooltip({ variables: { [name]: value } })`: the same `set-object-tooltip` intent, merged on the host, touching
nothing but that one variable.

#### Parameters

| Name | Type | Required | Notes |
|---|---|---|---|
| `name` | `string` | yes | A letter or `_`, then up to 31 letters, digits or `_` (`hp`, `hp_max`, `Score2`). No dots — dotted names are reserved for the built-ins `counters.<key>` and `values.<key>`. An empty string, or anything that is not a string, does nothing at all; any other invalid name is refused with a diagnostic. |
| `value` | [`TooltipVariableValue`](https://diceytable.com/docs/scripting-api/types#tooltipvariablevalue) `\| null` | yes | A string (at most 200 characters), a finite number or a boolean. `null` — or leaving it out — deletes the variable, so the template falls back to its `{name\|fallback}` text or to nothing. |

**Applicability:** every object kind.

#### How, why and when to use it

Write the tooltip's wording once — in the Inspector or with one `setTooltip` call at load — and let play change
only the numbers. A unit's hit points, a deck's draw count this turn, the player who last touched a die: each is a
variable the description reads, and each change is one small intent that cannot disturb the wording around it.
The alternative, rebuilding the whole description string on every change, works but puts formatting and state in
the same string, so a value containing `*` or `[` would have to be escaped by you — whereas a variable's value is
**always shown as plain text**, whatever characters it contains.

#### Example

```ts
// content/scripting-api/examples/objecthandle.setTooltipVariable.ts

// Scene script: every die's tooltip says who rolled it last. The template is
// written once at load; each roll changes only the one variable it reads.

async function prepareDice(): Promise<void> {
  const dice = await world.getAllObjects({ kind: "die" });
  for (const die of dice) {
    die.setTooltip({
      enabled: true,
      description: "Last rolled by *{roller|nobody yet}*",
    });
  }
  world.log(`Tooltips on for ${dice.length} dice.`);
}

globalEvents.onDiceRolled.add((handle, value, context) => {
  handle.setTooltipVariable("roller", context.actor);
  world.log(`${handle.id} rolled ${value === null ? "cocked" : String(value)}.`);
});

globalEvents.onChatMessage.add((message) => {
  if (message.text.trim() !== "!forget") {
    return;
  }
  void world.getAllObjects({ kind: "die" }).then((dice) => {
    for (const die of dice) {
      die.setTooltipVariable("roller", null);
    }
    world.log(`Cleared the roller on ${dice.length} dice.`);
  });
});

void prepareDice();
```

Before anyone rolls, hovering a die shows its name, *Last rolled by nobody yet* in italics and — because
`showDetails` was left at its default — the built-in `Value:` line. After a roll the italic text becomes the
rolling peer's id, and `!forget` puts every die back to *nobody yet*.

#### Gotchas

**This returns immediately. The change is not visible in `ObjectData` — including this handle's own
`tooltip.variables` — until the host has applied it and the next snapshot arrives. Call `await handle.refresh()`
if you need to read the result.**

**Setting a variable does not turn the tooltip on.** On an entity whose tooltip is off, or that has never had one,
the variable is stored and nothing appears on hover. Pair it with `setTooltip({ enabled: true })` — the example
does that at load — or enable the tooltip in the Inspector.

**One call is one intent and one snapshot.** Changing three variables with three calls broadcasts three
snapshots. When several change together, pass them in one
[`setTooltip({ variables: { … } })`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesettooltip) instead.

**An entity holds at most 32 variables.** A call that would add a 33rd is refused with an error in the script
console, and the variable never appears. Delete variables you are finished with.

**Your variable wins over a built-in of the same name.** Setting `value` on a die replaces the built-in `{value}`
(the face it landed on) everywhere that die's templates use it. Choose names that do not collide with `name`,
`kind`, `value`, `count` or `owner` unless overriding one is the point.

**Numbers are shown rounded.** A whole number shows as-is; any other number is rounded to two decimal places
(`2.5` stays `2.5`, `1.23456` shows `1.23`), and a boolean shows as `true` or `false`.

**Players who cannot see the entity cannot see its variables.** The whole tooltip, variables included, is withheld
from a player not entitled to a hidden card's identity, and from every entity in a hidden zone. A variable is not
a safe place for a secret on a card that may later be turned face up.

#### See also

- [`ObjectHandle.setTooltip`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesettooltip) — change several fields or variables at once.
- [`TooltipData.variables`](https://diceytable.com/docs/scripting-api/types#tooltipdatavariables) — reading the variables back.
- [`TooltipVariableValue`](https://diceytable.com/docs/scripting-api/types#tooltipvariablevalue) — what a value may be.
- [TOOLTIP template syntax](https://diceytable.com/docs/editor/inspector/platform-panels#tooltip-template-syntax) — `{name}`, `{name|fallback}` and the built-in variables.

### objecthandle.getSavedData

```ts
getSavedData(key?: string): Promise<string | null>;
```

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

Reads one string your scripts previously stored against **this entity**. The sandbox asks the host for the value
under `obj:<id>:<key>`, so two entities never share a slot even when they use the same key.

#### Parameters

| Name | Type | Required | Notes |
|---|---|---|---|
| `key` | `string` | no | Names one slot on this entity. Anything that is not a string — including omitting it — becomes `""`, so `getSavedData()` reads the entity's single unnamed slot. Not trimmed or lowercased: `"Note"` and `"note"` are different slots. |

**Applicability:** every object kind. The scope is the entity's id, and every entity has one.

#### Returns

`Promise<string | null>`.

`null` means **no value is stored under that key for this entity**. Values are always strings — encode numbers and
structures yourself, and parse defensively on the way back, because a value written by an older version of your
script is exactly as likely as a well-formed one.

The promise rejects if the host refuses the request.

#### How, why and when to use it

Each token in your game tracks its own hit points, and the number has to be attached to *that* token rather than
to a table-wide map you have to keep in step as tokens are spawned and destroyed. Per-entity saved data is that
attachment: the key is scoped to the id, so the bookkeeping disappears with the entity. The alternative is
`world.getSavedData` with the id baked into the key — which works, and leaves you owning the cleanup when the
entity goes away. Use the entity scope when the value belongs to one piece; use the table scope for anything about
the game as a whole.

#### Example

```ts
// content/scripting-api/examples/objecthandle.getSavedData.ts

// Scene script: read the per-entity note stored against each die. Saved data
// here is scoped to one entity, so two dice never share a slot.

const NOTE_KEY = "note";

async function readDieNotes(): Promise<void> {
  const dice = await world.getAllObjects({ kind: "die" });
  if (dice.length === 0) {
    world.log("No dice on the table.");
    return;
  }

  for (const die of dice) {
    const note = await die.getSavedData(NOTE_KEY);
    world.log(note === null
      ? `${die.id}: nothing stored under "${NOTE_KEY}".`
      : `${die.id}: ${note}`);
  }

  // Omitting the key reads the entity's one unnamed slot.
  const unnamed = await dice[0].getSavedData();
  world.log(`${dice[0].id} default slot: ${unnamed === null ? "empty" : unnamed}`);
}

globalEvents.onChatMessage.add((message) => {
  if (message.text.trim() === "!notes") {
    void readDieNotes();
  }
});

void readDieNotes();
```

Each line reads `script-1f2e3d4c5b6a7089: nothing stored under "note".` until something writes one, and the
stored text afterwards — including after a reload.

#### Gotchas

**Resolves after a round-trip to the host, so the value is the host's state at the moment it answered — not
necessarily still true when your handler continues.**

**Your key is not the storage key.** The host namespaces the request as `obj:<objectId>:<key>` and then composes
the runtime key as `scripts.<scope>.<encoded namespaced key>.v1`
(`apps/web/src/playcanvas/savedDataKeys.ts`, `tableScriptSavedDataKey`), escaping every character the store's key
pattern does not allow. It is invisible from a script, and it is why the value is not reachable from a mod: mod
saved data is keyed by mod id, in a different key space in the same store.

**Edit Mode's store is session-only** and is cleared every time you stop or restart the scripts, so the editor
cannot show you whether a value truly persists. At a real table it rides the snapshot.

**Nothing tidies up after a deleted entity.** A slot keyed on an id outlives the entity that id addressed.

#### See also

- [`ObjectHandle.setSavedData`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesetsaveddata) — the write half.
- [`world.getSavedData`](https://diceytable.com/docs/scripting-api/world#worldgetsaveddata) — the same idea scoped to the whole table.
- [`ObjectData.metadata`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatametadata) — the other per-entity bag, which a
  script can read but not write.
- [Known limitations](https://diceytable.com/docs/reference/known-limitations) — the full list of documented gaps.

### objecthandle.setSavedData

```ts
setSavedData(value: string, key?: string): Promise<void>;
```

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

Stores one string against **this entity** for your scripts to read back later. The sandbox sends it to the host
under `obj:<id>:<key>`, so the value belongs to this entity and no other.

#### Parameters

| Name | Type | Required | Notes |
|---|---|---|---|
| `value` | `string` | yes | Coerced with `String()` before it leaves the sandbox; `null` and `undefined` both become `""`. A plain object becomes `"[object Object]"` — serialize with `JSON.stringify` yourself. Nothing throws on a bad value. |
| `key` | `string` | no | Names the slot on this entity. Anything that is not a string — including omitting it — becomes `""`, the entity's single unnamed slot. Not normalized: `"Note"` and `"note"` are different slots. |

**Applicability:** every object kind.

#### Returns

`Promise<void>`.

It resolves with no value once the host has accepted the write, and **rejects** with an `Error` when the host
refuses — a write against an id that is not on the table is the usual cause. Await it inside `try`/`catch` so the
refusal is visible rather than surfacing as an unhandled rejection.

#### How, why and when to use it

A token's hit points change every time it is attacked, and the number has to travel with that token — through a
save, a reload, and a host migration. Writing it against the entity's own id is what makes that true without you
maintaining a side table. The alternative is `ObjectData.metadata`, which does replicate and does persist and is
right there on the handle — but a script cannot write it, so it is only usable for values fixed at spawn time. Use
per-entity saved data for anything about one piece that changes during play.

#### Example

```ts
// content/scripting-api/examples/objecthandle.setSavedData.ts

// Scene script: stamp each die with the peer that last rolled it. The write is
// awaited so a refusal shows up in the console instead of vanishing.

const LAST_ROLLER_KEY = "last-roller";

async function recordRoller(handle: ObjectHandle, actor: string): Promise<void> {
  try {
    await handle.setSavedData(actor, LAST_ROLLER_KEY);
    world.log(`${handle.id} last rolled by ${actor}.`);
  } catch (error) {
    const detail = error instanceof Error ? error.message : String(error);
    world.log(`${handle.id} roller not stored: ${detail}`);
  }
}

globalEvents.onDiceRolled.add((handle, value, context) => {
  world.log(`${handle.id} settled (value ${value === null ? "cocked" : String(value)}).`);
  void recordRoller(handle, context.actor);
});

globalEvents.onChatMessage.add((message) => {
  if (message.text.trim() !== "!clearrollers") {
    return;
  }
  void world.getAllObjects({ kind: "die" }).then((dice) => {
    for (const die of dice) {
      void recordRoller(die, "nobody");
    }
  });
});
```

The script console prints `script-1f2e3d4c5b6a7089 last rolled by a1b2c3d4.` after each roll.

#### Gotchas

**Resolves once the host has accepted the write. The value reaches other peers with the next snapshot, not when
this resolves.**

**Your key is not the storage key.** The host namespaces the request as `obj:<objectId>:<key>` and then composes
the runtime key as `scripts.<scope>.<encoded namespaced key>.v1`
(`apps/web/src/playcanvas/savedDataKeys.ts`, `tableScriptSavedDataKey`), escaping every character the store's key
pattern does not allow. Nothing about that is visible from a script, and it is why a mod cannot read what a table
script wrote.

**Writing to a destroyed entity fails.** The host will not persist data against an id that is not on the table, so
a write racing a delete is rejected.

**Nothing validates what you stored.** The slot holds a string and hands it back unchanged, however old the writer
was. Version your format if it is more than a number.

#### See also

- [`ObjectHandle.getSavedData`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlegetsaveddata) — the read half.
- [`world.setSavedData`](https://diceytable.com/docs/scripting-api/world#worldsetsaveddata) — the same idea scoped to the whole table.
- [`ObjectData.metadata`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatametadata) — the read-only per-entity bag.
- [Known limitations](https://diceytable.com/docs/reference/known-limitations) — the full list of documented gaps.

## ObjectData

_Surface A — table script · interface · 13 members_

Read-only data snapshot of a table object.

`ObjectData` is the twelve-field shape a table script can see of an entity: `id`, `kind`, `name`, `position`,
`rotation`, `scale`, `locked`, `faceUp`, `stackCount`, `tags`, `metadata` and `tooltip`. Every `ObjectHandle`
extends it, and every one of the twelve is derived by one function in the sandbox (`apps/web/src/scripting/sandbox/tableScriptSandbox.html`,
`stateToData`) from the entity's replicated state — which is why the same twelve values reach you identically
whether they arrived with an event, with a query or with a refresh.

It is also the resolved value of [`refresh()`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlerefresh), and there it is a **detached copy**: a
plain record with the twelve fields and no methods, no delegates and no link back to the handle. The handle's own
fields keep tracking the table; the copy you were handed does not change again.

### How, why and when to use it

You want an entity's state as it stood at one moment — to compare two positions a second apart, or to record what
a card looked like before you flipped it. `const before = await handle.refresh();` gives you twelve values that
came from one host answer and stay put. The alternative is reading the handle's fields one at a time, which is
right for a single question ("is it locked?") and wrong the moment an `await` sits between two of your reads: the
sandbox can rewrite the record in that gap, so `before.position` and `before.faceUp` end up describing two
different states. Take the copy when you need several fields to agree with each other; read the handle directly
when you need one field and need it now.

### Gotchas

**`name` is the entity's `label`, not its human-readable name.** `stateToData` populates it from `label` — the
slug — and returns `null` for an empty one. `displayName` is not published to a table script at all. See
[`ObjectData.name`](https://diceytable.com/docs/scripting-api/objecthandle#objectdataname) and
[A table script cannot read `displayName`](https://diceytable.com/docs/reference/known-limitations#a-table-script-cannot-read-displayname).

**Coordinates are in feet.** `position` is absolute table space, so `[0, 1, 0]` is one foot above the table
origin; `rotation` is Euler degrees.

**Twelve fields is far fewer than the entity has.** No `displayName`, no `parentId`, no components, no color,
physics, owner seat or container contents. Those are on the replicated
[object state](https://diceytable.com/docs/mods/reference/object-state) and are unreachable from this surface.

**`readonly` is a type-level promise, not a frozen object.** TypeScript refuses `data.locked = true` at compile
time and nothing stops you writing into the `metadata` record at run time — which changes nothing on the table
and is thrown away by the next refresh, because that replaces the whole record. Copy anything you intend to
change.

### See also

- [`ObjectHandle`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandle) — the interface that extends these twelve fields with methods and delegates.
- [`ObjectHandle.refresh`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlerefresh) — the call that resolves an `ObjectData`.
- [`ObjectData.name`](https://diceytable.com/docs/scripting-api/objecthandle#objectdataname) — which of the three names this is.
- [Object state](https://diceytable.com/docs/mods/reference/object-state) — the full replicated entity, including the fields this omits.
- [Known limitations](https://diceytable.com/docs/reference/known-limitations) — every documented gap, in one list.

### Members

| Signature | Description | Returns |
|---|---|---|
| [`id`](https://diceytable.com/docs/scripting-api/objecthandle#objectdataid) |  | `string` |
| [`kind`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatakind) |  | `ObjectKind` |
| [`name`](https://diceytable.com/docs/scripting-api/objecthandle#objectdataname) |  | `string \| null` |
| [`position`](https://diceytable.com/docs/scripting-api/objecthandle#objectdataposition) |  | `Vec3` |
| [`rotation`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatarotation) |  | `Vec3` |
| [`scale`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatascale) | The entity's scale. For an imported model this is a MULTIPLIER on the model's own size, not a size in feet — copy it onto a replacement with `spawnObject`'s `scale` so the two match. | `Vec3` |
| [`locked`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatalocked) |  | `boolean` |
| [`faceUp`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatafaceup) |  | `boolean \| null` |
| [`stackCount`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatastackcount) | How many items this entity represents — the height of a card stack, the size of a token pile, the number of cards left in a deck. `1` for anything that does not stack. | `number` |
| [`tags`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatatags) |  | `readonly string[]` |
| [`seat`](https://diceytable.com/docs/scripting-api/objecthandle#objectdataseat) | The seat this entity belongs to — the seat colour id an author picked in the Inspector's Seat field (`"white"`, `"red"`, …) — or null when it belongs to no seat. | `string \| null` |
| [`metadata`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatametadata) |  | `Readonly<Record<string, unknown>>` |
| [`tooltip`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatatooltip) | This entity's hover tooltip, or null when it has never been given one (the default). | `TooltipData \| null` |

### objectdata.id

```ts
readonly id: string;
```

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

The entity's address. This is the only value that resolves an entity — `world.getObjectById`, the sandbox's own
handle table and every host-side lookup key on it, and nothing anywhere looks an entity up by either of its names.
It is assigned when the entity is created and never changes.

#### How, why and when to use it

You need to act on the same entity across two events — a token picked up in one handler and dropped in another,
or a deck you found at load and want to shuffle three turns later. Store `handle.id`, not the handle, when the
gap is long or the value has to survive into saved data: an id is a plain string you can persist, compare and
log, whereas a handle is a live object whose properties will have drifted. Store the handle when you are acting
inside the same handler and want the methods. The one thing never to do is identify an entity by
`ObjectData.name` — that is a label, it is not unique across kinds, and two entities can share it.

#### Gotchas

**An id from `world.spawnObject` is real before the entity is.** The sandbox generates the id — a `script-` prefix
and sixteen hex characters — and posts it with the spawn intent, so you hold a correct address before the host has
validated anything. If the host rejects the definition, that id addresses nothing forever.

**Comparison is exact.** Ids are compared with `===` after string coercion, with no trimming or case folding.

#### See also

- [`world.getObjectById`](https://diceytable.com/docs/scripting-api/world#worldgetobjectbyid) — turning an id back into a handle.
- [`ObjectData.name`](https://diceytable.com/docs/scripting-api/objecthandle#objectdataname) — the value that is *not* an address.
- [IDs, names and tags](https://diceytable.com/docs/editor/concepts/ids-names-tags) — the three names and which one resolves.

### objectdata.kind

```ts
readonly kind: ObjectKind;
```

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

What kind of thing this entity is: `card`, `deck`, `die`, `token`, `board`, `bag`, `custom`, `card-holder`,
`button`, `table` or `coin`. The kind is fixed at spawn and decides how the host treats the entity — which actions do something,
what its physics defaults are, and what shape it gets.

#### How, why and when to use it

Your handler has a handle that came from `globalEvents.onObjectDropped`, so it could be anything a player can pick
up, and you are about to call `shuffle()` on it. Reading `kind` first is what tells you whether that call will do
anything at all: on anything but a `deck` the host refuses it silently — no error, no event, no sound. The
alternative is to filter at the query — `world.getAllObjects({ kind: "deck" })` — and that is the
better tool whenever you are *choosing* which entities to work on, because it never returns the wrong one in the
first place. Read `kind` when the entity arrived from somewhere you did not choose: an event payload, an id out of
saved data, a handle a player's action handed you.

#### Gotchas

**Not every action checks the kind, so this is your guard rather than the host's.** `roll` on a card throws the
card; `flip` on a die turns it over and flips its face flag. Only the container actions guard themselves — and
`flip` on a `token` or `coin`, which the host refuses when the piece may not turn over, and `toss`, which the
host refuses on anything but a `coin`. See
[Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) for exactly which do and do not.

**The type is widened, so a typo compiles.** `ObjectKind` names all eleven kinds and then admits any other
string, so `kind === "dice"` type-checks and is always `false`. Compare against the literals the runtime
actually uses.

#### See also

- [`world.getAllObjects`](https://diceytable.com/docs/scripting-api/world#worldgetallobjects) — filtering by kind at the query instead.
- [Object kinds](https://diceytable.com/docs/mods/reference/object-kinds) — all eleven kinds, their physics defaults and their fields.
- [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) — which actions do something on which kind.
- [Object Types](https://diceytable.com/docs/scripting-api/object-types) — the handle type each kind resolves to in a script.
- [PIECE](https://diceytable.com/docs/editor/inspector/piece) — where an entity's kind is set in Edit Mode.

### objectdata.name

```ts
readonly name: string | null;
```

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

The entity's **`label`** — its slug and machine key, not its human-readable name. The sandbox reads
`label` off the entity's state and publishes it here under the name `name`, so a card's `name` is its card
identity (`AS`, `10H`), a preset's is its preset slug (`die-d6`), and an entity a script spawned without one is
named after its kind.

`null` only when the handle has never carried real entity state — a `world.spawnObject` result whose label
somehow never landed, or a handle built for an id the sandbox has never seen state for. Every entity on the table
has a label, so a refreshed handle always reports a string.

#### How, why and when to use it

You are logging what a player just did, and `Player drew AS` reads better than
`Player drew script-1f2e3d4c5b6a7089`. `name` is the readable identifier for that, and for `kind: "card"` it is
more than cosmetic — the label *is* which card it is, so a hand-scoring routine reads it to know what was played.
The alternative is `id`, and that is what you must use for anything that has to be exact: labels are not unique,
two decks can both be labeled `deck-standard`, and a player renaming an entity in Edit Mode changes it. Read
`name` to display or to identify a *card*; read `id` to address an entity.

#### Gotchas

**This is the slug, and it is load-bearing for cards.** A card's `label` drives hidden-information redaction —
which peers are allowed to see which card. It is not free text, and nothing a script does can change it after
spawn.

> **Known gap.** A table script cannot see an entity's human-readable name at all. Entities carry both a `label`
> and an optional `displayName` — the one shown in the Hierarchy and the Inspector — and the sandbox publishes
> only `label` (`apps/web/src/scripting/sandbox/tableScriptSandbox.html`, `stateToData`).
> `SpawnObjectOptions.name` likewise writes `label`. Everything about labels works correctly and every entity
> reports one; the second name is not exposed at all. **This is a Surface A boundary, not a platform one** — mod
> scripting reads the entity state its peer received, which carries `displayName` except on a card that peer
> may not identify (redaction deletes it, exactly as it rewrites `label`). Use tags or the label itself when a
> script needs to recognize an entity by something an author typed.
> See [Known limitations](https://diceytable.com/docs/reference/known-limitations).

#### See also

- [`ObjectData.id`](https://diceytable.com/docs/scripting-api/objecthandle#objectdataid) — the value that actually addresses an entity.
- [`world.spawnObject`](https://diceytable.com/docs/scripting-api/world#worldspawnobject) — the only place a script writes a label.
- [IDs, names and tags](https://diceytable.com/docs/editor/concepts/ids-names-tags) — the three names, in full.
- [Object state](https://diceytable.com/docs/mods/reference/object-state) — the entity state a mod reads, `displayName` included, and what redaction removes from it.
- [Known limitations](https://diceytable.com/docs/reference/known-limitations) — the full list of documented gaps.

### objectdata.position

```ts
readonly position: Vec3;
```

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

Where the entity is, as `[x, y, z]` in **feet**. The coordinates are table-space and absolute — `[0, 1, 0]` is one
foot above the table origin — and they stay absolute even for an entity parented to another, so a piece welded to
a board still reports where it is on the table rather than an offset from the board.

#### How, why and when to use it

You want to lay a drawn card next to the deck it came from, or drop a turn marker beside whichever seat is
active, and both need a coordinate to start from. Reading the position of something already in the right area is
the cheapest way to get one. The alternative is to hard-code the layout as constants, which is what you should do
for fixed furniture — a river, a discard slot, a scoring track — because a constant cannot drift when a player
nudges the piece you were measuring from. Read `position` when the answer depends on where something *currently*
is; hard-code when the answer is part of the board.

#### Gotchas

**It is a cached value, not a live read.** The array is refreshed when the handle is delivered by a world query,
by an event, or by `refresh()` — and not in between. A piece being dragged across the table has a stale position
here every frame you did not ask about.

**Y is up, and it is the entity's origin rather than the surface it rests on.** A card lying on the table does not
report `y: 0`. Copy a resting height from a similar entity rather than guessing one.

**The array is a fresh copy each refresh, and writing to it does nothing.** `handle.position[0] = 5` changes a
number in the frame and no part of the table. Use
[`setPosition`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesetposition).

#### See also

- [`ObjectHandle.setPosition`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesetposition) — moving the entity.
- [`ObjectHandle.refresh`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlerefresh) — getting a current value.
- [Moving, rotating and scaling entities](https://diceytable.com/docs/editor/working/transform-and-gizmos) — the same coordinates in
  Edit Mode.
- [Parenting](https://diceytable.com/docs/editor/working/parenting) — why a child still reports a world position.

### objectdata.rotation

```ts
readonly rotation: Vec3;
```

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

How the entity is oriented, as `[x, y, z]` Euler angles in **degrees**, reported in world terms. `y` is the one
that matters most of the time: it is the entity's heading on the table.

#### How, why and when to use it

A board has been dragged around all evening and you want to square it up, so you need to know which right angle it
is nearest to before you can snap it. Reading `rotation[1]` and rounding is how you find that. The alternative is
`rotate()`, the fixed 90° step, which is right when you want a quarter turn *from wherever it is* and wrong when
you want it to land on a specific angle — from 37° it gives you 127°. Read `rotation` when you are computing a
target; skip it entirely when a relative turn is what you meant.

#### Gotchas

**It is a cached value, not a live read,** refreshed only when the handle is delivered by a query, an event or
`refresh()`. A tumbling die's rotation here is whatever it was when you last looked.

**Never infer face state from it.** A flipped card sits near `x: 180`, but `flip()` and the transform path are
separate: an entity rotated to `[180, 0, 0]` with `setRotation` looks flipped and still reports its old
`faceUp`. Read [`faceUp`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatafaceup).

**Angles are not normalized to any range,** and equivalent orientations do not compare equal. Reduce both sides
before you test for equality.

**The array is a fresh copy and writing to it does nothing.** Use
[`setRotation`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesetrotation).

#### See also

- [`ObjectHandle.setRotation`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesetrotation) — setting an absolute
  angle.
- [`ObjectHandle.rotate`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlerotate) — the fixed quarter turn.
- [`ObjectData.faceUp`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatafaceup) — the flag that actually tracks the
  face.
- [Moving, rotating and scaling entities](https://diceytable.com/docs/editor/working/transform-and-gizmos) — the same angles in Edit
  Mode.

### objectdata.scale

```ts
readonly scale: Vec3;
```

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

The entity's scale. For an imported model this is a MULTIPLIER on the model's own size,
not a size in feet — copy it onto a replacement with `spawnObject`'s `scale` so the
two match.

The entity's scale per axis.

#### Returns

`Vec3` — `[x, y, z]`. `[1, 1, 1]` for an entity with no scale of its own.

#### How, why and when to use it

Read it when a script replaces one entity with another that must match it — promoting a pawn, swapping a token
for an upgraded one. Pass it straight to [`spawnObject`](https://diceytable.com/docs/scripting-api/world#worldspawnobject)'s
[`scale`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionsscale), together with `position` and `rotation`, and the
replacement stands exactly where and as large as the original did.

#### Gotchas

**For an imported model it is a multiplier, not a size.** A chess pawn at `[3, 3, 3]` is three times its modelled
size, not three feet tall. Compare scales between entities of the same model, not against distances.

**It is a copy taken when the handle was last updated**, like `position` — capture it before destroying the entity
you are replacing.

#### See also

- [`SpawnObjectOptions.scale`](https://diceytable.com/docs/scripting-api/types#spawnobjectoptionsscale) — where it goes.
- [`ObjectData.position`](https://diceytable.com/docs/scripting-api/objecthandle#objectdataposition) — the other field a replacement copies.

### objectdata.locked

```ts
readonly locked: boolean;
```

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

Whether the entity is pinned. `true` means the host has marked it locked and switched its rigidbody to static, so
physics leaves it alone and players cannot move it or act on it — apart from unlocking it again.

#### How, why and when to use it

Your script locks the boards at load and you do not want to send a redundant intent for the ones that are already
locked, because every intent costs a snapshot broadcast to every peer. Reading `locked` first is the filter. It is
also the honest way to answer "did the lock actually take?" after a `lock()` — call `refresh()` and read this,
rather than assuming. The alternative is to track lock state in your own variable, which is fine until a player
unlocks something from the object menu and your variable is quietly wrong for the rest of the session.

#### Gotchas

**It is a cached value, not a live read.** A player can unlock an entity between your read and your next line.

**A lock stops players, not your script.** The gate that refuses actions on a locked entity
(`packages/shared/src/tableObjects.ts`, `isObjectActionAllowedForTarget`) runs on intents arriving from a player
or spectator. A script's intents are raised on the host and never pass through it, so a `true` here does not mean
your own `flip()` or `setPosition()` will be refused.

**Locking is not the same as a static rigidbody.** An entity authored static is already immovable by physics and
still perfectly draggable. The lock is what stops the hand.

#### See also

- [`ObjectHandle.lock`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlelock) — setting it.
- [`ObjectHandle.unlock`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleunlock) — clearing it.
- [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) — the locked rule and its one exception.
- [RIGIDBODY](https://diceytable.com/docs/editor/inspector/rigidbody) — the authored body type a lock replaces.

### objectdata.faceUp

```ts
readonly faceUp: boolean | null;
```

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

Which way up the entity is showing. `true` is face up, `false` is face down, and the value is the inverse of the
entity's stored face-down flag — the same flag `flip()` toggles and the hidden-information system reads when it
decides which peers may see a card's face.

`null` means **the handle has never carried real entity state**: a `world.spawnObject` result you have not
refreshed, or a handle the sandbox built for an id it has only ever seen mentioned. Every entity in a host
snapshot has a boolean here, so `null` is a "not read yet" marker rather than a third face state.

#### How, why and when to use it

You are turning every card face up at the end of a round, and `flip()` is a toggle — so calling it on all of them
turns the already-face-up ones back down. Reading `faceUp` first is what makes the pass idempotent. The
alternative is to track face state yourself from `globalEvents.onObjectAction`, which is real work and goes wrong
the first time a player flips something while your handler is awaiting something else. Read the flag; do not model
it.

#### Gotchas

**It is a cached value, not a live read.** After `flip()` the handle still reports the old value until the host
answers — `await handle.refresh()` first, or compare against what you know you asked for.

**Applies to: `card` and `deck` meaningfully; every other kind carries the flag anyway.** `flip()` is not
kind-guarded, so a `die`, `board`, `bag`, `custom` or `card-holder` can be turned over and will report
`faceUp: false` despite having no face. A `token` is the exception: flipping one turns it over and leaves this
flag alone, so a token's `faceUp` does **not** tell you which side is up. Treat a non-card's value as noise.

**Face up is not the same as revealed.** For a card, visibility to other peers is decided by the face flag
*together* with seat ownership and reveal state, and a script cannot request the `reveal-*` actions at all. A
`true` here does not by itself guarantee every player can see the card.

#### See also

- [`ObjectHandle.flip`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandleflip) — the only method that changes this.
- [`ObjectData.rotation`](https://diceytable.com/docs/scripting-api/objecthandle#objectdatarotation) — the orientation that does *not*
  track the face.
- [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) — why `reveal-*` is not in the script vocabulary.
- [Object kinds](https://diceytable.com/docs/mods/reference/object-kinds) — which kinds have a face at all.

### objectdata.stackCount

```ts
readonly stackCount: number;
```

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

How many items this entity represents — the height of a card stack, the
size of a token pile, the number of cards left in a deck. `1` for anything
that does not stack.

How many items this entity represents as one thing on the table: the height of a card stack, the size of a token
pile, the number of cards still in a deck. It is `1` for everything that does not stack, and it is never `0` - an
entity that reaches zero is removed, and you hear about that as `onDestroyed` rather than as a count.

It is the same number the entity's replicated state carries, so it is exact rather than inferred, and it is the
cheapest way to ask "how much is left" without reading contents at all.

#### How, why and when to use it

You want to announce that the draw pile is running low, or to stop a player splitting a stack that is already a
single card. Both are one comparison here. The alternative for a container is
[`ContainerObject.cards`](https://diceytable.com/docs/scripting-api/object-types#containerobjectcards), which tells you *which* cards
are left as well as how many - read `stackCount` when the count is all you need, and `cards` when identity
matters. For a token pile there is no alternative: `stackCount` is the only published measure of its size.

#### Gotchas

**It is a cached value, like every other field on a handle.** After a `draw()` the handle still reports the old
count until the host answers - `await handle.refresh()`, or read the count off the handle an event delivers.

**A deck's count and its `cards.length` can disagree for one moment**, in the same way and for the same reason:
they are two fields of one cached record, refreshed together, and the record is only as new as the last refresh.

**It counts entries, not faces.** A stack of five cards is `stackCount: 5` and one entity with one id. Splitting
it produces new entities with new ids; it does not change this entity into five.

#### See also

- [`ContainerObject.cards`](https://diceytable.com/docs/scripting-api/object-types#containerobjectcards) - what a container holds, not just how much.
- [`ObjectHandle.refresh`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlerefresh) - making the cached count current.
- [`ObjectHandle.draw`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandledraw) - the action that decrements a container's count.
- [Object kinds](https://diceytable.com/docs/mods/reference/object-kinds) - which kinds stack at all.

### objectdata.tags

```ts
readonly tags: readonly string[];
```

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

The author tags on this entity: lowercase strings matching `[a-z0-9_-]`, up to 32 characters each and up to 100 of
them. Tags are how an author or a script marks a set of entities as belonging together, and they are the only
grouping mechanism a script can both write and read.

#### How, why and when to use it

Your scoring pass needs the dice that count and not the ones a player brought for fun, so the ones that count get
a `scoring-die` tag at spawn and the pass asks for that tag. Reading `handle.tags` is the other half of that: it
tells you whether an entity that arrived from an event — a drop, a roll — is one of yours. The alternative is
`kind`, which most scripts try first and which is too coarse the moment a table has two sorts of the same kind.
Read `tags` for membership in a set you defined; read `kind` for what a thing fundamentally is.

#### Gotchas

**Read-only, and there is no way to change tags after spawn.** The array is a fresh copy on every refresh, so
`handle.tags.push("x")` changes nothing about the table. `world.spawnObject`'s `tags` option is the only place a
table script can write one.

**Platform `dt:` tags are not in here.** The reserved `dt:` namespace lives on the engine entity, which no script
can reach; this list is the author tag set only. So you never need to filter platform tags out of it, and you can
never match one with `world.getAllObjects({ tag })` either.

**Matching is exact and stored tags are lowercase.** `handle.tags.indexOf("Blue")` finds nothing on an entity
tagged `blue`. Share a `const` between the code that spawns and the code that looks.

**The frame's tag filter and the host's schema disagree on length.** A tag matching the character class passes the
sandbox's filter at any length, and the host's schema then rejects anything over 32 characters — rejecting the
whole spawn, not only the offending tag. Keep tags short.

#### See also

- [`world.getAllObjects`](https://diceytable.com/docs/scripting-api/world#worldgetallobjects) — querying by a single tag.
- [`world.spawnObject`](https://diceytable.com/docs/scripting-api/world#worldspawnobject) — the only place a script writes tags.
- [Tags and groups](https://diceytable.com/docs/editor/working/tags-and-groups) — authoring tags by hand.
- [IDs, names and tags](https://diceytable.com/docs/editor/concepts/ids-names-tags) — the `dt:` namespace and why it is unforgeable.

### objectdata.seat

```ts
readonly seat: string | null;
```

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

The seat this entity belongs to — the seat colour id an author picked in the Inspector's
Seat field (`"white"`, `"red"`, …) — or null when it belongs to no seat.

A label only: it does not hide the entity, change who may move it, or put it in anyone's
hand. Use it to find a side's pieces (`getAllObjects({ seat: "white" })`) or to learn which
seat plays which side from the board itself. Read-only from a script.

The seat this entity **belongs to** — the seat id an author picked in the Inspector's **Seat** field, or for a
whole folder or selection at once in `GROUP EDIT`. White's chess pieces belong to the `white` seat; a player's
army belongs to theirs.

#### Returns

`string | null`. The value is a **seat id** — one of the ten seat colours `red`, `blue`, `green`, `yellow`,
`purple`, `orange`, `pink`, `cyan`, `white`, `brown` — never the name the scene shows for that seat. A chess pack
that names its `brown` seat "Black" stores `"brown"` here. `null` means the entity belongs to no seat, which is
the default for every entity and for every save written before the field existed.

#### How, why and when to use it

Use it when a game needs to know **whose** pieces are whose from the board itself. The motivating case is chess:
without it the script has to guess that whichever seat moves first plays White, or hard-code thirty-two entity
ids. With it, `world.getAllObjects({ seat })` returns one side's pieces, and comparing a piece's `seat` with
[`onTurnStarted`](https://diceytable.com/docs/scripting-api/events#globaleventsonturnstarted)'s `seat` tells you whether the player
on move touched their own piece.

Reach for it instead of the seat template when the pieces are a **fixed set** that exists whoever sits down. The
template clones a holder for every seat a player claims; a seat on an entity is a label on one entity that never
multiplies.

#### Example

```ts
// content/scripting-api/examples/objectdata.seat.ts

// Scene script for a chess pack. In the Inspector the author gave White's
// sixteen pieces the "white" seat and Black's sixteen the "brown" seat (which
// the scene names "Black"). The script reads the sides from the board, so it
// never has to assume that whoever moves first is White.

const PIECE_TAG = "chess-piece";

async function describeSides(): Promise<void> {
  const pieces = await world.getAllObjects({ tag: PIECE_TAG });
  const countBySeat = new Map<string, number>();
  for (const piece of pieces) {
    const seat = piece.seat ?? "no seat";
    countBySeat.set(seat, (countBySeat.get(seat) ?? 0) + 1);
  }
  for (const [seat, count] of countBySeat) {
    world.log(`${seat}: ${count} piece(s)`);
  }
}

globalEvents.onTurnStarted.add((turn) => {
  const seat = turn.seat;
  if (seat === null) {
    return;
  }
  void world.getAllObjects({ seat }).then((mine) => {
    world.log(`Seat ${seat} to move with ${mine.length} piece(s) left.`);
  });
});

void describeSides();
```

On a standard set the console prints `white: 16 piece(s)` and `brown: 16 piece(s)`, then one line per turn.

#### Gotchas

**It is a label, not a permission.** A seat on an entity does not hide it, does not put it in anyone's hand, does
not change its physics and does not stop another player picking it up. If your game should refuse a move of the
opponent's piece, check `seat` in your own handler and put the piece back.

**It is not `ownerSeat`.** Object state has a separate `ownerSeat`, which means "this card is in that seat's hand"
and is what hides a hand from the other players. A table script does not see `ownerSeat`; it is a different
thing and setting one never sets the other.

**Read-only from a script.** There is no setter: the seat is authored in Edit Mode (or by an AI agent through
`entity_update`). A script that needs to track a capture can keep its own record in saved data.

**A seat-template entity reads `null`.** A holder or piece the seat template stamps onto a seat belongs to that
seat through the template, not through this field — use its provenance or your own tag to tell those apart.

**An entity put into a container loses its seat.** Like `parentId`, the seat describes where an entity stands, so
it is not part of what a bag stores; the entity taken back out has none.

**It is a cached value.** It is refreshed whenever the handle is (any `world` read, or `await handle.refresh()`).

#### See also

- [`world.getAllObjects`](https://diceytable.com/docs/scripting-api/world#worldgetallobjects) — its `seat` filter.
- [PIECE § Seat](https://diceytable.com/docs/editor/inspector/piece#seat) — setting it on one entity.
- [Multi-select § Seat](https://diceytable.com/docs/editor/working/multi-select#seat) — setting it on a folder or a selection.
- [`seat` in object state](https://diceytable.com/docs/mods/reference/object-state#seat) — the replicated field this is read from.

### objectdata.metadata

```ts
readonly metadata: Readonly<Record<string, unknown>>;
```

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

The entity's freeform property bag, as the host published it. It is the same record `world.spawnObject` writes
through its `metadata` option, and it carries both what an author put there and what the platform keeps there.
Values are `unknown`, so every read needs a type check before you use it.

Keys you will actually meet: `scriptId` (the object script attached to this entity), `standardPresetId` (the
standard-library preset it was built from), `grabbableWhileParented` (the per-child opt-out from grab
escalation), `cards` and `stackModelVersion` (a deck's contents), `cardId` and `sourceDeckId` (on a card a draw
produced), and `revealTeam` (which team, if any, a card is revealed to).

#### How, why and when to use it

You spawned a token with `metadata: { role: "wizard" }` and, three events later, a handler that only has a handle
needs to know what it is. `metadata` is where that answer survives, because it is part of the entity's replicated
state rather than something you have to track alongside it. The alternative is tags, which are cheaper to filter
on and are the right choice for membership — "is this one of the scoring dice?" — but hold no values. Put a
*value* in metadata at spawn; put *membership* in a tag.

#### Gotchas

**It is read-only in practice as well as in the type.** The record you get is the frame's own copy of the entity
state, so writing to it changes nothing on the table, replicates to nobody, and is silently thrown away by the
next refresh. There is no method that writes metadata after spawn — `world.spawnObject` is the only opportunity.

**Every value is `unknown`.** Narrow before you use one: `typeof value === "string"`, an `Array.isArray` check,
and a default for the case where an older version of your script never wrote the key.

**`parentId` and `components` are not here, and not on `ObjectData` at all.** An entity's parent link and its
engine components are top-level fields on the replicated entity state, and neither is published to a table
script. A script therefore cannot see that an entity is part of an assembly — but it *can* see
`grabbableWhileParented`, because that one rides `metadata`.

**Grab escalation means a drop event may not be about the piece the player touched.** Grabbing a child of an
assembly escalates to its root ancestor unless that child carries `grabbableWhileParented`, so
`globalEvents.onObjectPickedUp` and `onObjectDropped` report the **escalated** entity. A script that credits a
move to the piece a player visually grabbed is wrong for every parented assembly. That escalation is deliberate —
see [Parenting](https://diceytable.com/docs/editor/working/parenting) — so read `metadata.grabbableWhileParented` if you need to know
which pieces are exempt.

#### See also

- [`world.spawnObject`](https://diceytable.com/docs/scripting-api/world#worldspawnobject) — the one place a script writes metadata.
- [`ObjectHandle.setSavedData`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesetsaveddata) — per-entity state a
  script *can* change after spawn.
- [Parenting](https://diceytable.com/docs/editor/working/parenting) — grab escalation and the `grabbableWhileParented` opt-out.
- [Object state](https://diceytable.com/docs/mods/reference/object-state) — every field of the replicated entity state, including the
  ones `ObjectData` does not publish.
- [Events](https://diceytable.com/docs/scripting-api/events) — which entity a pick-up or drop actually reports.

### objectdata.tooltip

```ts
readonly tooltip: TooltipData | null;
```

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

This entity's hover tooltip, or null when it has never been given one (the default).

The entity's hover tooltip as it is currently configured: whether it shows, its title and description templates,
whether the built-in detail lines appear, and the entity's own variables. It is the configuration, not the text a
player sees — `{name}` placeholders and `**bold**` markers are still in it, unrendered.

#### Returns

[`TooltipData`](https://diceytable.com/docs/scripting-api/types#tooltipdata) `| null`. `null` means **the entity has no tooltip field
at all**, which is the default: every entity starts without one, and every entity in a save written before
authored tooltips existed has none. A non-`null` value with `enabled: false` is a tooltip that has been written
and then switched off — its text is kept, it just does not show.

#### How, why and when to use it

Read it before you write, when your script shares an entity's tooltip with an author or another script: check
`handle.tooltip?.enabled` before deciding whether to switch one on, or read `tooltip.variables` to continue a
count that was set in the Inspector as a starting value. The alternative — keeping your own copy of what you last
wrote — goes stale the moment an author edits the tooltip in the Inspector, and the Inspector is where most
tooltip text is expected to live.

#### Gotchas

**It is a cached value, not a live read.** After `setTooltip` or `setTooltipVariable` the handle still reports the
old configuration until the next snapshot arrives — `await handle.refresh()` first.

**`variables` holds only this entity's own variables.** The built-ins a template can also read — `name`, `kind`,
`value`, `count`, `owner`, `counters.<key>` and `values.<key>` — are resolved when the tooltip is drawn and never
appear here.

**Switching a tooltip off can make this `null`.** A tooltip that is disabled *and* has no title, description,
variables or `showDetails: false` left is removed rather than stored, so the next read is `null` rather than
`{ enabled: false, … }`.

**The title falls back to a name your script cannot read.** A `null` `title` shows the entity's `displayName`, or
its `label` when it has none. [`ObjectData.name`](https://diceytable.com/docs/scripting-api/objecthandle#objectdataname) is the
`label`; the `displayName` is not published to a table script at all.

#### See also

- [`TooltipData`](https://diceytable.com/docs/scripting-api/types#tooltipdata) — the shape of the value.
- [`ObjectHandle.setTooltip`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesettooltip) — changing it, with an example.
- [`ObjectHandle.setTooltipVariable`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesettooltipvariable) — changing one variable.
- [`tooltip` in object state](https://diceytable.com/docs/mods/reference/object-state#tooltip) — the replicated field this is read from.

## refObject

_Surface A — table script · const_

The object this script is attached to. Defined ONLY in object scripts
(scripts attached via an object's Script section); undefined in scene scripts.

```ts
declare const refObject: ObjectHandle;
```

`refObject` is the [`ObjectHandle`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandle) for the entity a script is attached to. An entity attaches a
script through its `metadata.scriptId`, and when the host starts that pair it seeds the entity's state into the
sandbox first and then runs the body — so `refObject`'s ten fields hold real values on your very first line, not
placeholders, and its eight delegates are already wired to that entity alone.

**Its declared type follows the entity it was written for.** A script created from an entity's Script section
records that entity's kind, and the editor declares `refObject` as the matching handle — `DeckObject` for a deck,
`CardObject` for a card — so `refObject.cards` and `refObject.onFlipped` are offered where they apply and refused
where they cannot fire. A global script, and any script authored before scripts recorded a kind, keeps the
generic `ObjectHandle`. See [Object Types](https://diceytable.com/docs/scripting-api/object-types).

### How, why and when to use it

You want one behavior that every copy of a piece carries with it: a card that logs its own name when it is drawn,
a die that adds to a running total whenever it settles. The alternative is a scene script that subscribes to
`globalEvents.onDiceRolled` and opens every handler with a check that the entity is one of yours — a filter you
have to keep in step with the table as pieces are spawned and destroyed. `refObject.onRolled`
needs no filter, because the delegate fires only for that entity. Attach an object script when the rule belongs to
the piece; write a scene script when the rule is about the table, or when it has to see pieces that do not exist
yet.

### Gotchas

**It is typed as always present and is `undefined` in a scene script.**

> **Known gap.** The declaration is `declare const refObject: ObjectHandle;` — never optional — while the sandbox
> passes `undefined` for it whenever a script runs without an entity
> (`packages/shared/src/scripting.ts`; `apps/web/src/scripting/sandbox/tableScriptSandbox.html`, `runScript`).
> Autocomplete therefore offers `refObject.flip()` inside a scene script and the script throws the moment that
> line runs. In an object script it is populated before the body executes and every method on it works. In a
> scene script, reach entities through `world.getObjectById` or `world.getAllObjects` instead.
> See [Known limitations](https://diceytable.com/docs/reference/known-limitations#refobject-is-undefined-in-scene-scripts).

**One script attached to five entities runs five times.** The host starts the pair, not the script, so the body
executes once per attached entity with a different `refObject` each time. Anything you declare at the top level
is per-run state, which is what you usually want — and it means a counter you meant to share across the five has
to live in saved data instead.

**It is the same object every other lookup returns.** `world.getObjectById(refObject.id)` resolves the identical
handle, so refreshing one refreshes both. The lookup's *declared* type is the generic `ObjectHandle`, though —
an id says nothing about a kind — so the narrowed members are only on `refObject` and on a kind-filtered
[`world.getAllObjects`](https://diceytable.com/docs/scripting-api/world#worldgetallobjects).

**The declared kind is a hint, not a gate.** Attaching a script written for a deck to a card is allowed and it
runs; only the typing and the starter body came from the kind. The Script section says so when the two disagree.

### See also

- [`ObjectHandle`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandle) — everything `refObject` can do, since it is one.
- [`ObjectData`](https://diceytable.com/docs/scripting-api/objecthandle#objectdata) — the ten fields it carries.
- [Object Types](https://diceytable.com/docs/scripting-api/object-types) — the per-kind handle it is declared as, and what each adds.
- [`world.getAllObjects`](https://diceytable.com/docs/scripting-api/world#worldgetallobjects) — the scene-script way to reach entities.
- [Scripts](https://diceytable.com/docs/editor/working/scripts) — attaching a script to an entity in the editor.
- [Known limitations](https://diceytable.com/docs/reference/known-limitations#refobject-is-undefined-in-scene-scripts) — the scene-script gap in full.
