# TableObjectAction (engine)

> All 27 actions the runtime can apply to one entity, what each does, which kinds a player may send it for, and which script surfaces can request it.

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

`TableObjectAction` is the action field of an `object-action` intent — the complete set of things the
runtime knows how to do to one entity. **27 values**, declared as `ObjectActionIntent["action"]` in
`packages/shared/src/tableObjects/intents.ts`, aliased as `TableObjectAction`, and listed at runtime as
`TABLE_OBJECT_ACTIONS` in `packages/shared/src/tableObjects/intentSchema.ts`.

This is the widest of three vocabularies. A table script may request 13 of them and a mod may request 10;
[Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) owns the comparison and the reasons for each
narrowing, and [Object actions](https://diceytable.com/docs/mods/reference/object-actions) owns the full kind-by-action
participant matrix. This page is the value list with the surface column.

Two rules sit above every row. A **locked** entity refuses every action except `unlock` and a per-kind
exempt list — `press` on a button (a button ships locked on purpose, so locking it must not disable it), and
the container actions on a locked `deck` or `bag`; the full list is in
[Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies#the-engine-vocabulary). And an action aimed at an
entity that does not exist does nothing.

## The values

The **Players may send it for** column is the per-kind participant gate. It does **not** apply to the host,
so a table script or a host-side mod can address any action to any entity.

| Value | What the host does | Players may send it for | Table script | Mod |
|---|---|---|:--:|:--:|
| `lift` | Teleports the entity 0.75 ft straight up. | every kind | ✗ | ✗ |
| `flip` | Toggles `faceDown` and rotates 180° about local X. On a `deck` it also flips every card entry. On a `token` or a `coin` it turns the piece over in place and leaves `faceDown` alone; one that may not flip is refused on every path. | `card`, `deck`, `token` or `coin` unless `flippable: false` | ✓ | ✓ |
| `rotate` | Rotates 90° about local Y. | every kind | ✓ | ✓ |
| `lock` | Marks the entity locked and switches its rigidbody to static. | every kind, while unlocked | ✓ | ✓ |
| `unlock` | Clears the lock and restores the authored body type. | every kind, while locked | ✓ | ✓ |
| `tap` | Sets `tapped` to `true`. | **no kind** | ✓ (no handle method) | ✗ |
| `untap` | Sets `tapped` to `false`. | **no kind** | ✓ (no handle method) | ✗ |
| `shuffle` | Shuffles a deck's contents and starts the shuffle spin. Refused outright on any other kind, host-side as well as through the gate. | `deck` | ✓ | ✓ |
| `draw` | Draws the first item off the container. | `deck`, `bag` | ✓ | ✓ |
| `deal` | Deals from the container to the seated players. | `deck`, `bag` | ✓ | ✓ |
| `split` | Splits a stacked deck into two. | `deck`, with more than one card | ✓ (no handle method) | ✓ |
| `combine` | Merges the entity into a stack. | `card`, `deck` | ✓ (no handle method) | ✓ |
| `roll` | Throws a die with a randomized impulse and lets physics settle it. | `die` | ✓ | ✓ |
| `toss` | Flips a coin: thrown straight up 6 to 12 in (capped near 11.5 in by the global speed limit), spinning end over end with a slight drift. No sound of its own and no heads/tails result. Not exempt from the locked rule. Refused outright on anything but an unlocked `coin`, host-side as well as through the gate. | `coin` (`isTossableCoin`) | ✗ (observe only) | ✗ |
| `press` | Dips a button's cap, plays its sound and raises `onPressed`. Refused outright on any other kind, host-side as well as through the gate. Exempt from the locked rule — a locked button is still pressable. | `button` | ✗ (observe only) | ✗ |
| `flick` | Flicks the entity across the surface. | every kind except `board` and `table` | ✗ | ✗ |
| `reveal-all` | Clears the reveal team and, unless the entity is seat-owned, turns it face up. | `card`, `deck` | ✗ | ✗ |
| `reveal-team-a` | Reveals the entity to team A only. | `card`, `deck` | ✗ | ✗ |
| `reveal-team-b` | Reveals the entity to team B only. | `card`, `deck` | ✗ | ✗ |
| `peek` | Privately reveals the container's top *N* cards to the peeking player alone, and logs one public, identity-free line naming the count and the pile. Carries a `count`. | `deck`, `bag` | ✗ (observe only) | ✗ |
| `search` | Opens a private **search**: reveals the pile's whole contents to the searching player alone, subject to the authored audience, and logs one identity-free line. | `deck`, `bag` | ✗ (observe only) | ✗ |
| `search-pull` | Takes one named item out of a pile the actor is currently searching. Carries a `cardId` the host validates against that actor's live reveal. The public line never names it. | `deck`, `bag` | ✗ (observe only) | ✗ |
| `search-close` | Ends the session: applies the pile's authored order policy and revokes the reveal. | `deck`, `bag` | ✗ (observe only) | ✗ |
| `tip-out` | Empties a container onto the table without destroying anything: a holder's pieces are pushed clear, a finite piece bag's are respawned beside it. | a `bag` that is not infinite | ✗ (observe only) | ✗ |
| `empty` | Deletes a finite piece bag's stored contents. | **no player** — host-only | ✗ (observe only) | ✗ |
| `clear-source` | Forgets an infinite container's source piece. | **no player** — host-only | ✗ (observe only) | ✗ |
| `delete` | Destroys the entity, re-parents its children to its own ancestor, and removes its joints. | every kind | ✓ (as `destroy()`) | ✗ |

**Totals: 27 engine · 13 table script · 10 mod.**

The four hidden-information rows — `peek` and the three `search*` actions — are host-authoritative private
reveals. A table script may *observe* them; no surface may request one, because a script that could would
manufacture a reveal for itself. What a search event does and does not carry is on
[`DeckObject.onSearched`](https://diceytable.com/docs/scripting-api/object-types#deckobjectonsearched), and who may open one is
authored in [Deck and Bag Search](https://diceytable.com/docs/editor/workflows/deck-search).

`press` is engine-and-observe only: it has no place in the table-script or mod *request* vocabularies, but
a table script can watch it — [`ButtonObject.onPressed`](https://diceytable.com/docs/scripting-api/types#buttonobject) fires, and
`press` is a member of [`ObservedObjectAction`](https://diceytable.com/docs/scripting-api/types#observedobjectaction). A player
presses a button and the host raises the action; a script reacts.

`toss` is the same shape: only a player (or an AI agent acting as one, through `table_object_action`) can
flip a coin, and a table script hears it as `"toss"` on `onObjectAction` / `onAction`, and through
[`CoinObject.onTossed`](https://diceytable.com/docs/scripting-api/types#coinobjectontossed) on the coin's own handle. It applies to
every entity of kind `coin`: the built-in coin presets (`coin`, `coin-1`, `coin-2`, `coin-5`, `coin-10`) and a
project's own coin model whose Type is **Coin** alike. A coin-shaped model left as a `token` does not offer
it — see [Object kinds § Coin](https://diceytable.com/docs/mods/reference/object-kinds#coin).

## Two things the table column does not say

`tap` and `untap` are on the table-script allowlist and are refused for **every** kind on the participant
path, so no player or spectator can ever send them.
See [Known limitations](https://diceytable.com/docs/reference/known-limitations#tap-and-untap-are-refused-for-every-participant).

Four of the thirteen a table script may request — `tap`, `untap`, `split`, `combine` — have no
`ObjectHandle` method, so the typed API cannot call them even though the allowlist would pass them. 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).

## See also

- [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) — the three lists side by side, and why each narrowing exists.
- [ObjectAction (table script)](https://diceytable.com/docs/reference/enums/object-action) — the 13 a table script may request.
- [Sandbox-safe object actions](https://diceytable.com/docs/reference/enums/sandbox-safe-object-actions) — the 10 a mod may request.
- [Object actions](https://diceytable.com/docs/mods/reference/object-actions) — the full kind-by-action participant matrix.
- [`api.objectAction`](https://diceytable.com/docs/scripting-api/api#apiobjectaction) — how a mod requests one.
