# ObjectAction (table script)

> The 13 actions a table script may request, the 9 that have an ObjectHandle method, the 4 that do not, and what the script host does with each one.

- Source: https://diceytable.com/docs/reference/enums/object-action
- Last verified: 2026-10-06

`ObjectAction` is the union a **table script** may pass through the script host — 13 of the engine's 27
actions. It is declared inside `DICEYTABLE_SCRIPT_API_DTS` and re-checked at run time against
`SCRIPT_SAFE_OBJECT_ACTIONS` in `apps/web/src/scripting/TableScriptHost.ts`, and the two lists match
exactly, so a compromised sandbox frame cannot broaden the set.

This union does **not** exist on the mod surface. A mod's ten-action list is
[`SANDBOX_SAFE_OBJECT_ACTIONS`](https://diceytable.com/docs/reference/enums/sandbox-safe-object-actions), which is a different
list with a different enforcement path.

## The values

The **How a script calls it** column is the practical limit: an action with no method is in the union and
would pass the allowlist, but the typed API offers no way to request it.

| Value | What the host does | Kinds it is meaningful for | How a script calls it |
|---|---|---|---|
| `flip` | Toggles `faceDown` and rotates 180° about local X. On a `token`, turns it over in place without touching `faceDown`. | `card`, `deck`, and a `token` that may flip (flat shape, or `flippable: true`) — the host refuses it for any other token. On any other kind the rotation and the flag both still change. | `handle.flip()` |
| `rotate` | Rotates 90° about local Y. | every kind. | `handle.rotate()` |
| `lock` | Marks the entity locked and switches its rigidbody to static. | every kind. | `handle.lock()` |
| `unlock` | Clears the lock and restores the authored body type. | every kind. | `handle.unlock()` |
| `tap` | Sets `tapped` to `true`. | every kind. | **no method** |
| `untap` | Sets `tapped` to `false`. | every kind. | **no method** |
| `shuffle` | Shuffles a deck's contents. Refused outright on every other kind — the runtime returns before it changes anything, so a bag makes no sound and does not move. | `deck`. | `handle.shuffle()` |
| `draw` | Draws the first item off the container. Does nothing on any other kind. | `deck`, `bag`. | `handle.draw()` |
| `deal` | Deals from the container to the seated players. Does nothing on any other kind. | `deck`, `bag`. | `handle.deal()` |
| `split` | Splits a stacked deck in two. Does nothing unless the deck holds more than one card. | `deck`. | **no method** |
| `combine` | Merges the entity into a stack. | `card`, `deck`. | **no method** |
| `roll` | Throws the die with a randomized impulse. On a card it throws the card. | `die`. | `handle.roll()` |
| `delete` | Destroys the entity, re-parents its children, removes its joints. | every kind. | `handle.destroy()` — the method name differs from the action name |

**9 of the 13 have a method.** `tap`, `untap`, `split` and `combine` do not.

> **Known gap.** `tap`, `untap`, `split` and `combine` are declared in `ObjectAction` and are on the script
> host's allowlist (`apps/web/src/scripting/TableScriptHost.ts`, `SCRIPT_SAFE_OBJECT_ACTIONS`), but
> `ObjectHandle` exposes no method for any of them (`packages/shared/src/scripting.ts`). Every layer below
> the typed API is ready for them — the allowlist passes them and the runtime applies them correctly — and
> only the calling surface is missing. `delete` looks like the same problem and is not: it is reachable, as
> `destroy()`. Until a method exists, model tapping as your own state — a tag, or saved data — and read it
> back with `handle.refresh()`. A mod **can** call `split` and `combine`, because mod scripting passes the
> action name as a string.
> See [Known limitations](https://diceytable.com/docs/reference/known-limitations#actions-with-no-objecthandle-method).

## What the engine has and this union does not

Fourteen engine actions are outside this union: `lift`, `flick`, `press`, `toss`, `peek`, `search`,
`search-pull`, `search-close`, `reveal-all`, `reveal-team-a`, `reveal-team-b`, `tip-out`, `empty` and
`clear-source`. A table script cannot request any of them.

> **By design.** `lift` and `flick` are drag mechanics — the physical result of a pointer gesture,
> meaningless without the gesture that produced it. `press` is a button's own click — a script *observes*
> it through `ButtonObject.onPressed` and reacts, rather than synthesizing one. `toss` is a player flipping a
> coin. A script that needs a random result should choose one itself, not throw a coin and wait for
> it to land. `tip-out`, `empty` and `clear-source` manage a container's contents, and the last two are
> host-only even for players. `peek`, the three `search*` actions and the three `reveal-*` actions
> are hidden-information reveals, and hidden information is the one part of the table the host must own
> outright: an action that can flip who sees a card is an action that can be used to cheat. Scripts do not
> get them, and that is not expected to change. Model a reveal as your own state — a tag, or saved data — and
> let the host's reveal path stay the only thing that changes card visibility.

## Receiving an action is wider than requesting one

`globalEvents.onObjectAction` and `ObjectHandle.onAction` are **not** typed with this union. They are typed
with [`ObservedObjectAction`](https://diceytable.com/docs/scripting-api/types#observedobjectaction), which is this union plus the
fourteen engine actions above — the event is raised for all 27, so a handler can be handed a `lift`, a
`press`, a `toss` or a `reveal-*` it could never have asked for.

That is why there are two types rather than one: collapsing them would either hide real events or advertise
calls the host's allowlist refuses. Annotate with `ObjectAction` what you are about to request and with
`ObservedObjectAction` what an event gave you, and keep a `default` branch in the switch — the engine's
list and this union live in two files, and the engine gains actions (`toss` is the latest).

## See also

- [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) — the three lists side by side.
- [`ObservedObjectAction`](https://diceytable.com/docs/scripting-api/types#observedobjectaction) — the union an event delivers.
- [TableObjectAction (engine)](https://diceytable.com/docs/reference/enums/table-object-action) — all 27.
- [Sandbox-safe object actions](https://diceytable.com/docs/reference/enums/sandbox-safe-object-actions) — the mod list of 10.
- [`ObjectHandle`](https://diceytable.com/docs/scripting-api/objecthandle) — the nine methods in the last column.
- [Object actions](https://diceytable.com/docs/mods/reference/object-actions) — what each action does, per kind.
