Action vocabularies
Three object-action vocabularies - 27 engine actions, the 13 a table script may request, the 10 a mod may - what each one does, and exactly why they differ.
On this page7 sections
An object action is a named, host-applied change to one entity on the table: flip it, roll it, shuffle it,
delete it. Every one of them travels as an object-action intent, and the host is the only peer that applies it.
There are three lists of action names, and they are not the same list:
| Vocabulary | Size | Who uses it |
|---|---|---|
| Engine | 27 | The runtime itself. Everything the host knows how to do. |
| Table script | 13 | What a table script may request. Enforced by the script host. |
| Mod | 10 | What a mod may request. Enforced twice — in the sandbox frame and again on the host. |
Two of the engine's actions — press and toss — are not in either script vocabulary and are not a subset
boundary the way the rest are: a player presses a button or flips a coin, the host applies the action, and a
table script can only observe it. They are called out where the values are listed below rather than folded into
the subset story.
Each list is a subset of the one above it. The narrowing is deliberate in some places and accidental in others, and this page says which is which — because a reader who cannot tell the difference reasonably concludes the whole thing is arbitrary.
The engine vocabulary#
Every action the host can apply — 27 of them, listed in TABLE_OBJECT_ACTIONS. This is the full set; the other
two vocabularies are drawn from it.
The Players may send column is the per-kind allowlist that gates an action arriving from a player or
spectator — checked on that client before it sends, and again on the host when it arrives. It is not
applied to actions raised on the host itself: the host's own UI, a table script, and a mod running on the host
all reach the runtime directly. So a table script can request flip on a die, and the host will apply the flip
even though no player could have asked for it.
Two rules sit above the whole column. First, a locked entity refuses every action except unlock and a
short per-kind list: press on a button; draw, deal, peek, shuffle and the three search* on a
deck; and draw, deal, peek, the three search*, tip-out, empty and clear-source on a bag. A lock
means "stays put", so nothing that moves the entity is exempt — a locked coin cannot be tossed and a locked die
cannot be rolled. Second, an action against an entity that does not exist does nothing.
| Action | What the host does | Players may send it for |
|---|---|---|
lift |
Teleports the entity 0.75 ft straight up. | every kind |
flip |
Toggles faceDown and rotates the entity 180° about its local X axis. On a deck it also flips every card entry and re-derives the visible face. On a token or a coin it only turns the piece over in place (collider centre and resting height kept, faceDown untouched), and is refused on every path for one that may not flip — see Flipping a token and Flipping a coin. |
card, deck, and a token or coin unless it is flippable: false |
rotate |
Rotates the entity 90° about its local Y axis. | every kind |
lock |
Marks the entity locked and switches its rigidbody to static. | every kind, but only while unlocked |
unlock |
Clears the lock and restores the authored body type. | every kind, but only while locked |
tap |
Sets tapped to true. |
no kind — see below |
untap |
Sets tapped to false. |
no kind — see below |
shuffle |
Shuffles the deck's contents and starts the cosmetic shuffle spin. Refused outright for every other kind — see below. | 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, and only while its stack holds more than one card |
combine |
Merges the entity into a stack. | card, deck |
roll |
Throws the die with a randomized impulse and lets physics settle it. | die |
toss |
Flips a coin. It throws the coin straight up 6 to 12 in, spinning end over end about a random horizontal axis with a slight sideways drift, and lets physics land it. The table's global speed limit caps the top at about 11.5 in. It plays no sound of its own; the landing uses the coin's ordinary settle and collide sounds. It reports no heads or tails, so read the coin's orientation once it settles if you need one. Menus label it Flip Coin, and the touch rail and the VR menu say Toss. | coin — built-in or a project's own coin model (isTossableCoin) |
press |
Dips a button's cap, plays its sound and raises onPressed. Refused outright on any other kind. Exempt from the locked rule. |
button |
flick |
Flicks the entity across the surface. | every kind except board and table |
reveal-all |
Clears the reveal team and, unless the entity is owned by a seat, 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 top N cards of a container to the peeking player only (host-authoritative), and logs one public, identity-free line naming the count and the deck. Carries a count; every other action ignores it. |
deck, bag |
search |
Opens a private search session: reveals the container's whole contents to the searching player only, and logs one public, identity-free line naming the count and the pile. Gated by the authored audience, and refused silently when it does not include the actor. | deck, bag |
search-pull |
Takes one named item out of a pile the actor is currently searching, through the ordinary draw path. Carries a cardId; the host refuses one the actor's live reveal does not cover. The public line names the pile, never the card. |
deck, bag |
search-close |
Ends the session: applies the pile's authored order policy (shuffle the remainder, or keep it) and revokes the reveal. | deck, bag |
tip-out |
Empties a container onto the table without destroying anything: a holder's loose pieces are pushed clear, and a finite piece bag's stored pieces are respawned beside it. | a bag that is not infinite |
empty |
Deletes a finite piece bag's stored contents outright. | no player — host-only |
clear-source |
Forgets an infinite container's source piece, so it dispenses nothing until it is given a new one. | no player — host-only |
delete |
Destroys the entity, re-parents its children to its own ancestor, and removes its joints. | every kind |
What happens when a script sends an action to the wrong kind. Because a script bypasses the participant gate,
it can address any action to any entity. Four of the container actions guard themselves anyway and return without
doing anything:
draw and deal do nothing unless the target is a deck or a bag, and split does nothing unless it is a
deck with more than one card. The rest do not self-guard — roll on a
card throws the card, flip on a die turns it over and flips its faceDown flag. (A token or coin is the
exception for flip: the host refuses it for one that may not flip, and one that may flip
keeps its faceDown as it was.) Check handle.kind before
acting on an entity you did not spawn yourself. tip-out, empty and clear-source guard themselves too: each
returns without doing anything unless the target is the kind of container it applies to.
shuffle, press and toss refuse rather than no-op. applyObjectAction returns immediately for a
shuffle whose target is not a deck, for a press whose target is not a button, and for a toss whose
target is not an unlocked coin: no state change, no log line, no snapshot, no sound, no spin, no
movement. Those refusals are on the host side of the gate, so they apply to a table
script and a host-side mod too, not only to a player's intent. handle.shuffle() on a bag therefore does
nothing at all and reports nothing — check handle.kind === "deck" first if the distinction matters. (There
is no press method on ObjectHandle; a script cannot request press at all — it only observes it. The same is
true of toss. Its host-side check matters for the paths that can send it: the host's own menus, and an AI
agent driving the host's tab through table_object_action.)
By design —
shuffleis deck-only. Abagused to be on the allowlist, and used to spin 45° when you asked. It never reordered anything: a bag draws at random (containerDrawModereturns"random"forbag), so its contents have no order for a shuffle to change, and the 45° yaw was the only observable effect. The allowlist now says what the action does, so a bag no longer offers Shuffle in the right-click menu or the VR object menu, and shaking one no longer dispatches it.drawanddealare unchanged for bags — those are what a bag is for. If your game shuffled a bag for the visual, replace it withhandle.rotate().
Known gap. tap and untap have no case in the per-kind allowlist, so it refuses them for every kind.
A player or spectator can never send either one; only the host — including a table script — can.
The runtime applies them correctly when they arrive, so the behavior is complete; only the participant gate is
missing them. See Known limitations.
The table-script vocabulary — 13 actions#
ObjectAction in the table-scripting type declarations. The script host re-checks the same 13 names before it
passes an object-action intent to the runtime, so a compromised sandbox frame cannot broaden the set.
flip · rotate · lock · unlock · tap · untap · shuffle · draw · deal · split · combine · roll · delete
That is the engine's 27 minus the 14 a script may only observe: lift, flick, press, toss, peek, search, search-pull, search-close, reveal-all, reveal-team-a, reveal-team-b, tip-out, empty and clear-source.
Nine of the thirteen have an ObjectHandle method. The others are in the type union and would pass the
script host's check, but the typed API has no way to call them:
| Action | How a script calls it |
|---|---|
flip |
handle.flip() |
rotate |
handle.rotate() |
lock |
handle.lock() |
unlock |
handle.unlock() |
shuffle |
handle.shuffle() |
draw |
handle.draw() |
deal |
handle.deal() |
roll |
handle.roll() |
delete |
handle.destroy() — the method name differs from the action name |
tap |
no method |
untap |
no method |
split |
no method |
combine |
no method |
Known gap. tap, untap, split and combine are declared in ObjectAction and are on the script
host's allowlist, but ObjectHandle exposes no method for any of them, so a script cannot request them
through the typed API. Nothing about them is disabled — the allowlist and the runtime both handle them — and
only the calling surface is missing. See Known limitations.
Observing is a different, wider type. globalEvents.onObjectAction and ObjectHandle.onAction are
declared with ObservedObjectAction — this union plus
the 14 observe-only names above, i.e. all 27. A script may watch every action the
engine raises and request only these 13, and the two type names keep that distinction visible in the editor
rather than leaving it to be discovered at run time. press is the clearest case: there is no way to request
it, but a button script hears every press through onPressed. toss works the same way: a coin flip reaches
onObjectAction and onAction as "toss", and a coin's own script through CoinObject.onTossed, and no
script can start one.
The mod vocabulary — 10 actions#
SANDBOX_SAFE_OBJECT_ACTIONS, reached through api.objectAction(objectId, action) behind the
object-action capability. One list, checked at three points: inside the sandbox frame, which throws on
anything else; in SandboxedModRunner when the message reaches the host; and again in the host's
objectAction implementation before the intent is dispatched. All three test the same ten names — the
innermost gate is deliberately no laxer than the outer ones.
flip · rotate · lock · unlock · shuffle · draw · deal · split · combine · roll
That is the table script's 13 minus tap, untap and delete. A mod cannot delete an entity.
Unlike a table script, a mod passes the action name as a string, so split and combine are genuinely
reachable here even though they have no table-script method.
Compatibility matrix#
Rows are the 27 engine actions. ✓ means present, ✗ means absent. press and toss are the rows that break the
"each list is a subset of the one above" story: a player can send them, but neither script surface can request
them. A table script only observes them, through ObservedObjectAction (and ButtonObject.onPressed for a
press, CoinObject.onTossed for a toss).
| Engine action | Engine | Table script | ObjectHandle method |
Mod allowlist |
|---|---|---|---|---|
lift |
✓ | ✗ | ✗ | ✗ |
flip |
✓ | ✓ | flip() |
✓ |
rotate |
✓ | ✓ | rotate() |
✓ |
lock |
✓ | ✓ | lock() |
✓ |
unlock |
✓ | ✓ | unlock() |
✓ |
tap |
✓ | ✓ | ✗ | ✗ |
untap |
✓ | ✓ | ✗ | ✗ |
shuffle |
✓ | ✓ | shuffle() |
✓ |
draw |
✓ | ✓ | draw() |
✓ |
deal |
✓ | ✓ | deal() |
✓ |
split |
✓ | ✓ | ✗ | ✓ |
combine |
✓ | ✓ | ✗ | ✓ |
roll |
✓ | ✓ | roll() |
✓ |
toss |
✓ | ✗ (observe only) | ✗ | ✗ |
press |
✓ | ✗ (observe only) | ✗ | ✗ |
flick |
✓ | ✗ | ✗ | ✗ |
reveal-all |
✓ | ✗ | ✗ | ✗ |
reveal-team-a |
✓ | ✗ | ✗ | ✗ |
reveal-team-b |
✓ | ✗ | ✗ | ✗ |
peek |
✓ | ✗ (observe only) | ✗ | ✗ |
search |
✓ | ✗ (observe only) | ✗ | ✗ |
search-pull |
✓ | ✗ (observe only) | ✗ | ✗ |
search-close |
✓ | ✗ (observe only) | ✗ | ✗ |
tip-out |
✓ | ✗ (observe only) | ✗ | ✗ |
empty |
✓ | ✗ (observe only) | ✗ | ✗ |
clear-source |
✓ | ✗ (observe only) | ✗ | ✗ |
delete |
✓ | ✓ | destroy() |
✗ |
Totals: 27 · 13 · 9 · 10.
The Table script column is the ObjectAction type union, which the script host's allowlist matches exactly.
The ObjectHandle method column is what the typed in-frame API can actually call — the practical limit for
a table script.
Why these differ#
Three of the four gaps are decisions. Two are unfinished work. Told apart:
Engine → table script: a deliberate boundary#
By design. lift, flick, press, toss, peek, search, search-pull, search-close, reveal-all,
reveal-team-a, reveal-team-b, tip-out, empty and clear-source are
engine-internal. lift and flick are drag mechanics — the physical result of a pointer gesture,
meaningless without the gesture that produced it. press is the same in spirit: it is the result of a
player clicking a button, so a script reacts to it (ButtonObject.onPressed) but has no reason to
synthesize one — to make a button do something on its own, run that logic in onPressed rather than trying
to fake the press. toss is a player's coin flip. A script that wants a random result has a better tool: pick
the result itself and show it, rather than throw a coin and wait for physics to land it. peek is a hidden-information reveal that only ever un-hides a container's top cards to
the peeking player and only on the host, so — like the reveals below — a script may observe it but not
synthesize one. The three search* actions are the same reveal widened to a whole pile and held open as a
session, and they are withheld for the same reason twice over: a script that could open one would manufacture
a private reveal for itself, and the event it observes deliberately never names the card that was pulled. See
Deck and Bag Search. 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. tip-out, empty and clear-source are container management. empty and clear-source are
destructive and host-only even for players, and tip-out respawns a bag's whole contents at once.
Table script → mod: also deliberate, for a different reason#
By design. A mod is untrusted code fetched from a GitHub repository and gated by a capability allowlist; a
table script is authored in the editor by whoever built the scene. They get different budgets. delete is
withheld because a mod that can destroy entities can quietly dismantle a table it did not create, and
tap/untap are withheld because no participant path sends them either. Build a mod around
api.createObject and the actions it does have; a game that genuinely needs to remove pieces belongs in a
table script.
ObjectAction → ObjectHandle: drift#
Known gap. tap, untap, split and combine are in the table-script type union and on the script
host's allowlist, but ObjectHandle has no method for them. This is an oversight in the typed surface, not a
restriction: every layer below is ready for them, and only the calling surface is missing. delete looks like
the same problem and is not — it is reachable, as destroy().
See Known limitations.
The participant gate and tap/untap: drift#
Known gap. The per-kind allowlist that gates player and spectator actions has no case for tap or
untap, so it refuses them for every kind. The actions work; only players cannot ask for them.
See Known limitations.
Where these lists live#
If you are checking this page against the code, these are the definitions — by file and exported symbol, so the references survive edits.
| List | File | Symbol |
|---|---|---|
| Engine, 27 (type) | packages/shared/src/tableObjects/intents.ts |
ObjectActionIntent["action"], aliased as TableObjectAction |
| Engine, 27 (runtime list) | packages/shared/src/tableObjects/intentSchema.ts |
TABLE_OBJECT_ACTIONS, which is also the AI-agent table_object_action allowlist |
| Per-kind participant gate | packages/shared/src/tableObjects.ts |
isObjectActionAllowedForTarget, with LOCKED_EXEMPT_ACTIONS_BY_KIND |
Which entities may toss |
packages/shared/src/tableObjects.ts |
isTossableCoin — kind === "coin" |
| Table script, 13 (types) | packages/shared/src/scripting.ts |
the ObjectAction union inside DICEYTABLE_SCRIPT_API_DTS |
| Table script, 13 (enforcement) | apps/web/src/scripting/TableScriptHost.ts |
SCRIPT_SAFE_OBJECT_ACTIONS, checked by validateScriptIntent |
ObjectHandle methods |
packages/shared/src/scripting.ts |
the ObjectHandle interface inside DICEYTABLE_SCRIPT_API_DTS |
| Observed, 27 | packages/shared/src/scripting.ts |
the ObservedObjectAction union inside DICEYTABLE_SCRIPT_API_DTS |
| Mod, 10 (in-frame) | apps/web/src/mods/sandbox/modSandbox.html |
SAFE_OBJECT_ACTIONS |
| Mod, 10 (host, message) | apps/web/src/mods/SandboxedModRunner.ts |
SANDBOX_SAFE_OBJECT_ACTIONS, checked by isSandboxSafeObjectAction |
| Mod, 10 (host, dispatch) | apps/web/src/ui/App.tsx |
the mod runner's objectAction callback, checked by the same isSandboxSafeObjectAction |
| What each action does | apps/web/src/playcanvas/TabletopRuntime.ts |
applyObjectAction |
See also#
ObjectHandle— the table-script methods in this page's third column.- Host authority — why only the host applies an action.
- Known limitations — every gap named on this page, in one list.
