Dicey Table

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 — shuffle is deck-only. A bag used to be on the allowlist, and used to spin 45° when you asked. It never reordered anything: a bag draws at random (containerDrawMode returns "random" for bag), 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. draw and deal are unchanged for bags — those are what a bag is for. If your game shuffled a bag for the visual, replace it with handle.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#

Did this page answer your question?