Dicey Table

Concepts

Choosing a surface

Table script or mod script? A capability-by-capability decision table, what each surface alone can do, and why moving between them later is a rewrite.

On this page6 sections

You are writing code for a DiceyTable table. There are two places to put it, they share no objects, and each one can do things the other cannot. Pick before you start.

  • Table Scripting — TypeScript, written in the editor, saved inside the scene document. You get world, globalEvents and, in an object script, refObject. It runs on the host.
  • Mod Scripting — one JavaScript file in your mod's GitHub repository. You get api, handed to setup(api, manifest). It is gated by capabilities you declare in the manifest.

The decision table#

Find the thing you want to do. Where the answer is one surface, it is not a preference; where it is Either, both surfaces do it the same way.

You want to Surface Because
Move, rotate or reposition an entity from code Table handle.setPosition / setRotation. Mod scripting has no transform method at all.
Remove an entity from the table Table handle.destroy(). delete is withheld from mods.
React to one specific entity Table refObject.onPickedUp, onRolled, onDropped — entity-scoped delegates. Mod hooks are table-wide.
Post a chat line as the table Table world.broadcast.
Pace a sequence, or poll Table world.wait, globalEvents.onTick.
React to chat, or to turn start and end Table onChatMessage, onTurnStarted, onTurnEnded.
Show players a status line, a log, buttons or player panels off the table Either The Game UI: ui.show in a table script, api.uiShow in a mod (capability ui). The same widgets, private per seat on both.
Ask one player a question and wait for the answer Either ui.prompt / api.uiPrompt.
Place the older basic widgets (panel, button, checkbox, text) at a fixed screen anchor Mod api.setUiElement. A table script reaches basic widgets only inside a Game UI panel widget.
Play a sound, or change an entity's sound Mod api.playSound, api.setObjectSound.
Read the contents of a deck or bag Mod api.getContainerContents.
Read what is in a seat's hand Mod api.getHandObjects.
Know which seat or team this player is in Mod api.getMySeat, api.getMyTeam — answered per peer.
Filter entities by several tags at once Mod api.listObjects({ tags, match }). world.getAllObjects takes one tag.
split or combine a deck from code Mod api.objectAction(id, "split"). Table scripting declares both and exposes no method for either.

Two rows are worth reading twice. A mod cannot move or delete anything. It can flip, rotate, lock, shuffle, draw, deal, split, combine and roll — and that is the complete list. If your game needs a piece to end up somewhere specific, it needs a table script.

What each surface is really for#

Table Scripting is for rules. It runs on one peer, holds live handles, and reacts to entity events with entity-scoped delegates. It is the natural home for "when this die settles, add its face to the score", "when a card lands in this zone, flip it", "at the start of each turn, deal one".

Mod Scripting is for the table around the rules. It runs with a declared capability list, answers per-peer questions, and owns the one surface table scripting has none of — sound — plus the older basic widgets. It is the natural home for "play a shuffle sound the game ships itself", "read the deck to build a draft display", "add a deck-search panel to any game that installs this plugin".

Both draw the Game UI. Status lines, prompts, action strips, logs, player panels and hints are the same widgets on either surface, private to one seat when you ask, so the HUD is not a reason to pick one. Write it where the rules are: a game whose rules are a table script draws its HUD from that script.

Nothing stops a mod shipping both: an editor-authored scene with scene scripts inside it, and an entry.script JavaScript file beside it. They will not be able to call each other — they are different frames on different surfaces with no shared memory — but they can both act on the same table and observe each other's effects through the snapshot.

What you give up either way#

Table Scripting Mod Scripting
Authored in The editor's script editor, with full API autocomplete Any editor. The API declarations exist and power this reference; wiring them into an editor for autocomplete has not been done.
Distributed as Part of the scene document inside your mod A .js file in your mod's repository
Language TypeScript, transpiled on save JavaScript, run verbatim
Runs on The host only Gated per method — see Host authority
Security model A three-type intent allowlist, no capabilities 11 declared capabilities, plus the same intent-level checks
Object model Live ObjectHandles with methods and per-entity events Plain snapshot data plus api.objectAction(id, action)
Errors surface as Script-console diagnostics with the script name and phase Mod runner diagnostics
Actions available 13 in the type union, 9 with a method 10, all callable

Both surfaces are scanned by the same five static patterns, and both run in the same kind of opaque-origin iframe. See Sandbox limits.

Names that look shared and are not#

The two surfaces were designed with different vocabularies on purpose, and the near-misses are the easiest way to write code that silently never runs:

Table Scripting Mod Scripting Relationship
globalEvents.onTurnStarted api.on("onTurnStart", …) None. Different names, different payloads.
globalEvents.onObjectDropped api.on("onObjectDropped", …) Same name, different payload — the mod hook fires off an event-log line whose message starts "moved ", and carries the log event plus a snapshot, not a handle.
globalEvents.onCardDrawn api.on("onCardDrawn", …) Same name, different payload, same caveat.
globalEvents.onZoneEnter / onZoneLeave api.on("onZoneEnter", …) / "onZoneLeave" Same names, and for once the same four-string payload. The mod side needs read-world on top of subscribe-events, and both are host-only.
globalEvents.onTriggerEnter / onTriggerLeave api.on("onTriggerEnter", …) / "onTriggerLeave" Same names, and the same five-field payload. Same rule as the zone pair: the mod side needs read-world on top of subscribe-events, and both are host-only.
world.getAllObjects({ kind, tag }) api.listObjects({ kind, tag, tags, match }) Different filters. Do not assume parity.
ObjectData.name TableObjectState.label The same underlying value — the slug — under two names.

world does not exist in a mod's runtime, and api does not exist in a table script's. Pasting code between them does not produce an error you can see in the editor; it produces a script that throws on its first call.

The two surface values#

The surface badge says which declaration a member comes from. There is no third value and nothing belongs to both.

table-script#

Declared in the table-scripting declarations (packages/shared/src/scripting.ts). Reachable through world, globalEvents or refObject.

mod#

Declared in the mod-scripting declarations (packages/shared/src/modScripting.ts). Reachable through api, or through the exports.setup entry point.

A type used by both surfaces is documented once, on the surface whose reference page owns it, and cross-linked from the other.

See also#

  • Host authority — which peer each surface runs on.
  • Sandbox limits — the language subset and the scanner, which apply to both.
  • Action vocabularies — the 13 and the 10, side by side.
  • Anatomy of a mod — where each of these files sits in a repository.
  • Known limitations — where the two surfaces are asymmetric by accident rather than by design.
  • The mod api object — Surface B's 25 methods, each with its capability.
  • Mod hooks and capabilities — Surface B's hook events and its 12 capability slugs.
  • Types — Surface A's Vec3, ObjectKind, SpawnObjectOptions, PlayerInfo and TurnInfo.
  • setup.json — what a mod places before either surface runs.
  • Limits and caps — the numeric ceilings both surfaces hit.
  • Scripting API — the reference index for both surfaces, once you have chosen.
  • Events — the globalEvents delegates, which exist only on the table-scripting side.
  • Game UI (HUD) — the off-table interface both surfaces draw.
  • world — the global a mod does not have.

Did this page answer your question?