Reference
Object actions
The 27 TableObjectAction values and their per-kind gating — a full kind-by-action matrix, with the state-dependent exceptions called out.
On this page6 sections
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 — 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
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
unlockand a per-kind exempt list (LOCKED_EXEMPT_ACTIONS_BY_KIND):presson abutton;draw,deal,peek,shuffleand the threesearch*on adeck;draw,deal,peek, the threesearch*,tip-out,emptyandclear-sourceon abag. The matrix below assumes the target is unlocked, except in theunlockrow. 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 —tossincluded — is exempt. - A missing target is never allowed.
isObjectActionAllowedForTarget(action, null)is alwaysfalse.
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
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. [10] flip on
a token or a coin — allowed unless the entity's
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.)
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 —
shuffleis deck-only, anddraw/dealare not.shuffle,drawanddealshared onecasein the switch, so abagwas allowed to shuffle. It could not do anything: a bag draws at random (containerDrawModereturns"random"forbag), so there is no order to permute, andshuffleObjectyawed the entity 45° and returned. The case is now split —shufflereturnstarget.kind === "deck",draw/dealstill returndeck || bag. This is one of the rows where the runtime enforces the same rule independently of the gate (pressandtossare the others):applyObjectActionreturns immediately for a non-deckshuffle, 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:
cardadditionally allowsflip,combine, and all threereveal-*actions.deckallows everythingcarddoes, plusshuffle,draw,deal,peek, the threesearch*actions, and conditionallysplit.tokenadditionally allowsflip— 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 touchfaceDown: a token has no hidden face, so which side is up is its rotation.coinallows everythingtokendoes —flipunlessflippable: false(see [10]) — plustoss(see [11]), which throws it and lets physics choose the side. It is the only kind that allowstoss.dieadditionally allows onlyroll— and, unusually, does not allowflipdespitefliptoggling a boolean (faceDown) that exists on every kind's underlying state; the gate is deliberately narrower than the schema.bagsharesdraw,deal,peekand the threesearch*actions withdeckbut notshuffle,flip,combine,reveal-*, orsplit— 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 actionstip-out,emptyandclear-source(see [12]).buttonadds onlypress, which no other kind allows. It is otherwise identical to the generic set (and, unlike every other row,presssurvives 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 — the engine (27) / table-script (13) / mod (10) vocabularies,
ObjectHandlemethod coverage, and why each narrowing exists. - Object kinds — what each kind is and which fields matter for it.
- Intents —
ObjectActionIntent, the wire-level intent this gate validates. ObjectAction— the 13 table-script action names.ObjectKind— the kinds this matrix is indexed by.TableObjectAction— all 27 engine actions, including the 14 no script can request.- Mod scripting API —
api.objectAction, the mod call and the 10 names it accepts.
