# Object actions

> The 27 TableObjectAction values and their per-kind gating — a full kind-by-action matrix, with the state-dependent exceptions called out.

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

`TableObjectAction` is the 27-value action union (`ObjectActionIntent["action"]` in
`packages/shared/src/tableObjects/intents.ts`) — everything the runtime can do to a single
entity in response to an `object-action` intent. What each action *does* and how it is
gated across the **three action vocabularies** (engine, table script, mod) lives on
[Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) — that page owns the
surface-vs-surface axis. **This page owns a different axis: which entity kinds each action
is valid for**, from `isObjectActionAllowedForTarget()`
(`packages/shared/src/tableObjects.ts`).

## What this gate is for, and what it is not

`isObjectActionAllowedForTarget(action, target)` is the **participant gate**: it is checked
on a player or spectator's own client before an `object-action` intent is sent, and again
by the host when the intent arrives, for intents that originate from a participant. It is
**not** applied to actions the host raises directly — the host's own UI, a table script, and
a mod running host-side all reach the runtime without going through this function, so (for
example) a table script *can* request `flip` on a `die` and the runtime will apply it even
though a player could never have sent that combination. See
[Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies#the-engine-vocabulary)
for what happens when an action reaches a kind it was not designed for.

Two rules sit above the whole matrix, checked before any kind-specific case:

- **A locked entity refuses every action except `unlock` and a per-kind exempt list**
  (`LOCKED_EXEMPT_ACTIONS_BY_KIND`): `press` on a `button`; `draw`, `deal`, `peek`, `shuffle`
  and the three `search*` on a `deck`; `draw`, `deal`, `peek`, the three `search*`, `tip-out`,
  `empty` and `clear-source` on a `bag`. The matrix below assumes the target is unlocked, except
  in the `unlock` row. A lock means "stays put": a button ships locked so a stray drag cannot
  move it and must stay pressable, and a locked container is still a container. Nothing that
  moves or destroys the entity — `toss` included — is exempt.
- **A missing target is never allowed.** `isObjectActionAllowedForTarget(action, null)` is
  always `false`.

## The kind × action matrix

✓ = allowed for that kind (target unlocked, unless noted) · ✗ = never allowed for that kind.

| Action | `card` | `deck` | `die` | `token` | `board` | `bag` | `custom` | `card-holder` | `button` | `table` | `coin` |
|---|:--:|:--:|:--:|:--:|:--:|:--:|:--:|:--:|:--:|:--:|:--:|
| `lift` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| `flip` [10] | ✓ | ✓ | ✗ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ |
| `rotate` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| `lock` [1] | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| `unlock` [2] | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| `tap` [3] | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
| `untap` [3] | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
| `shuffle` [6] | ✗ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
| `draw` | ✗ | ✓ | ✗ | ✗ | ✗ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ |
| `deal` | ✗ | ✓ | ✗ | ✗ | ✗ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ |
| `split` [4] | ✗ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
| `combine` | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
| `roll` | ✗ | ✗ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
| `toss` [11] | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ |
| `press` [7] | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ | ✗ | ✗ |
| `flick` [5] | ✓ | ✓ | ✓ | ✓ | ✗ | ✓ | ✓ | ✓ | ✓ | ✗ | ✓ |
| `reveal-all` | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
| `reveal-team-a` | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
| `reveal-team-b` | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
| `peek` [8] | ✗ | ✓ | ✗ | ✗ | ✗ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ |
| `search` [9] | ✗ | ✓ | ✗ | ✗ | ✗ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ |
| `search-pull` [9] | ✗ | ✓ | ✗ | ✗ | ✗ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ |
| `search-close` [9] | ✗ | ✓ | ✗ | ✗ | ✗ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ |
| `tip-out` [12] | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ |
| `empty` [12] | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ |
| `clear-source` [12] | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ |
| `delete` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |

**[1] `lock`** — allowed only while the target is **not already locked** (`!target.locked`).
**[2] `unlock`** — allowed only while the target **is locked**; it is one of the two actions
that bypass the "locked refuses everything" rule above (`press` is the other). **[3] `tap`/`untap`** — refused
for **every** kind: neither has a `case` in the switch, so both fall to the `default: return
false`. The runtime still applies `tap`/`untap` correctly when an action reaches it some
other way (a table script, the host's own UI) — only the participant gate is missing them.
See [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies#the-participant-gate-and-tapuntap-drift)
for the full "known gap" writeup; this page states the fact, that page explains why it
happened. **[4] `split`** — allowed for `deck` only while `stackCount > 1`
(`target.kind === "deck" && target.stackCount > 1`); a single-card deck cannot be split.
**[5] `flick`** — the one action with an explicit *exclusion* rather than an inclusion list:
`target.kind !== "board" && target.kind !== "table"`. Every kind except `board` and `table` allows it —
the two surfaces other pieces rest on. **[6] `shuffle`** — `deck`
only, and it is one of three actions the **runtime** refuses as well as the gate (`press` and
`toss` are the others): see the by-design note below. **[7] `press`** — `button` only
(`target.kind === "button"`), and it is exempt from the locked gate. Like `shuffle`, the
runtime refuses it host-side for any other kind, so a table script or host-side mod pressing
a card does nothing — no state change, no sound, no `onPressed`. A player cannot *request*
`press` on a non-button either; it is the button object's own click that raises it. A button
can further restrict *who* may press it (`metadata.button.restrictTo`), checked when the
action is applied. **[8] `peek`** — `deck`/`bag` only. It privately reveals the top *N* cards
of a container to the peeking player alone (host-authoritative, un-redacted for that one
viewer's snapshot) and logs one public, identity-free line naming only the count and the deck.
A mod cannot *request* it — it is a UI privacy action, not on the mod allowlist — but a table
script may *observe* it via `onObjectAction`. It carries a `count` on the `object-action`
intent; every other action ignores that field. **[9] `search` / `search-pull` / `search-close`** —
`deck`/`bag` only, for the same reason `peek` is. This gate is about the **target kind** alone: *who*
may search is a second, authored question (the pile's own setting, then its `Area` zone, then the kind
default), re-checked host-side on every one of the three intents, and both gates must pass. A refused
search is refused silently. `search-pull` carries a `cardId`, validated against that actor's live
reveal. A mod cannot request any of them; a table script may *observe* them, and is never told which
card was pulled — see [Deck and Bag Search](https://diceytable.com/docs/editor/workflows/deck-search). **[10] `flip` on
a `token` or a `coin`** — allowed unless the entity's
[`flippable`](https://diceytable.com/docs/mods/reference/object-state#flippable) is an explicit `false`
(`isFlatPieceKind(target.kind) && target.flippable !== false` — `isFlatPieceKind` is `token` or
`coin`). For a coin that is exactly what players are offered: a coin is flat by definition, so it
flips unless `flippable` is `false`. For a token it is deliberately looser than what players are
*offered*: the gate has no geometry, so it cannot apply the shape default ("a flat piece flips, a
meeple does not"). The runtime applies it instead, host-side, when the action
arrives — a token whose resolved answer is "no" (explicit `false`, or a tall shape with no
override) is refused there on **every** path, a table script and a host-side mod included, with no
log line, no sound and no `onAction`. The menus hide Flip for the same tokens, so a player never
sees a Flip the host would refuse. Turning a piece over grants nothing `rotate` does not, which is
why the gate does not try harder. **[11] `toss`** — `coin` only: `isTossableCoin(target)`, which is
`target.kind === "coin"`. Every coin tosses — the built-in coin presets and a project's own coin
model whose Type is **Coin** alike; a coin-shaped model left as a `token` does not. (Before the
`coin` kind existed, `toss` was limited to a `token` wearing a built-in coin preset variant; such a
saved token is rewritten to `coin` on load — see [Object kinds § Coin](https://diceytable.com/docs/mods/reference/object-kinds#coin).)
The coin goes straight up 6 to 12 in, spinning end over end, and lands where physics puts it;
nothing reports heads or tails. The menus use the same test, so no surface offers a toss this gate
would refuse. Like `shuffle` and `press`, the runtime repeats the test host-side: a `toss` aimed at
anything but an unlocked coin is refused on **every** path — the host's own UI and an AI agent on
the host's tab included — with no log line, no snapshot and no movement. **[12] `tip-out` /
`empty` / `clear-source`** — `bag` only, by container state: `tip-out` needs a container that is not
infinite (a holder's loose pieces are pushed clear, a piece bag's stored pieces are respawned),
`empty` needs a finite piece bag (not a holder), and `clear-source` needs an infinite container. This
gate passes `empty` and `clear-source` for a matching bag, but the participant authority check
(`apps/web/src/ui/intentAuthority.ts`) then refuses both for every player: they are **host-only**.
The runtime also returns without doing anything when the container is the wrong shape.

> **By design — `shuffle` is deck-only, and `draw`/`deal` are not.** `shuffle`, `draw` and
> `deal` shared one `case` in the switch, so a `bag` was allowed to shuffle. It could not
> do anything: a bag draws at **random** (`containerDrawMode` returns `"random"` for `bag`),
> so there is no order to permute, and `shuffleObject` yawed the entity 45° and returned.
> The case is now split — `shuffle` returns `target.kind === "deck"`, `draw`/`deal` still
> return `deck || bag`. This is one of the rows where the runtime enforces the
> same rule independently of the gate (`press` and `toss` are the others): `applyObjectAction` returns immediately for a
> non-`deck` shuffle, so a table script and a host-side mod are refused too, not just a
> player. Nothing else about bags changed.

## Reading the matrix by kind

Four kinds — `board`, `custom`, `card-holder`, `table` — share the same narrow "generic
manipulation" set: `lift`, `rotate`, `lock`/`unlock`, `flick` (except `board` and `table`), `delete`.
The other six get something beyond that:

- **`card`** additionally allows `flip`, `combine`, and all three `reveal-*` actions.
- **`deck`** allows everything `card` does, plus `shuffle`, `draw`, `deal`, `peek`, the three
  `search*` actions, and conditionally `split`.
- **`token`** additionally allows `flip` — only for a token that may turn over (see
  [10] above). Unlike a card's flip it turns the piece over **in place** and does not touch
  `faceDown`: a token has no hidden face, so which side is up *is* its rotation.
- **`coin`** allows everything `token` does — `flip` unless `flippable: false` (see [10]) — plus
  `toss` (see [11]), which throws it and lets physics choose the side. It is the only kind that
  allows `toss`.
- **`die`** additionally allows only `roll` — and, unusually, does **not** allow `flip`
  despite `flip` toggling a boolean (`faceDown`) that exists on every kind's underlying
  state; the gate is deliberately narrower than the schema.
- **`bag`** shares `draw`, `deal`, `peek` and the three `search*` actions with `deck` but not `shuffle`, `flip`, `combine`,
  `reveal-*`, or `split` — it is an *unordered* container: you take things out of it, and
  what you get is random, so it has no order to shuffle and no card semantics. It alone has
  the container-management actions `tip-out`, `empty` and `clear-source` (see [12]).
- **`button`** adds only `press`, which no other kind allows. It is otherwise identical to
  the generic set (and, unlike every other row, `press` survives the lock).

## Reading the matrix by action

Six actions are universal (`lift`, `rotate`, `lock`, `unlock`, `delete`, and `flick` minus
`board` and `table`) and read the same as "works on anything." The rest partition cleanly along one
axis each: **card semantics** (`combine`, `reveal-*` → `card` + `deck` only), **turn-over
semantics** (`flip` → `card` + `deck`, plus a `token` or `coin` not marked `flippable: false`),
**container semantics** (`draw`, `deal` → `deck` + `bag`), **order semantics**
(`shuffle` → `deck` only, because a bag has no order), **die semantics**
(`roll` → `die` only), **coin semantics** (`toss` → `coin` only),
**container management** (`tip-out`, `empty`, `clear-source` → `bag` only), **stack semantics** (`split` → `deck`, and only a multi-card
one), and **control semantics** (`press` → `button` only). `tap`/`untap` are the only two
actions with **no** kind that allows them through this gate.

## Where this is defined

| What | File | Symbol |
|---|---|---|
| The 27-action union | `packages/shared/src/tableObjects/intents.ts` | `ObjectActionIntent["action"]`, aliased `TableObjectAction` |
| The same list at runtime | `packages/shared/src/tableObjects/intentSchema.ts` | `TABLE_OBJECT_ACTIONS` |
| The per-kind gate (this page) | `packages/shared/src/tableObjects.ts` | `isObjectActionAllowedForTarget`, `LOCKED_EXEMPT_ACTIONS_BY_KIND` |
| Which entities toss | `packages/shared/src/tableObjects.ts` | `isTossableCoin` (`kind === "coin"`) |
| The legacy coin-token rewrite | `packages/shared/src/tableObjects/kinds/coin.ts` | `migrateLegacyCoinKind`, `BUILTIN_COIN_PRESET_VARIANTS` |
| What each action does when applied | `apps/web/src/playcanvas/TabletopRuntime.ts` | `applyObjectAction` |
| Where the gate is checked | `apps/web/src/ui/intentAuthority.ts` | the `object-action` branch of the participant check, which also makes `empty` and `clear-source` host-only |

## See also

- [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) — the engine (27) / table-script (13) / mod (10) vocabularies, `ObjectHandle` method coverage, and why each narrowing exists.
- [Object kinds](https://diceytable.com/docs/mods/reference/object-kinds) — what each kind is and which fields matter for it.
- [Intents](https://diceytable.com/docs/mods/reference/intents) — `ObjectActionIntent`, the wire-level intent this gate validates.
- [`ObjectAction`](https://diceytable.com/docs/reference/enums/object-action) — the 13 table-script action names.
- [`ObjectKind`](https://diceytable.com/docs/reference/enums/object-kind) — the kinds this matrix is indexed by.
- [`TableObjectAction`](https://diceytable.com/docs/reference/enums/table-object-action) — all 27 engine actions, including the 14 no script can request.
- [Mod scripting API](https://diceytable.com/docs/scripting-api/api) — `api.objectAction`, the mod call and the 10 names it accepts.
