# Scripting concepts

> The shared ideas behind both DiceyTable script surfaces - where code runs, in what order, how events arrive, and what every reference badge means.

- Source: https://diceytable.com/docs/scripting/concepts
- Last verified: 2026-10-08

DiceyTable has **two** script surfaces. They are separate products that happen to share an
iframe-hardening pattern and a static scanner, and nothing else:

| | **Table Scripting** | **Mod Scripting** |
|---|---|---|
| You write | TypeScript, in the editor at `/editor` | JavaScript, a file in your mod's GitHub repository |
| You are handed | `world`, `globalEvents`, and — in an object script — `refObject` | `api`, as the first argument to `setup(api, manifest)` |
| Events arrive by | delegates: `globalEvents.onObjectDropped.add(fn)` | a registry: `api.on("onObjectDropped", fn)` |
| Objects are | live `ObjectHandle`s with methods | plain snapshot data plus `api.objectAction(id, action)` |

`world` does not exist in a mod's runtime. `api` does not exist in a table script's runtime.
Their event names look similar and are not related — the mod hook is `onTurnStart`, the
table-script delegate is `onTurnStarted`. Read
[Choosing a surface](https://diceytable.com/docs/scripting/concepts/choosing-a-surface) before you pick one; the two
answer different questions and moving between them later is a rewrite, not a port.

## The nine pages, and what each one answers

| Page | The question it answers |
|---|---|
| [Host authority](https://diceytable.com/docs/scripting/concepts/host-authority) | Which peer actually runs my code, and what do the other players see? |
| [Execution order](https://diceytable.com/docs/scripting/concepts/execution-order) | What runs first, and what already exists by the time it does? |
| [Events and delegates](https://diceytable.com/docs/scripting/concepts/events-and-delegates) | When does a handler fire, in what order, and can I stop what triggered it? |
| [Async and snapshots](https://diceytable.com/docs/scripting/concepts/async-and-snapshots) | I called a method — when is the result true, and where do I read it? |
| [Sandbox limits](https://diceytable.com/docs/scripting/concepts/sandbox-limits) | Why does the editor say `document` doesn't exist, and why did my comment fail the scan? |
| [Choosing a surface](https://diceytable.com/docs/scripting/concepts/choosing-a-surface) | Table script or mod? |
| [Game UI (HUD)](https://diceytable.com/docs/scripting/concepts/game-ui) | How does my game tell or ask a player something, privately if need be, without writing on the table? |
| [Highlights and clicks](https://diceytable.com/docs/scripting/concepts/highlights-and-clicks) | How does my scripted game show what a player may pick, and hear which entity they picked? |
| [Asset pack script scope](https://diceytable.com/docs/scripting/concepts/pack-script-scope) | A game depends on my Asset pack — whose saved data does my prefab's script see? |

## If you read one paragraph

Exactly one peer at a table is the **host**, and the host owns the table's real state. A table
script runs on that peer and nowhere else. Everything a script changes becomes real when the
host applies it and reaches every other player in the host's next state broadcast — not when
your method returns. Almost every surprising behavior in either surface follows from that one
sentence, so the pages above spend their length on its consequences rather than on restating
it.

## The badges, and where each value is defined

Every entry in the [Scripting API reference](https://diceytable.com/docs/scripting-api/world) carries a four-row badge
table — authority, timing, capability, availability — under a byline that states the fifth,
its surface. Each value is defined **once**, on the concepts page that owns the idea, and every
reference entry points back here rather than re-explaining it.

| Badge | Values | Defined on |
|---|---|---|
| **Surface** | `table-script` · `mod` | [Choosing a surface](https://diceytable.com/docs/scripting/concepts/choosing-a-surface#the-two-surface-values) |
| **Authority** | `host-only` · `all-peers` · `host-authoritative` | [Host authority](https://diceytable.com/docs/scripting/concepts/host-authority#the-three-authority-values) |
| **Timing** | `sync` · `async` | [Async and snapshots](https://diceytable.com/docs/scripting/concepts/async-and-snapshots#the-two-timing-values) |
| **Capability** | `none`, or one of the 10 mod capability slugs | [Sandbox limits](https://diceytable.com/docs/scripting/concepts/sandbox-limits#the-capability-values) |
| **Availability** | `scene-script` · `object-script` · `both` · `mod` | [Execution order](https://diceytable.com/docs/scripting/concepts/execution-order#the-four-availability-values) |

## Where the honest list lives

Both surfaces have gaps: declarations that are stale, methods that exist in a type union but
have no way to call them, an event that fires correctly but reports `null`. They are collected,
classified and dated on one page — [Known limitations](https://diceytable.com/docs/reference/known-limitations) — and
every reference entry that touches one links to its entry there. A gap you find in the product
that is not on that page is a documentation bug worth reporting.

## See also

- [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) — the three object-action lists and why they differ.
- [How to read these docs](https://diceytable.com/docs/reading-these-docs) — generated pages, prose pages, and how examples are verified.
- [`world`](https://diceytable.com/docs/scripting-api/world) — the table-scripting entry point.
- [`api`](https://diceytable.com/docs/scripting-api/api) — the mod-scripting entry point.
- [Scripting API](https://diceytable.com/docs/scripting-api) — the reference these concepts describe.
