How to Read These Docs

These docs make five structural promises. Each one changes how much you should trust a given page, and each one is enforced by something other than good intentions — a generator, a compiler, or a test that fails the build.

Generated pages and hand-written pages#

Reference sections are two kinds of file stitched together, and both are visible in the repository:

• Generated blocks are produced directly from the code — the scripting API's .d.ts declaration, or the mod schemas' Zod definitions. They live under a _generated/ folder, carry a DO NOT EDIT header, and are rewritten wholesale whenever the code changes. Signatures, parameter names, types and optionality on these pages cannot drift from the code, because they are read from it mechanically rather than transcribed.
• Prose fragments are hand-written and carry the why: when to reach for a call, what null actually means, a worked example, and the gotchas. They are merged into the generated skeleton at a stable marker and are never touched by regeneration.

A test re-runs both generators and fails if the committed output differs by a byte, so a symbol added to the code cannot quietly go undocumented.

If a reference entry looks unusually terse — a signature and one line, nothing else — its prose fragment has not been written yet. That is a gap, not a statement that the member is uninteresting.

The badge legend#

Every scripting reference entry carries up to five badges. The values of each badge are defined in exactly one place in these docs, and this page links to that place rather than restating it. A legend that keeps its own copy of the vocabulary is a legend that will eventually disagree with the pages it explains.

Badge	What it tells you	Its values
Authority	Whether a call runs identically on every peer, only on whoever is hosting, or runs anywhere while its effects come from the host.	The three authority values
Timing	Whether the call resolves immediately or only once the result returns on the next state broadcast.	The two timing values
Availability	Which attachment points — scene script, per-entity script, mod — can reach the member.	The four availability values
Capability	For mod scripts, which manifest-declared capability gates the call. Table scripts have no capability system.	The capability values
Surface	Which of the two script surfaces the member belongs to.	The two surface values

Those five pages are the source of truth. The badge vocabulary is closed: a value outside the lists they define fails the docs test suite, so a badge you see on a page is always one of the documented values.

Why the badges exist at all#

DiceyTable is host-authoritative. Exactly one connected peer is the host and it owns the table's real state; every other peer asks. That single fact is why Authority and Timing are badges rather than prose — an API that looks synchronous can still only take effect once the host agrees, and a page that did not say so would be misleading by omission. Host authority is the full treatment.

Examples are verified, not merely plausible#

An example that reads correctly and silently does not run is worse than no example. Every block on this site presented as runnable code is checked before it can be published:

• Table-script examples are compiled against the exact TypeScript declaration that feeds the in-editor autocomplete, using the same compiler options the editor enforces — including no DOM library, because a table script has no DOM. A change to the scripting API that breaks a published example fails the build.
• Mod examples get the same treatment against the mod API's declaration and are additionally run through the same static scanner that gates real publishing. A published mod example is therefore guaranteed to be one the scanner would accept, not merely one that reads like valid JavaScript.

What this does not guarantee: that an example produces the outcome you want at your table. Compilation proves the call exists and the types line up. Whether shuffling before dealing is the right order for your game is a design question no compiler answers.

Known drift is disclosed, never papered over#

There are two independent script surfaces and three overlapping action vocabularies that do not line up perfectly. Some of that is a deliberate security boundary — the mod surface is smaller on purpose — and some of it is real, tracked drift.

Where a page describes a gap like that, it names it instead of presenting the two surfaces as symmetrical. Action vocabularies is the map of which name means what where, and Known limitations is the running list of what does not work yet.

If a page and the product disagree, the product is right. Report the mismatch rather than assuming you misread; a page that is wrong is a bug in these docs.

Every page is dated and editable#

Every routable page carries two things in its footer:

• Last verified: YYYY-MM-DD — the day a human last confirmed the page against the running product. It is not the file's modification date, and a cosmetic edit does not advance it. It is also what the page reports to search engines as its modification date, so the stamp you read and the stamp a crawler reads cannot disagree.
• Edit this page on GitHub — a direct link to the exact source file that produced the page you are reading. For a reference page that is the hand-written shell; the generated block beside it is regenerated from code and cannot be edited there.

Version-wise, these docs describe the current release of DiceyTable. There is no archived copy of the docs for an older build — the platform ships continuously and the pages are verified against what is deployed, which is what the date stamp records.

Conventions inside a page#

• Terminology is normative. "Component" always means an engine component — render, rigidbody, collision, light, camera, script — and never a thing you place on the table, which is an Entity. Every term is defined once in the Glossary, and a test sweeps the whole docs tree for retired vocabulary.
• Three names, three jobs. id addresses an entity, label is its slug and uniqueness key, displayName is the optional human-facing name. They are not interchangeable; see IDs, names and tags.
• See also links go both ways. A guide links its reference entry and the reference entry links back, and a test fails the build on any /docs/… link — including its #anchor — that does not resolve.
• Search covers headings and symbols, not just page titles. Press / or Ctrl+K from anywhere in the docs; typing a bare member name such as spawnObject jumps straight to that member rather than to the page that mentions it.