Enums and Constants
ObjectAction (table script)
The 13 actions a table script may request, the 9 that have an ObjectHandle method, the 4 that do not, and what the script host does with each one.
On this page4 sections
ObjectAction is the union a table script may pass through the script host — 13 of the engine's 27
actions. It is declared inside DICEYTABLE_SCRIPT_API_DTS and re-checked at run time against
SCRIPT_SAFE_OBJECT_ACTIONS in apps/web/src/scripting/TableScriptHost.ts, and the two lists match
exactly, so a compromised sandbox frame cannot broaden the set.
This union does not exist on the mod surface. A mod's ten-action list is
SANDBOX_SAFE_OBJECT_ACTIONS, which is a different
list with a different enforcement path.
The values#
The How a script calls it column is the practical limit: an action with no method is in the union and would pass the allowlist, but the typed API offers no way to request it.
| Value | What the host does | Kinds it is meaningful for | How a script calls it |
|---|---|---|---|
flip |
Toggles faceDown and rotates 180° about local X. On a token, turns it over in place without touching faceDown. |
card, deck, and a token that may flip (flat shape, or flippable: true) — the host refuses it for any other token. On any other kind the rotation and the flag both still change. |
handle.flip() |
rotate |
Rotates 90° about local Y. | every kind. | handle.rotate() |
lock |
Marks the entity locked and switches its rigidbody to static. | every kind. | handle.lock() |
unlock |
Clears the lock and restores the authored body type. | every kind. | handle.unlock() |
tap |
Sets tapped to true. |
every kind. | no method |
untap |
Sets tapped to false. |
every kind. | no method |
shuffle |
Shuffles a deck's contents. Refused outright on every other kind — the runtime returns before it changes anything, so a bag makes no sound and does not move. | deck. |
handle.shuffle() |
draw |
Draws the first item off the container. Does nothing on any other kind. | deck, bag. |
handle.draw() |
deal |
Deals from the container to the seated players. Does nothing on any other kind. | deck, bag. |
handle.deal() |
split |
Splits a stacked deck in two. Does nothing unless the deck holds more than one card. | deck. |
no method |
combine |
Merges the entity into a stack. | card, deck. |
no method |
roll |
Throws the die with a randomized impulse. On a card it throws the card. | die. |
handle.roll() |
delete |
Destroys the entity, re-parents its children, removes its joints. | every kind. | handle.destroy() — the method name differs from the action name |
9 of the 13 have a method. tap, untap, split and combine do not.
Known gap. tap, untap, split and combine are declared in ObjectAction and are on the script
host's allowlist (apps/web/src/scripting/TableScriptHost.ts, SCRIPT_SAFE_OBJECT_ACTIONS), but
ObjectHandle exposes no method for any of them (packages/shared/src/scripting.ts). Every layer below
the typed API is ready for them — the allowlist passes them and the runtime applies them correctly — and
only the calling surface is missing. delete looks like the same problem and is not: it is reachable, as
destroy(). Until a method exists, model tapping as your own state — a tag, or saved data — and read it
back with handle.refresh(). A mod can call split and combine, because mod scripting passes the
action name as a string.
See Known limitations.
What the engine has and this union does not#
Fourteen engine actions are outside this union: lift, flick, press, toss, peek, search,
search-pull, search-close, reveal-all, reveal-team-a, reveal-team-b, tip-out, empty and
clear-source. A table script cannot request any of them.
By design. lift and flick are drag mechanics — the physical result of a pointer gesture,
meaningless without the gesture that produced it. press is a button's own click — a script observes
it through ButtonObject.onPressed and reacts, rather than synthesizing one. toss is a player flipping a
coin. A script that needs a random result should choose one itself, not throw a coin and wait for
it to land. tip-out, empty and clear-source manage a container's contents, and the last two are
host-only even for players. peek, the three search* actions and 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.
Receiving an action is wider than requesting one#
globalEvents.onObjectAction and ObjectHandle.onAction are not typed with this union. They are typed
with ObservedObjectAction, which is this union plus the
fourteen engine actions above — the event is raised for all 27, so a handler can be handed a lift, a
press, a toss or a reveal-* it could never have asked for.
That is why there are two types rather than one: collapsing them would either hide real events or advertise
calls the host's allowlist refuses. Annotate with ObjectAction what you are about to request and with
ObservedObjectAction what an event gave you, and keep a default branch in the switch — the engine's
list and this union live in two files, and the engine gains actions (toss is the latest).
See also#
- Action vocabularies — the three lists side by side.
ObservedObjectAction— the union an event delivers.- TableObjectAction (engine) — all 27.
- Sandbox-safe object actions — the mod list of 10.
ObjectHandle— the nine methods in the last column.- Object actions — what each action does, per kind.
