# Host authority

> Why a table script runs on exactly one peer, what the other players actually receive, and what the host-only, all-peers and host-authoritative badges mean.

- Source: https://diceytable.com/docs/scripting/concepts/host-authority
- Last verified: 2026-07-27

Exactly one peer at a table is the **host**. The host owns the table's real state: it holds the
physics world, it is the only peer that applies a change, and it broadcasts the result to
everyone else. Every other peer is a `player` or a `spectator` and renders what the host sends.

A **table script runs on the host and nowhere else.** The start path refuses to run when the
peer's role is `player` or `spectator` (`apps/web/src/ui/App.tsx`, `startTableScripts` —
*"Scripts execute only where the table is authoritative: the room host, or a solo (offline)
table. Players/spectators receive effects via snapshots."*). A solo table has no other peers and
is authoritative over itself, so scripts run there too.

## What this means if you are not the host

You are reading a script's behavior from the outside. Your client never loads the script, never
evaluates a handler, and never sees a diagnostic it produced. What reaches you is the outcome:
the host applied a change, and the change arrived in a state broadcast. Three consequences are
worth holding on to:

- **Timing is the host's, not yours.** A script that waits two seconds waits two seconds on the
  host's clock. You see the result when the following broadcast lands.
- **A script's diagnostics are invisible to you.** Script errors and `world.log` lines are
  written to the host's own event log. If a game is misbehaving and you are not hosting, the
  person who can see why is whoever is.
- **Nothing a script does is trusted from your side.** You cannot influence a script by sending
  anything, because your client is not running it.

## The path a change takes

Every table-script mutation travels the same route. Nothing skips a step.

```text
your handler                     (runs in the script sandbox, on the host)
  handle.flip()
    -> postMessage to the host   ("intent", plus which script sent it)
    -> validateScriptIntent      (host-side: the five allowed intent types only)
    -> runtime.applyIntent       (physics + state change, attributed to "Script")
    -> emitSnapshot              (host broadcasts to every peer)
    -> each peer renders the new state
```

Two of those steps are gates you can actually hit:

- **The intent allowlist.** A table script can emit exactly five intent types — `spawn`,
  `object-action`, `transform`, `set-object-tooltip` and `card-overlay-set`, the last one only as
  "set this card counter to N" (`card.setCounter`; the host then checks the counter is declared by
  the card schema) (`apps/web/src/scripting/TableScriptHost.ts`, `validateScriptIntent`). Anything else is refused with a diagnostic in the script console, and
  the object-action name is re-checked against the script allowlist even though the in-frame API
  emits only allowed names. See [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies).
- **Schema validation.** A `spawn` definition is parsed with the shared table-object schema
  before it reaches the runtime. A definition that fails — an over-long tag is the usual cause —
  is dropped whole, with a diagnostic and no object. See
  [Known limitations](https://diceytable.com/docs/reference/known-limitations#tag-validation-is-asymmetric). A
  `set-object-tooltip` patch is parsed the same way, against a strict schema, so a misspelt option
  or an invalid variable name is refused whole with a diagnostic rather than half-applied — see
  [`setTooltip`](https://diceytable.com/docs/scripting-api/objecthandle#objecthandlesettooltip).

## Who the actor is

Every lifecycle event carries an `EventContext` whose `actor` says who caused it. The values the
runtime actually passes are:

| `actor` | What caused the event |
|---|---|
| a peer id | A participant acted. This is the common case at a real table, and it covers the viewer's own grab tool and VR hands as well as a remote player's intent — the grab paths report the viewer's peer id (`apps/web/src/playcanvas/TabletopRuntime.ts`, `currentActorLabel`). |
| `"Script"` | A table script emitted the intent (`apps/web/src/ui/App.tsx`, the `TableScriptHost` `dispatchIntent` callback). |
| `"Host"` | The runtime's own default — an internal path that named no actor (`applyIntent(intent, actor = "Host")`). |
| `"You"` | The local viewer where no peer id exists yet — a solo or offline table. `currentActorLabel()` returns `viewerPeerId ?? "You"`. |
| `"System"` | The runtime's other offline label, treated as local alongside `"You"` (`isLocalActor`). |

The spelling is **capitalised**, and the declaration says so
(`packages/shared/src/scripting.ts`, `EventContext.actor`). A handler comparing
`context.actor === "script"` never matches; compare against the four literals above and treat
anything else as a peer id.

## Mod scripting is gated per method, not per peer

Mod scripting does not have the single host-only switch table scripting has. A mod's `api`
methods fall into three groups instead, and the badge on each entry tells you which:

- Methods that **dispatch an intent** — `createObject`, `objectAction`, `setObjectSound` — go
  through the host exactly like a table script's mutations.
- Methods that are **refused off the host** — `setUiElement` and `deleteUiElement` reject with
  `"Only the host can update mod UI state."` on a `player` or `spectator` peer.
- Methods that are **answered inside the sandbox frame** — `getMySeat`, `getMyTeam`, `getTurn`
  and `on` post nothing at all and read context the host pushed in, so their answer is about the
  peer that asked.

## The three authority values

The **authority** badge on every reference entry answers one question: *whose copy of the table
changes, and who has to be running?*

### `host-authoritative`

The call emits a `TableIntent`. The host validates it, applies it, and the effect reaches every
peer in the next state broadcast. Two entries carry this badge without emitting an intent,
because their effect still reaches everyone anyway: `world.broadcast`, where the host posts the
chat line to every peer, and `api.playSound`, an ephemeral sound event sent on the unreliable
channel. Neither one is table state, and neither survives a save.

### `host-only`

Nothing replicates. Either the host-side implementation refuses the call for a non-`host` role,
or the call is a read back from the host, or it writes to the host's own console. `world.log`
and `api.registerAction` are the plainest examples: both land in the host's local state and no
other peer learns anything.

### `all-peers`

The call is answered entirely inside the sandbox frame, on whichever peer is running the script.
No message is posted and nothing replicates, so the answer describes that peer.

> **By design.** `all-peers` is never correct on a table-scripting entry, because a table script
> only ever runs on one peer — the host — so "all peers" and "the host" would name the same
> thing and the badge would carry no information. Every table-scripting member is
> `host-authoritative` or `host-only`. If you are reading a table-scripting entry badged
> `all-peers`, the page is wrong; please report it.

## See also

- [Async and snapshots](https://diceytable.com/docs/scripting/concepts/async-and-snapshots) — what "resolves" means when the answer arrives by broadcast.
- [Execution order](https://diceytable.com/docs/scripting/concepts/execution-order) — when your code runs relative to the table it is reading.
- [Events and delegates](https://diceytable.com/docs/scripting/concepts/events-and-delegates) — which peer fires each event and how many times.
- [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) — the three action lists the host enforces.
- [`world.spawnObject`](https://diceytable.com/docs/scripting-api/world) — a worked example of an optimistic, host-authoritative call.
- [`ObjectHandle`](https://diceytable.com/docs/scripting-api/objecthandle) — the twelve mutators that return before the host has applied anything.
- [Events](https://diceytable.com/docs/scripting-api/events) — which peer fires each `globalEvents` delegate.
- [Mod hooks and capabilities](https://diceytable.com/docs/scripting-api/hooks-and-capabilities) — the same authority question on Surface B.
- [Intents](https://diceytable.com/docs/mods/reference/intents) — the wire shape a mutator turns into.
- [Mod scripting API](https://diceytable.com/docs/scripting-api/api) — the 21 mod methods, each badged with whose copy of the table its effect reaches.
- [Types](https://diceytable.com/docs/scripting-api/types) — `PlayerInfo.isHost`, how a script asks which peer it is running on.
