# Sidecars

> Files beside a mod's assets — model meta, deck definitions and assemblies — plus the link records, thumbnails and folder keepers the editor manages.

- Source: https://diceytable.com/docs/mods/files/sidecars
- Last verified: 2026-10-06

A **sidecar** is a small JSON file that sits beside (or names) another asset and carries configuration the asset file itself can't express. DiceyTable has two: **model meta sidecars** (`*.meta.json`) and **custom-deck definitions** (`*.deck.json`). Both are ordinary declared assets — list them in `assets[]` like anything else — but their *content* is additionally validated against a shared schema at scan time, on top of the generic asset checks in [Assets](https://diceytable.com/docs/mods/files/assets). **Model assemblies** (`*.assembly.json`, below) are not sidecars, but get the same content validation.

## Why sidecars get extra validation

Both sidecar shapes are consumed by every client — spawn paths and card-face rendering read them directly — so a malformed sidecar would otherwise fail identically and repeatedly on every peer at runtime, with no clear diagnostic. The scanner's `validateSidecarJsonAsset()` catches that at publish time instead, with a path-bound error pointing at the exact file.

- **Invalid model meta:** `` `Model meta sidecar does not match the expected schema (${field}: ${message}).` `` (code `invalid-model-meta`)
- **Invalid deck definition:** `` `Custom deck definition does not match the expected schema (${field}: ${message}).` `` (code `invalid-deck-definition`)
- **Either, if not parseable JSON:** `` `${label} is not valid JSON: ${parse error}.` ``
- **Invalid model assembly (including unparseable JSON):** `` `Model assembly does not match the expected schema (${message}).` `` (code `invalid-model-assembly`)

## Model assemblies — `<name>.assembly.json`

An assembly is one model made of several part GLBs, each with its own transform. The editor writes one when you split a model: splitting `models/castle.glb` produces `models/castle/castle.assembly.json` plus one `models/castle/castle-<part>.glb` per part. Use the assembly's path anywhere a model path goes — a custom model object or a room decor placement — and every peer loads it as a single model.

```json
{
  "version": 1,
  "source": "models/castle.glb",
  "parts": [
    {
      "id": "tower",
      "label": "Tower",
      "model": "models/castle/castle-tower.glb",
      "position": { "x": 2.1, "y": 0, "z": -4 },
      "rotation": { "x": 0, "y": 0, "z": 0 },
      "scale": { "x": 1, "y": 1, "z": 1 }
    }
  ]
}
```

- **`position`** places the part's **base centre** (the centre of its X/Z bounds, at its lowest point), so rotation and scale pivot about the bottom middle of the part.
- **`rotation`** is in degrees. `rotation` and `scale` default to identity. Scale must be positive.
- **`model`** is a repo-relative `.glb`/`.gltf` path **from the repo root**, not from the assembly's own folder. A part cannot be another assembly.
- **`parts`** holds 1–256 entries, and each `id` must be unique.
- **Materials:** each part binds its materials from its **own** meta sidecar (`models/castle/castle-tower.meta.json`), so rebinding a part changes it in every assembly that uses it. An assembly sidecar (`castle.assembly.meta.json`) is only a fallback for slots a part's sidecar doesn't bind. A table object's own per-slot assignments still win over both.

This is purely additive: it only rejects sidecar-shaped files that are internally broken. No existing content-type, size, or extension rule is loosened or skipped.

## Model meta sidecars — `<model-stem>.meta.json`

**Path convention:** `modelMetaPathFor(modelPath)` strips only the model file's **last** extension segment and appends `.meta.json`, in the same directory:

| Model path | Sidecar path |
|---|---|
| `assets/models/foo.glb` | `assets/models/foo.meta.json` |
| `assets/models/foo.v2.glb` | `assets/models/foo.v2.meta.json` |
| `assets/models/foo` (no extension) | `assets/models/foo.meta.json` |

**Recognized by:** `isModelMetaPath(path)` — case-insensitive suffix match on `.meta.json` with a non-empty stem.

**What it's for:** default spawn properties for a custom model, applied by `applyModelAssetMetaToDefinition()` when the model is spawned — so every table an author drops the model onto gets consistent defaults without re-configuring by hand each time.

**Shape** (`modelAssetMetaSchema`, `packages/shared/src/modelAssetMeta.ts`) — every field is optional (`.partial()`); unknown keys are stripped:

| Field | Type / constraint |
|---|---|
| `kind` | table-object-kind enum (`card`, `deck`, `die`, `token`, `board`, `bag`, `custom`, `card-holder`, `button`, `table`, `coin`) — what the model spawns **as**. Absent means `custom` |
| `material` | sound-material enum (`wood`, `cardboard`, `metal`, `plastic`, `card`, `tile`, `felt`, `cloth`, `glass`, `stone`, `generic`, `silent`) — the piece's physical **surface**, and what a piece landing on it is heard through. Absent resolves from `kind` |
| `flippable` | boolean — whether a `token` spawned from this model offers **Flip**. Absent means "decide from the shape" (flat pieces flip, tall ones do not). Ignored for every other `kind` |
| `color` | hex color, `^#[0-9a-f]{6}$` |
| `rotation`, `scale` | `{ "x": …, "y": …, "z": … }` objects (`vector3TupleSchema` — an **object**, despite the name; a JSON array is rejected). `rotation` is in degrees, `scale` is a multiplier on the model's native size |
| `spawnHeight` | number, finite, ≥0 — **note:** read directly by the caller when computing spawn position; not auto-applied by `applyModelAssetMetaToDefinition()` |
| `faceDown`, `locked` | boolean |
| `stackCount` | integer, 1–1000 |
| `containerMode` | container-mode enum |
| `capacityLimit` | integer, 1–1000 |
| `tags` | string array, ≤100 entries, each `^[a-z0-9_-]+$`, ≤32 chars |
| `metadata` | free-form record — merged per-key over the definition's own `metadata` (sidecar keys win) |
| `materialSlots` | record of **source material name → project material id** — the model's default per-slot material binding, merged per-key over the definition's own `materialSlots` (sidecar keys win) |
| `bodyType` | physics body-type enum |
| `mass` | number, positive, finite |
| `friction`, `restitution`, `linearDamping`, `angularDamping` | number, 0–1 |
| `collisionShape` | collision-shape enum |
| `collider` | the authored **collider list** — `{ "mode": "auto" }`, or `{ "mode": "custom", "entries": [ … ] }` with 1–8 entries, each carrying its own `offset`/`rotation`/`scale` |
| `triggers` | up to 8 **trigger volumes**, each `{ id, name, shape, position, rotation, size, tag? }` |

**`kind` and `material` classify the piece; the rest of the file dresses it.** `kind` decides which
gameplay actions and sound events a spawned object has at all, and `material` decides what it sounds
and weighs like — neither is a clip id or a render material. A model that *is* a die is a die every
time it is placed, which is why both belong on the asset rather than on each entity in `setup.json`.
The Model editor writes them from **Spawn defaults ▸ Type / Surface**, and changing Surface there
re-derives the `mass`/`friction`/`restitution`/damping numbers below (tune them afterwards and your
values are kept). An entity can still be reclassified on the table, and an explicit `kind` in
`setup.json` wins over the sidecar's.

**`flippable` refines a `token`.** Most models never need it: a token's Flip is decided by its
shape, which is right for checkers, coins and meeples alike. Write it only when the shape guesses
wrong — `true` for a chunky two-sided marker, `false` for a flat standee that must stay face up.
The Model editor writes it from **Spawn defaults ▸ Flippable** (shown only while Type is Token;
**Auto** removes the key). Like `kind` and `material` it is copied into the spawn definition, so it
is replicated per entity and the Inspector can override it on one piece.

The `bodyType`/`mass`/`friction`/`restitution`/`linearDamping`/`angularDamping`/`collisionShape` fields are **flat** in the sidecar (not nested under a `physics` key) but get collected into the spawned definition's `physics` override at apply time.

**`materialSlots` is what makes an imported model's materials editable.** Importing a GLB lifts its
materials into project materials and its images into `textures/` files, then **removes those images
from the GLB** — so the bytes are stored once rather than twice. The model keeps its material
*names*, which are the slot keys, and this record says which project material each one became. It is
written once, at import, and every spawn of the model inherits it through
`applyModelAssetMetaToDefinition()`.

The consequence worth stating plainly: for a model imported this way, `materialSlots` is not
decoration. Remove it and the model renders untextured, because the textures it used to carry
internally now live beside it and only the binding connects the two. Editing the bound material is
what changes how the model looks — which is the point.

It applies to **room decor** as well as to table entities. A `roomPack.decor` placement names a
`modelPath` and never builds an entity definition, so it reads this record from the same per-asset
registry that carries `collider`, `triggers` and the shadow flags — which is also why those keys
work for scenery.

**Units, once, for the whole file:** every length is in **feet** measured at the entity's identity scale (the world unit in DiceyTable is a foot — a playing card is about 0.29 ft wide), and every rotation is Euler XYZ in **degrees**. The entity's own `scale` is applied on top at spawn, so author at unit scale.

`collider` and `triggers` are both **optional and additive** — a sidecar written before they existed is still valid, and both keys are documented field by field below. Two conventions are worth knowing up front:

- **`.collider.glb`, the sibling bake.** A `convexHull` or `mesh` entry with `"source": "baked"` reads its geometry from a GLB next to the model: strip the model file's last extension and append `.collider.glb`, so `assets/models/keep.glb` pairs with `assets/models/keep.collider.glb`. `bakedPath` overrides that when the file lives elsewhere. Declare the collider GLB in `assets[]` like any other asset.
- **`triggers[].tag` cannot be a platform tag.** It goes through the same author-tag validation as every other tag — 1–32 characters matching `^[a-z0-9_-]+$` — and a `dt:`-prefixed value is **rejected**, so a mod cannot mint a reserved platform tag from a sidecar.

**Worked example:**

```json
{
  "kind": "token",
  "material": "metal",
  "color": "#c9a227",
  "scale": { "x": 1, "y": 1, "z": 1 },
  "locked": false,
  "tags": ["premium-piece"],
  "mass": 0.4,
  "friction": 0.6,
  "collisionShape": "convexHull",
  "collider": {
    "mode": "custom",
    "entries": [
      {
        "id": "body",
        "name": "Body",
        "shape": "cylinder",
        "radius": 0.06,
        "height": 0.02,
        "axis": 1
      }
    ]
  },
  "triggers": [
    {
      "id": "slot",
      "name": "Coin Slot",
      "shape": "box",
      "position": { "x": 0, "y": 0.05, "z": 0 },
      "rotation": { "x": 0, "y": 0, "z": 0 },
      "size": { "x": 0.2, "y": 0.1, "z": 0.2 },
      "tag": "coin-slot"
    }
  ]
}
```
Path: `assets/models/coin.meta.json`, sitting beside `assets/models/coin.glb`.

## Custom deck definitions — `<slug>.deck.json`

**Path convention:** `assets/decks/<slug>.deck.json`, where `<slug>` comes from `deckDefinitionPathFor(name)` — lowercased, NFKD-normalized, non-alphanumerics collapsed to `-`, trimmed, capped at 60 chars.

**Recognized by:** `isDeckDefinitionPath(path)` — case-insensitive suffix match on `.deck.json` with a non-empty stem.

**Companion asset paths** (editor convention, not schema-enforced): per-card face images at `assets/decks/<slug>/cards/<NNN>-<stem>.webp` (zero-padded 3-digit index) and a generated composite sheet at `assets/textures/decks/<slug>/sheet-1.webp`. The **per-card images are the durable source of truth**; the sheet is a build artifact regenerated from them. Only the sheet is declared in `manifest.assets` — card sources are authoring input and are never downloaded by players. (Decks created before the sources moved under `assets/decks/` still have them at `assets/textures/decks/<slug>/cards/…`; both paths are recognised.)

**Shape** (`customDeckDefinitionSchema`, `packages/shared/src/customDeck.ts`), schema version `1`:

| Field | Type / constraint |
|---|---|
| `schemaVersion` | literal `1` |
| `id` | string, 1–120 |
| `name` | string, 1–120 |
| `face` | a **sheet**: `{ texturePath, columns (1–64), rows (1–64), cardCount (≥1), cardWidthPx (1–8192), cardHeightPx (1–8192) }` — `cardCount` must fit `columns × rows` |
| `uniqueBacks` | boolean — TTS "Unique Backs": each card windows its own cell of the back sheet |
| `back` | discriminated union: `{ kind: "sheet", sheet: <same shape as face> }` or `{ kind: "single", texturePath }` |
| `sideways` | boolean, default `false` — TTS "Sideways" (cards render/rotate landscape) |
| `backIsHidden` | boolean, default `false` — TTS "Back is Hidden": hand-hidden cards show the back instead of the deck's own hidden-face convention |
| `cardFields` | array, ≤64, default `[]` — the data model every card inherits; each `{ key, label?, type, defaultValue?, options? }` |
| `deckFields` | array, ≤64, default `[]` — same shape, describing the deck itself |
| `data` | object, ≤64 keys, default `{}` — the deck's own field values |
| `cards` | array, 1–1000, each `{ cardId, label?, faceIndex (≥0), backIndex? (≥0), count (1–1000, default 1), data? }` |

Four cross-field checks run beyond the shape above: every `cards[].faceIndex` must be `< face.cardCount`; (when `uniqueBacks` is true and `back.kind === "sheet"`) every `cards[].backIndex` must be `< back.sheet.cardCount`; every `cardId` must be unique; and the `count`s must add up to no more than 1000. Field keys must also be unique within `cardFields` and within `deckFields`. Each produces a field-pathed schema error, which the sidecar scan surfaces via the `invalid-deck-definition` message above.

**Copies (`cards[].count`):** a card's copies share one sheet cell, so `face.cardCount` counts **distinct** cards while the spawned deck's `stackCount` is the sum of the counts. Copy 1 keeps the plain `cardId`; copies 2..N get a `#2`, `#3`, … suffix (`expandDeckCardIds()` / `baseDeckCardId()`). A definition written before `count` existed is unchanged in meaning: every entry defaults to one copy.

**Data model:** `cardFields`/`deckFields` declare typed fields (`text`, `number`, `boolean`, `select`) with an inherited `defaultValue`; a card overrides one by putting the same key in its own `data`. Bags are sparse — an absent key inherits — and hold flat scalars only. Read them through `resolveDeckCardData()` / `resolveDeckData()`, which apply inheritance and coerce each value to its declared type. A value that disagrees with its type is coerced at read time, never rejected at validation time, so retyping a field cannot make an authored deck unloadable.

**Hand-hidden face convention:** unless `backIsHidden` is set, the hand-hidden face shown for a card is the **last image on the face sheet** (`face.cardCount - 1`), matching Tabletop Simulator's convention — reserve your final sheet cell for a generic card-back-style image if you want that look.

**Worked example:**

```json
{
  "schemaVersion": 1,
  "id": "tarot-major-arcana",
  "name": "Tarot — Major Arcana",
  "face": {
    "texturePath": "assets/textures/decks/tarot/sheet-1.webp",
    "columns": 5,
    "rows": 5,
    "cardCount": 22,
    "cardWidthPx": 512,
    "cardHeightPx": 880
  },
  "uniqueBacks": false,
  "back": { "kind": "single", "texturePath": "assets/textures/decks/tarot/back.webp" },
  "sideways": false,
  "backIsHidden": false,
  "cardFields": [
    { "key": "arcanum", "label": "Arcanum", "type": "number", "defaultValue": 0 },
    { "key": "element", "type": "select", "options": ["fire", "water", "air", "earth"] }
  ],
  "deckFields": [{ "key": "ruleset", "type": "text", "defaultValue": "rider-waite" }],
  "data": {},
  "cards": [
    { "cardId": "the-fool", "label": "The Fool", "faceIndex": 0, "count": 1, "data": { "element": "air" } },
    { "cardId": "the-magician", "label": "The Magician", "faceIndex": 1, "count": 1, "data": { "arcanum": 1 } }
  ]
}
```

`the-fool` has no `arcanum` entry, so it inherits the field's `0`; `the-magician` has no `element`, so it resolves to `null`. Neither card stores what it agrees with the model about — that is what keeps a large deck's file (and its replicated slice) small.

## Files the editor manages for you

Three more kinds of file live in a mod repo beside your assets. You never write them by hand:
the editor writes, moves and removes them. They are listed here so you know what they are
when you see them on GitHub.

### Library link records — `<file>.link.json` and `links/materials/`

A link record **records where a library copy came from**: which library item a project file (or
material) was copied from, and what that item looked like at the time. The source is one of:

- a **platform preset** — `{ "type": "preset", "presetKind": "model" | "material" | "texture" | "deck", "presetId": … }`;
- a **plugin resource** at a pinned commit — `{ "type": "plugin", "pluginId": …, "commitSha": <full 40-hex sha>, "resourcePath": … }`.

**Where it lives:**

| Copy of | Record path |
|---|---|
| A file | Next to it, keyed by the **full** filename: `textures/wood-floor.webp` → `textures/wood-floor.webp.link.json` |
| A material (materials live in the scene, not in files) | `links/materials/<material id>.link.json`, with the id percent-encoded into one filename segment — material ids can contain `:` and `/` |

The full filename is used, not the stem as `.meta.json` does, because `foo.glb` and `foo.png`
must not share a record.

**Shape** (`assetLinkRecordSchema`, `packages/shared/src/assetLinks.ts`), strict — unknown keys
are refused:

| Field | Meaning |
|---|---|
| `version` | literal `1` |
| `source` | the library item, as above |
| `sourceHash` | a hash of the source when the copy was last synced with it |
| `base` | the source's editable properties at that time — stored, never re-fetched, because a preset has no history and an old plugin commit may be unreachable later |
| `overrides` | `{ set?, unset? }` — the project's changes from `base` |
| `linkedAt`, `syncedAt` | ISO timestamps |
| `detached` | `{ at, reason }`, present once the copy's bytes were changed locally |

**What happens to it:**

- **It moves with its file.** Moving or renaming the file in the
  [Asset Explorer](https://diceytable.com/docs/editor/interface/asset-explorer#moving-copying-and-deleting) moves its
  `.link.json` too.
- **Changing the file's bytes detaches it.** Optimizing an image, splitting a model or uploading
  over the file asks first, then sets `detached`. The record stays so the credit can still say
  where the work came from, as an unlocked
  [`derivedFrom`](https://diceytable.com/docs/mods/manifest/reference#credits) credit.

The matching credit on the manifest is a [locked credit](https://diceytable.com/docs/mods/manifest/reference#credits).

The editor writes a record whenever it makes a linked copy: **Add to project**, pasting or
dropping library items into the Project pane, or **Duplicate to project**. See
[Credits and linked copies](https://diceytable.com/docs/editor/interface/asset-explorer#credits-and-linked-copies). A
project that still has a material using a built-in's id, from before linked copies existed,
gets a record under `links/materials/` written for it when the project opens.

### Baked thumbnails — `thumbnails/`

The editor renders a 256×256 WebP preview of your models, assemblies, materials, prefabs,
decks and textures, and keeps them in the repo so they don't have to be rendered again on every
open. How they are generated and shown is on
[The Asset Explorer § Thumbnails](https://diceytable.com/docs/editor/interface/asset-explorer#thumbnails).

| Subject | Thumbnail path |
|---|---|
| A file | `thumbnails/<repo path>.webp` — `models/keep.glb` → `thumbnails/models/keep.glb.webp` |
| A material | `thumbnails/@materials/<id>.webp` |
| A prefab | `thumbnails/@prefabs/<id>.webp` |
| The index | `thumbnails/index.json` |

The `@` keeps a material or prefab thumbnail from colliding with a real `materials/` folder; a
file path whose first folder starts with `@` gets an extra `@` for the same reason. Material
and prefab ids are escaped into a single filename segment.

`thumbnails/index.json` is `{ "version": 1, "rendererVersion", "entries": { <key>: { "inputHash", "file", "width", "height" } } }`.
`inputHash` covers everything that changes the picture — the item and what it depends on — so
the editor can tell which images are stale.

Three rules worth knowing:

- **Published, but never declared.** Thumbnails are pushed to GitHub with the rest of the repo,
  but they are **not** added to [`manifest.assets`](https://diceytable.com/docs/mods/manifest/reference#assets):
  `isDeclarableModAsset` excludes everything under `thumbnails/`. Players never download them to
  play, and they don't count against the declared-asset cap.
- **Never a sync conflict — for generated files.** If the local and GitHub copies of
  `thumbnails/index.json`, or of a thumbnail at exactly the path the editor would write
  (`thumbnails/<key>.webp`), differ, the local copy is kept and the image is regenerated. You
  are never asked to choose. Any **other** file you put under `thumbnails/` yourself — say
  `thumbnails/cover.png` — is yours, and a conflict on it prompts like any other file.
- **Hidden in the explorer.** Generated thumbnails appear on their subjects, not as files, and
  they move or are deleted along with the file they picture. A file you put under `thumbnails/`
  by hand is not generated, so the explorer shows it — but because nothing under `thumbnails/`
  is declared, don't keep assets a table needs in that folder.

Scripts, sounds, JSON and other text files have no thumbnail. Neither do card data files (they
show an icon) or deck card source images, since the deck's own thumbnail covers them.

### Folder keepers — `.keep`

A zero-byte `.keep` file makes an **empty folder** real. Git has no empty folders, and project
folders are otherwise derived from file paths, so a folder made with **New ▾ ▸ Folder** would
vanish on reload without one.

- It is hidden in the explorer.
- It is never declared in `manifest.assets`: `isDeclarableModAsset` requires an allowed file
  extension, and `.keep` has none.
- Once the folder holds anything else, the keeper is no longer needed and the editor removes it.

## Replication note

Neither sidecar type travels over the wire as its own object. A deck's resolved contents are copied into `TableObjectDefinition.metadata.customDeck` at spawn time (see `buildCustomDeckObjectMetadata()`); a model's meta sidecar is applied once, at spawn, to build the definition. Peers never fetch `.meta.json`/`.deck.json` files directly at runtime for a `TableIntent` — they're an *authoring-time* convenience, not part of the replicated protocol.

`collider` and `triggers` follow the same rule and go one step further: **neither becomes replicated per-entity state at all.** Every peer that loads the model resolves them itself from this file, so no snapshot field, no snapshot schema version and no migration changed to add them. Trigger volumes are local physics artefacts rebuilt per peer, and only the **host's** copies are ever sampled — which is why both trigger events are host-only.

## See also

- [Assets](https://diceytable.com/docs/mods/files/assets) — the generic content-type/size checks these files receive on top of the schema validation above.
- [Manifest reference § `assets`](https://diceytable.com/docs/mods/manifest/reference#assets) — a sidecar must be in `assets[]` to be fetched and validated. The editor declares it for you; a hand-built repo has to list it.
- [COLLISION](https://diceytable.com/docs/editor/inspector/collision) — the shape options `collider` authors, and the three conditions the runtime refuses a mesh-derived collider under.
- [`onTriggerEnter` (table script)](https://diceytable.com/docs/scripting-api/events#globaleventsontriggerenter) and [`onTriggerEnter` (mod)](https://diceytable.com/docs/scripting-api/hooks-and-capabilities#modhookeventmapontriggerenter) — the only two things a `triggers` entry ever does.

## `customDeckDefinitionSchema`

Exported from `@diceytable/shared` as `customDeckDefinitionSchema`. 42 fields across 6 tables.

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `schemaVersion` | `1` | **yes** | — | — | — | — | — |
| `id` | `string` | **yes** | — | 1–120 chars | — | — | — |
| `name` | `string` | **yes** | — | 1–120 chars | — | — | — |
| `face` | `customDeckSheetSchema` | **yes** | — | — | — | 1 further cross-field rule (message built at validation time). | — |
| `extraFaceSheets` | `customDeckSheetSchema[]` <br>same shape as `face` | no | — | <= 7 items | — | — | — |
| `uniqueBacks` | `boolean` | **yes** | — | — | — | — | — |
| `back` | `customDeckBackSchema` | **yes** | — | — | — | — | — |
| `sideways` | `boolean` | no | `false` | — | — | — | — |
| `cardRotationRule` | `customDeckRotationRuleSchema` | no | — | — | — | — | — |
| `art` | `customDeckArtSchema` | no | — | — | — | — | — |
| `backIsHidden` | `boolean` | no | `true` | — | — | — | — |
| `hiddenFaceIndex` | `integer` | no | — | >= 0, <= 9007199254740991 | — | — | — |
| `cardFields` | `customDeckFieldSchema[]` | no | `[]` | <= 64 items | — | — | — |
| `deckFields` | `customDeckFieldSchema[]` <br>same shape as `cardFields` | no | `[]` | <= 64 items | — | — | — |
| `data` | `customDeckDataSchema` | no | `{}` | — | — | 1 further cross-field rule (message built at validation time). | — |
| `cards` | `customDeckCardSchema[]` | **yes** | — | 1–1000 items | — | — | — |

Whole-object rules:

- 1 further cross-field rule (message built at validation time).

### `schemaVersion`

The version gate on the document shape, and the reason a `.deck.json` from a newer editor
fails loudly instead of half-loading. There is no migration function for deck definitions
the way there is for session snapshots, so a document that doesn't match this exact literal
is rejected whole — by the publish-time sidecar scan, and by the editor's own load path,
which turns it into *"This deck has no valid definition yet"* rather than a scrambled table.

That strictness is the point: a partially understood deck would put the wrong art on the
wrong card on every peer at once, which is far harder to notice than a file that refuses to
load. The deck editor stamps this for you; you write it only when hand-authoring.

### `id`

The deck's own identifier, copied into a spawned deck's `metadata.customDeck.definitionId`
so you can tell which definition a table Entity came from. Nothing resolves it: the sheet
grid and the whole card mapping travel with the Entity, so the runtime never looks the
definition back up by this value. Treat it as provenance, not as a handle.

The deck editor mints a UUID-backed value once and never rewrites it, so it survives renaming
the deck. Uniqueness is checked nowhere — two definitions can share an `id` and both work,
which costs you only the ability to tell their spawned Entities apart afterward.

### `name`

The deck's human-readable name. It becomes the spawned `deck` Entity's `label`, truncated to
80 characters, so it is what you read on the table and in the hierarchy, not only a caption
inside the editor.

Renaming a deck moves nothing on disk. The definition's slug, and with it the per-card image
folder under `assets/decks/`, are fixed when the deck is created and read back from
the file's own path afterward, so a renamed deck keeps its original folder name. That is
deliberate: re-slugging on rename would orphan every card image the deck owns.

### `face`

The sprite sheet every card's front is cut out of: one texture plus the grid that divides it.
This is the deck's FIRST face sheet, and on most decks its only one. A deck whose cards do not
fit a single 4096-pixel image continues onto `extraFaceSheets` — 62 poker-sized cards at
512x758 already need a second sheet — with each card's `faceIndex` staying one global cell
index across the whole run.

The grid fields are the contract between whatever composed the sheet and the runtime that
samples it. Get one of them wrong and nothing errors; every card renders the wrong rectangle. If you are building a sheet by hand, match the row-major-plus-V-flip convention
described under [sheet generation](https://diceytable.com/docs/editor/item-editors/deck#sheet-generation).

### `extraFaceSheets`

Face sheets two onwards, for a deck whose cards do not fit one image. `face` is always sheet
one; these follow it in order. Absent on a single-sheet deck, which is most of them.

**A card's `faceIndex` is one global cell index across the whole run**, not a
`{sheet, cell}` pair. Sheet one contributes its `cardCount` cells, then sheet two continues
the numbering, and so on. So on a deck whose first sheet holds 40 cards, `faceIndex: 40` is
the *first* cell of the second sheet. That is what lets every definition written before
multi-sheet decks existed keep working untouched: with no `extraFaceSheets`, the global index
and the cell index are the same number.

Look a cell up with `resolveDeckFaceCell()` rather than indexing `face` yourself. Indexing
`face` directly with a global index is silent on a multi-sheet deck — it reads out of range,
or worse, in range on the wrong sheet, and the card simply shows the wrong art.

At most eight sheets. The real limit is memory, not the format: a 4096-pixel sheet decodes to
64 MB of video memory, so the [Asset pack budget](https://diceytable.com/docs/editor/workflows/build-an-asset-pack) starts
warning at 96 MB and refuses at 256 MB across all of a pack's sheets. Lowering the card
resolution is usually the better answer to a deck that needs many sheets — halving the cell
size quarters the memory and quadruples the cards per sheet.

### `uniqueBacks`

Whether each card windows its own cell of the back sheet. This flag means something only when
`back.kind` is `"sheet"`: with a single back image the runtime returns that whole texture
before it ever consults this field, so on a single-back deck both `uniqueBacks` and every
`cards[].backIndex` are dead weight.

With a back sheet and this set, a card's back is its `backIndex`, falling back to its
`faceIndex` — Tabletop Simulator's parallel-sheets convention, where face cell `n` and back
cell `n` belong together — and then to cell 0. With a back sheet and this clear, every card
gets cell 0, which becomes the deck's one shared back. The deck editor writes only single
backs today, so a back sheet is hand-authored.

### `back`

Where the reverse of a card comes from: `{ "kind": "single", "texturePath": … }` for one
shared image, or `{ "kind": "sheet", "sheet": … }` for a grid with the same shape as `face`.

A single back is drawn as the entire texture with no windowing, so its pixel dimensions are
free — it does not have to match the face sheet's cell size or its aspect ratio. A back sheet
is sliced by exactly the same grid math as the face, and which cell a given card gets out of
it is decided by `uniqueBacks`. The deck editor writes only the single form, defaulting to a
generic back bundled with the client.

### `sideways`

Tabletop Simulator's "Sideways" flag, recording that the deck's cards are landscape rather
than portrait. It is persisted, and it travels to every peer inside `metadata.customDeck` —
but no runtime code path reads it. No card is rotated, resized or re-cropped because of it.
Set it to record your intent; do not set it expecting the table to change.

To actually ship a landscape deck, give the cells landscape pixels (`cardWidthPx` greater than
`cardHeightPx`) and scale the placed Entity to match.
See [Known limitations](https://diceytable.com/docs/reference/known-limitations).

### `cardRotationRule`

Derive each card's rotation from one of its **card fields**, so a set is tagged once instead of
being turned card by card.

A real TCG mixes orientations inside one deck. If a Star Wars TCG import gives every card a
`type` field, one rule — "`type` = `battle` → 90°" — turns every battle card in a 60-card deck.
Without it you would set [`rotationQuarter`](https://diceytable.com/docs/mods/files/sidecars#cardsrotationquarter) on each of them by hand, and
redo the work every time you re-import.

The rule is an **authoring convenience and nothing more**. It is resolved when the deck is
spawned, so the replicated `metadata.customDeck` slice carries one resolved number per card and
never the rule itself: the runtime does no rule evaluation per draw, and a mod script reading a
drawn card sees a plain `rotationQuarter`. The practical consequence is that editing a rule
reaches the table the way any other deck edit does — by respawning the deck, not by mutating
decks already in play.

Precedence is fixed: a card's own `rotationQuarter` wins, then this rule's
[`match`](https://diceytable.com/docs/mods/files/sidecars#cardrotationrulematch), then its [`fallback`](https://diceytable.com/docs/mods/files/sidecars#cardrotationrulefallback), then
upright. `resolveCardRotationQuarter()` is the only correct implementation of that order — call
it rather than reading the fields yourself.

Omit the whole block for a deck whose cards are all one way up. Nothing is defaulted in, so a
deck authored before rotation existed is byte-identical after a save.

### `art`

How a card's source image is framed on the card, and what shape the card itself is. Optional:
a deck without an `art` block behaves exactly as decks did before the block existed — cover,
no bleed, square corners, white background — so nothing already published changes appearance.

Everything here except `cornerRadius` is baked into the generated face sheet's PIXELS, which
is why changing any of it marks the sheet dirty in the deck editor and needs a Generate &
Save rather than a plain Save. Because they apply at composition time rather than at import,
they stay editable for the life of the deck; the per-card images keep their original aspect
ratio precisely so this remains true.

`cornerRadius` is the exception: it is copied onto `metadata.customDeck` and read by the
runtime, which generates the card body's mesh from it. See
[Card art](https://diceytable.com/docs/editor/item-editors/deck#card-art).

### `backIsHidden`

Accepted for backwards compatibility and **no longer read**. A hidden card shows its back
whatever this is set to.

It used to select between "the last cell of the face sheet" (its default) and "the card's
back". That default only makes sense for decks authored the Tabletop Simulator way, with a
generic image reserved in the final cell; every other deck has a real card there, so every
card held in every opponent's hand rendered as that one card's art.

Use [`hiddenFaceIndex`](https://diceytable.com/docs/mods/files/sidecars#customdeckdefinitionschemahiddenfaceindex) to reserve a cell
deliberately.

### `hiddenFaceIndex`

A face-sheet cell reserved as the stand-in another player sees in place of a card you are
holding. Leave it out — the default — and they see the card's **back**, which is what a
physical card does.

Set it only if your sheet actually contains a generic "?" image, the way Tabletop Simulator
decks conventionally reserve their final cell. Naming a cell that holds a real card shows
that card's art on every hidden card at the table.

This is a choice about substitute art, not about secrecy. What keeps the card secret is
host-side redaction: the host strips the `cardId` out of the snapshot before sending it to a
peer who isn't entitled to that card's identity, whatever this field says.

> **Replaces the old `backIsHidden` behaviour.** That flag used to select between "the last
> face-sheet cell" (its default) and "the back", so any deck whose last cell was a real card
> — every deck not authored for Tabletop Simulator — showed that card's face for every hidden
> card in the game. `backIsHidden` is still accepted so existing definitions load, but is no
> longer read.

### `cardFields`

The deck's **card data model**: the fields every card in the deck has, with the value each
card inherits until it says otherwise. Declaring a model here is what makes per-card data
navigable — the deck editor renders one labelled control per field on every card tile, and a
script reading a card knows which keys to expect instead of guessing at a free-form bag.

A field's `defaultValue` lives here, once; a card overrides it by putting the same key in its
own `data`. That split is the point: a 100-card deck with a `cost` field that is 0 on 90 cards
stores one default and ten overrides.

The list travels with every spawned deck and every card drawn out of it, on
`metadata.customDeck.cardFields`, so a table or mod script can resolve a card's values without
loading the `.deck.json`. Keys must be unique across the list — a duplicate is a validation
error rather than a silent last-one-wins.

`deckFields` is the same shape for the deck itself; see that field for the distinction.

### `deckFields`

The **deck's own** field model — facts about the deck as a whole rather than about any one
card: a ruleset name, a starting hand size, an expansion label. Same shape as `cardFields`,
and the same uniqueness rule, but the values live in the deck's single `data` bag instead of
being inherited by anything.

Use `cardFields` when the value differs card to card (even if most cards agree); use
`deckFields` when there is exactly one answer for the whole deck. Putting a deck-wide constant
in `cardFields` works, but you pay for it in a default that every card carries the meaning of.

Like `cardFields`, this list is copied onto every spawned deck — and onto every card drawn out
of it, so a lone card still knows which deck's rules it came from.

### `data`

The deck's own field values — the counterpart to `deckFields`, exactly as a card's `data` is
the counterpart to `cardFields`. Sparse in the same way: an absent key inherits that field's
`defaultValue`. `resolveDeckData(def)` merges the two and coerces each value to its declared
type.

Undeclared keys are preserved rather than dropped, so a mod may stash its own values here; they
are passed through without coercion because no field declares their type.

Values are flat scalars only (string, number, boolean, `null`) and the bag holds at most 64
keys. It is replicated on every spawned deck, so keep it to facts the table actually needs —
a rules document belongs in the mod's files, not in here.

### `cards`

The deck's **distinct** card list, and its starting order: entry 0 becomes the top of the
spawned deck. Position here does **not** pick a card's art — `faceIndex` does — so you can
reorder the deck without touching a single index. The deck editor writes the two in step,
which makes a saved file look more constrained than the schema is.

This array is *not* the deck's size. Each entry carries a `count` of physical copies, and the
spawned Entity's `stackCount` is the sum of those counts, not this array's length. Both are
capped at 1000: the array by its own `max`, the total by a whole-object rule, so a definition
that validates always spawns at its full size rather than being silently trimmed.

Card identities must be unique — see `cardId`.

### `customDeckDefinitionSchema.face`

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `texturePath` | `string` | **yes** | — | 1–400 chars | — | — | — |
| `columns` | `integer` | **yes** | — | >= 1, <= 64 | — | — | — |
| `rows` | `integer` | **yes** | — | >= 1, <= 64 | — | — | — |
| `cardCount` | `integer` | **yes** | — | >= 1, <= 9007199254740991 | — | — | — |
| `cardWidthPx` | `integer` | **yes** | — | >= 1, <= 8192 | — | — | — |
| `cardHeightPx` | `integer` | **yes** | — | >= 1, <= 8192 | — | — | — |

Whole-object rules:

- 1 further cross-field rule (message built at validation time).

#### `face.texturePath`

The repo-relative path of the face sheet, resolved exactly like a custom model's texture: a
peer prefers a copy already primed in its local cache, and otherwise pulls the bytes straight
from `raw.githubusercontent.com` for your repo at the published ref. No sheet image is ever
stored on the platform's servers.

Declare it in `assets[]` like any other file — see [Assets](https://diceytable.com/docs/mods/files/assets). A path
that resolves to nothing does not break the deck: the cards fall back to the standard card
materials, so the failure looks like a deck that lost its art rather than an error anyone
gets told about.

#### `face.columns`

How many cells wide the grid is. With `rows`, it is the only thing that decides where a card's
rectangle lands: cell `n` sits at column `n % columns`, row `floor(n / columns)`, counting from
the top-left of the composed image.

Get it off by one and nothing fails validation — every card past the first row is cropped from
the wrong place, and the deck renders as a scramble of card halves. Read this off the sheet you
actually composed, never off the card count.

#### `face.rows`

How many cells tall the grid is. It sets each cell's height in UV space and, with it, the
vertical flip: sheet images are composed with row 0 at the top, while texture space puts
`v = 0` at the bottom, so the runtime maps row `r` to `1 - (r + 1) / rows`.

You never do that arithmetic yourself — the shared `cardSheetUvWindow` helper owns it, and the
deck editor's compositor is written against the same convention. It matters the moment you
build a sheet by hand: pack it top-left first, or the cards come out mirrored top to bottom
against what the image shows.

#### `face.cardCount`

How many of the grid's cells actually hold a card. It does not have to equal `columns × rows` —
trailing cells on the last row are allowed to sit empty — and only the "too many" direction is
rejected: a
count larger than the grid holds fails validation with the grid size quoted back at you. A
count *smaller* than the grid is normal and costs nothing.

It carries a second job that is easy to miss. The hand-hidden stand-in face defaults to cell
`cardCount - 1`, so rounding this number up to something tidy points that stand-in at a blank
cell, and other players see an empty rectangle where a card back belongs. Every
`cards[].faceIndex` is validated against it too.

#### `face.cardWidthPx`

The width of one cell in the source texture, in pixels. It is not the card's width on the
table — a placed card is sized by its Entity's scale, in feet — and the runtime does not use it
to compute a card's crop rectangle either. That comes from `columns` and `rows` alone.

What it is actually for: with `columns`, it reconstructs the sheet's full pixel width so the
one-pixel anti-bleed gutter can be converted into a UV inset. Report the real cell width and
the gutter is one real pixel; report an invented one and the inset is the wrong size, which
shows up as a hairline of the neighboring card along a card's edge.

#### `face.cardHeightPx`

The height of one cell in the source texture, in pixels — the vertical half of the job
`cardWidthPx` does, feeding the sheet's full pixel height so the anti-bleed gutter converts to
the right UV inset. It does not set how tall a card is on the table; the placed Entity's scale
does, in feet.

The two together fix your cards' aspect ratio, and the deck editor re-encodes every new upload
to them, so changing them is how you reshape a deck between poker, bridge and square. Cards
already uploaded keep the pixels they were encoded at and stretch to fill the new cell, which
is why a mid-deck change looks like it did nothing until you re-upload.

### `customDeckDefinitionSchema.cardRotationRule`

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `fieldKey` | `string` | **yes** | — | — | `^[A-Za-z_][A-Za-z0-9_]{0,39}$` | — | — |
| `match` | `Record<string, cardRotationQuarterSchema>` | **yes** | — | — | — | — | — |
| `fallback` | `cardRotationQuarterSchema` | no | — | — | — | — | — |

#### `cardRotationRule.fieldKey`

Which **card field** selects the rotation — the key, not the label.

The value looked up for a card is its own override in `data`, falling back to the field's
declared `defaultValue`. That fallback is what makes a rule cheap to apply: declare
`type` with `defaultValue: "unit"`, and only the cards that are *not* units need a `data` entry
at all.

The key does not have to be declared in [`cardFields`](https://diceytable.com/docs/mods/files/sidecars#cardfields) — data bags tolerate
undeclared keys, so a rule can key off something a mod script writes. It is a much better idea
to declare it: the deck editor can only offer a rotation rule for fields it knows about, and an
undeclared key gives you no UI and no validation.

A key that no card carries and no field declares is not an error. Every card simply misses,
and the rule's [`fallback`](https://diceytable.com/docs/mods/files/sidecars#cardrotationrulefallback) applies.

#### `cardRotationRule.match`

Field value → quarter turns.

Values are compared **as strings**, so `"battle"`, `2` and `true` all work as keys and a
numeric or boolean field needs no special handling: a card whose `type` is the number `2`
matches the key `"2"`. This is deliberate — the alternative is a per-type comparison table that
silently fails to match the moment a field's type changes under it.

`null` never matches. It is "no value", not the string `"null"`, so a card whose field is
explicitly null falls through to [`fallback`](https://diceytable.com/docs/mods/files/sidecars#cardrotationrulefallback) exactly like a card
that has no value at all. An absent field behaves the same way.

Only list the values you actually want turned. Anything unlisted falls to `fallback` (and, with
no fallback, to upright), so a deck of mostly-portrait cards needs one entry, not one per card
type.

#### `cardRotationRule.fallback`

The rotation for a card whose value matches nothing in [`match`](https://diceytable.com/docs/mods/files/sidecars#cardrotationrulematch) —
including a card with no value for the rule's field at all, and one whose value is `null`.

Omit it for the ordinary case: an unmatched card is then upright, which is what you want when
`match` lists the exceptions. Set it when the exceptions run the other way — a deck of
landscape cards with a handful of portrait ones is expressed as `fallback: 1` plus a short
`match` for the upright few, rather than as a `match` entry per landscape card.

A per-card [`rotationQuarter`](https://diceytable.com/docs/mods/files/sidecars#cardsrotationquarter) still overrides this, so a fallback can
never trap an individual card at the wrong orientation.

### `customDeckDefinitionSchema.art`

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `fit` | `"cover"` \| `"contain"` | no | `"cover"` | — | — | — | — |
| `bleedPx` | `integer` | no | `0` | >= 0, <= 256 | — | — | — |
| `cornerRadius` | `number` | no | `0` | >= 0, <= 0.25 | — | — | — |
| `backgroundColor` | `string` | no | `"#ffffff"` | — | `^#[0-9a-fA-F]{6}$` | — | — |

#### `art.fit`

Whether a source image fills the card or fits inside it.

`cover` scales the image until it covers the whole cell and crops whatever overflows — the
right choice for full-bleed card art, and the default. `contain` scales until the entire
image is visible and fills the remainder with `backgroundColor`, which is what you want for
art whose edges matter (a bordered illustration, a scanned card, a logo).

Both modes preserve the source's aspect ratio. Neither ever stretches it non-uniformly.

#### `art.bleedPx`

How far the art is pushed PAST the card's edge, measured in card-cell pixels. Print bleed,
minus the physical trimming: raise it when a card's art has no margin and you would rather
lose a sliver of the edge than risk a hairline of background showing at the corners.

**Not an exact per-edge guarantee on a non-square card.** Preserving the source aspect means
one uniform scale factor, so growing the art enough to clear the short axis by `bleedPx`
clears the long axis by proportionally more. `cover` guarantees *at least* `bleedPx` on every
edge and exactly that much on the tightest one. An exact bleed on all four sides would require
scaling the axes differently, i.e. distorting the author's art.

Unrelated to `CUSTOM_DECK_SHEET_GUTTER_PX`, the fixed one-pixel gutter the sheet composer
draws to stop texture filtering sampling a neighbouring cell. That one guards rendering; this
one is a framing decision.

#### `art.cornerRadius`

The card's corner rounding, as a fraction of its SHORT edge — `0` is a square corner and
`0.25` is the maximum. Expressing it against the short edge rather than in pixels is what
makes a poker card and a square card look equally rounded at the same value.

**This reshapes the card, not just the artwork.** The runtime generates the card body's mesh
from this number, so it changes the physical silhouette of the deck and of every card drawn
out of it. That is why it is copied onto `metadata.customDeck` and travels to every peer: the
sheet's rounded artwork and the generated body have to agree, or a rounded corner would show
a sliver of the wrong thing.

The deck editor previews it live against a real card image.

#### `art.backgroundColor`

The `#rrggbb` fill behind the card art: the letterbox in `contain`, and the area outside the
rounded corners at any non-zero `cornerRadius`. Defaults to white.

The corner fill is normally invisible, because the generated card body is rounded by the same
`cornerRadius` and simply has no geometry there. It matters when you deliberately round the
art more than the body, and it is what you see in the deck editor's preview — so set it to
your card's border colour rather than leaving it white on a dark deck.

### `customDeckDefinitionSchema.cardFields`

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `key` | `string` | **yes** | — | — | `^[A-Za-z_][A-Za-z0-9_]{0,39}$` | — | — |
| `label` | `string` | no | — | 1–60 chars | — | — | — |
| `type` | `"text"` \| `"number"` \| `"boolean"` \| `"select"` | **yes** | — | — | — | — | — |
| `defaultValue` | `customDeckDataValueSchema` | no | — | — | — | — | — |
| `options` | `string[]` | no | — | <= 1024 items; each 1–120 chars | — | — | — |

Whole-object rules:

- 1 further cross-field rule (message built at validation time).

#### `cardFields.key`

The name the value is stored under, in both a card's `data` and the deck's `data`, and the
name a script reads it by. Constrained to a script-safe identifier — a letter or `_` first,
then letters, digits and `_`, up to 40 characters — so `data.cost` always works and no consumer
has to quote or escape anything.

Keys must be unique within their list. Renaming one in the deck editor migrates every stored
value across the whole deck; renaming one by hand in the `.deck.json` does not, and orphans
every value still filed under the old name (they survive as undeclared keys rather than being
deleted, so the fix is to rename them too).

#### `cardFields.label`

A human display name for the field, shown above its control in the deck editor. Purely
cosmetic — nothing joins on it, and omitting it falls back to showing the `key`.

Set it when the key has to stay terse for scripts but the editor deserves better: `key: "atk"`
with `label: "Attack"`.

#### `cardFields.type`

What kind of value the field holds, which picks the deck editor's control and the coercion
applied when a value is read:

| Type | Editor control | Coercion |
|---|---|---|
| `text` | single-line text box | anything stringifies |
| `number` | number box | numeric strings parse; anything else reads as `null` |
| `boolean` | checkbox | `"true"` and `1` read as `true` |
| `select` | dropdown over `options` | a value not in `options` reads as `null` |

Coercion happens at **read** time (`resolveDeckCardData` / `resolveDeckData`), not at
validation time — the schema does not reject a value that disagrees with its field's type.
That is deliberate: changing a field's type must not make an authored deck unloadable. The
deck editor converts stored values in place when you change a type, so what you see there is
already the coerced result.

`select` additionally requires a non-empty `options` list; a select without one is a
validation error.

#### `cardFields.defaultValue`

The value inherited by everything that has not overridden this field — every card in the deck
for a `cardFields` entry, the deck itself for a `deckFields` entry. Storing it once here, and
only the exceptions per card, is what keeps a large deck's `.deck.json` (and its replicated
`metadata.customDeck` slice) small.

Omitting it is not the same as setting it to `null` in the file, but it resolves the same way:
a field with no default reads as `null` until something overrides it.

A default that disagrees with the field's `type` is coerced when read, not rejected — see
`type`.

#### `cardFields.options`

The allowed values for a `select` field, in the order the deck editor's dropdown lists them.
Required and non-empty when `type` is `select` — a select with no choices is a validation
error, not an empty dropdown.

Ignored for every other type. The deck editor drops the list outright when you change a field
away from `select`, so it does not linger as dead weight in the file.

A stored value that is not in this list reads as `null` (see `type`), which is what happens
after you remove a choice that cards were already using — those cards fall back to the field's
`defaultValue`, or to `null` if there isn't one.

### `customDeckDefinitionSchema.cards`

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `cardId` | `string` | **yes** | — | 1–120 chars | — | — | — |
| `label` | `string` | no | — | <= 120 chars | — | — | — |
| `faceIndex` | `integer` | **yes** | — | >= 0, <= 9007199254740991 | — | — | — |
| `backIndex` | `integer` | no | — | >= 0, <= 9007199254740991 | — | — | — |
| `count` | `integer` | no | `1` | >= 1, <= 1000 | — | — | — |
| `data` | `customDeckDataSchema` | no | — | — | — | 1 further cross-field rule (message built at validation time). | — |
| `assetPath` | `string` | no | — | 1–400 chars | — | — | — |
| `rotationQuarter` | `cardRotationQuarterSchema` | no | — | — | — | — | — |

#### `cards.cardId`

A card's identity, and the value everything else joins on. The spawned deck's replicated
per-card entries carry it, the runtime looks up a card's sheet cell by it, and the host's
hidden-information redaction strips exactly this string out of a snapshot before it reaches a
peer who isn't entitled to see that card — so it is also the one thing a cheating client would
want and cannot get.

It must be unique within the deck, and that **is** validated: a duplicated `cardId` is a
rejection, because copies of a card are expressed with `count` rather than by repeating an
entry. A `cardId` the mapping doesn't contain falls back to the standard card materials.

The ids that reach the table are *instance* ids, not these: with `count` copies, copy 1 keeps
this string and copies 2..N get a `#2`, `#3`, … suffix. Lookup strips a trailing `#<digits>`
to get back here, so a `cardId` of your own that ends that way (`"set#2"`) is indistinguishable
from a copy — don't write one.

#### `cards.label`

An optional human-readable name for one card — `The Fool`, `Fireball`. It is authoring
metadata: the deck editor shows it in the card grid and restores it when you reopen the deck,
and no runtime code path reads it. It does not name the table Entity, and it is not a slug.

Do not reach for it as an identifier; `cardId` is what the runtime and redaction key on.
And do not put anything secret in it: the whole card list is copied into the spawned Entity's
`metadata.customDeck`, which every peer needs in order to render, and redaction neutralizes
card *identities* there, not labels.

#### `cards.faceIndex`

Which cell of the face sheet this card's front is cut from, counted row-major from the
top-left. It is validated against `face.cardCount`, with the offending index and the sheet size
quoted in the message, so an out-of-range front is caught at publish time rather than at the
table.

It is independent of the card's position in `cards`: two cards can point at the same cell, and
the deck's order can change without any index moving. The deck editor happens to write index
and position in step, which is worth knowing before you hand-edit a saved deck and assume the
pairing is enforced.

#### `cards.backIndex`

Which cell of the back sheet this card's reverse is cut from. It is consulted only when
`uniqueBacks` is set *and* `back.kind` is `"sheet"` — and it is validated only under those same
two conditions, so an out-of-range value on a single-back deck passes the scan and then never
matters, because nothing reads it.

Omit it on a unique-backs deck and the card falls back to its own `faceIndex`, which is
Tabletop Simulator's parallel-sheets layout; if that is out of range for the back sheet, cell 0.
See `uniqueBacks` for what the flag changes about this field and about `back`.

#### `cards.count`

How many **physical copies** of this card the deck spawns with. This is the whole reason a
100-card deck of 14 distinct designs does not need 100 images: copies share one sheet cell,
one `faceIndex`, one label and one `data` row, so the face sheet is sized by the number of
*distinct* cards (`face.cardCount`) and never by the deck's actual size.

Every copy still needs its own identity, because the deck's replicated per-card entries key
everything off `cardId`. Copy 1 keeps the plain `cardId`; copies 2..N get a `#2`, `#3`, …
suffix — `expandDeckCardIds()` builds that list and `baseDeckCardId()` maps a suffixed id back
to this entry, which is how a copy finds its shared cell. A deck authored before `count`
existed is byte-identical under the new rules: every entry defaults to `count: 1` and every
instance id stays exactly the `cardId` you wrote.

The copies of one card are emitted **together**, in definition order, so a freshly spawned deck
is grouped rather than interleaved. Shuffle it if you want otherwise.

The 1000 ceiling here is per entry; a whole-object rule also rejects a definition whose counts
*add up* past 1000, so a deck that validates always spawns at its full size. A card's copies
are indistinguishable in play — they carry identical data — so use `count` for genuine
duplicates and separate entries for cards that differ in any way.

#### `cards.data`

This card's **overrides** of the deck's `cardFields` defaults. Sparse on purpose: a key that
is absent means "inherit", not "empty", so a deck whose cards mostly agree with the model
stores almost nothing per card. `resolveDeckCardData(cardFields, card)` is the function that
merges the two and coerces each value to its declared type; read the result rather than this
bag directly, or you will see holes where a default should be.

Keys the deck's `cardFields` do **not** declare are kept verbatim rather than dropped, so a
mod can stash its own values here and they survive a round-trip through the deck editor. They
are also passed through uncoerced — nothing validates them against a type, because there is no
type to validate against.

Values are flat scalars only (string, number, boolean, `null`). There is no nesting: this bag
is copied onto every spawned deck and onto every single card drawn out of it, and it rides in
snapshots to every peer, so it is deliberately cheap to serialize. All copies of a card share
this one row — see `count`.

#### `cards.assetPath`

The individual image this card's cell was built from, repo-relative — the link from a packed
deck back to the source art it was assembled out of.

Nothing reads it at render time: the runtime windows the packed sheet, which is the whole point
of packing. It matters for everything you do to a deck *after* building it — re-gridding it,
adding a card, exporting the originals — all of which need the sources still present.

The deck editor writes this and always has. Declaring it here is what makes it survive being
parsed: an undeclared key is stripped, so every tool that inspected a loaded definition saw
cards with no sources and concluded the source images were orphans. The project explorer
offered to delete the very files the deck needs.

Optional, because a deck assembled from a sheet you supplied directly has no per-card sources
to point at.

#### `cards.rotationQuarter`

Quarter turns applied to this card when it is **drawn**, clockwise as the card is seen
face-up: `0` upright, `1` = 90°, `2` = 180°, `3` = 270°.

Rotation is a render-time property and is never baked into the face sheet. Every cell of the
sheet is still composed at the same orientation, which is what keeps the packing trivial, keeps
a re-grid cheap, and lets you turn a card without regenerating any art. What changes is how the
card is drawn: the runtime turns the card's UV window onto its own cell, and an **odd** quarter
also swaps the card body's width and height, because a quarter-turned portrait card is a
landscape card. Rotating the art without swapping the body would squash it.

This field is what `sideways` only ever recorded — see
[`sideways`](https://diceytable.com/docs/mods/files/sidecars#sideways), which is persisted but read by nothing. Use
`rotationQuarter` when you want the table to actually change, and use it per card: a real TCG
mixes orientations inside one deck (Star Wars TCG battle and location cards are printed
landscape while units are portrait).

Leave it **absent** to let the deck's [`cardRotationRule`](https://diceytable.com/docs/mods/files/sidecars#cardrotationrule) decide. That is
why it is optional rather than defaulting to `0`: an absent value means "follow the rule",
while an explicit `0` pins this one card upright *against* the rule. Resolve the two with
`resolveCardRotationQuarter()` rather than reading this field directly — nothing else applies
the precedence correctly.

Only the card's **face** turns. Its back is drawn upright, because backs are symmetric art and
a turned back on a face-down landscape card just looks broken. The reserved
[`hiddenFaceIndex`](https://diceytable.com/docs/mods/files/sidecars#hiddenfaceindex) cell is drawn upright too: it is one shared image, and
turning it with the card underneath would leak that card's orientation to opponents — for a
card type that is always landscape, that is a real tell.

Copies of a card share its rotation, the same way they share a sheet cell and a data row.

## `modelAssetMetaSchema`

Exported from `@diceytable/shared` as `modelAssetMetaSchema`. 53 fields across 7 tables.

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `kind` | `"card"` \| `"deck"` \| `"die"` \| `"token"` \| `"board"` \| `"bag"` \| `"custom"` \| `"card-holder"` \| `"button"` \| `"table"` \| `"coin"` | no | — | — | — | — | — |
| `material` | `soundMaterialSchema` | no | — | — | — | — | — |
| `flippable` | `boolean` | no | — | — | — | — | — |
| `color` | `string` | no | — | — | `^#[0-9a-f]{6}$` | — | — |
| `rotation` | `vector3TupleSchema` | no | — | — | — | — | — |
| `scale` | `vector3TupleSchema` <br>same shape as `rotation` | no | — | — | — | — | — |
| `spawnHeight` | `number` | no | — | >= 0 | — | — | — |
| `faceDown` | `boolean` | no | — | — | — | — | — |
| `locked` | `boolean` | no | — | — | — | — | — |
| `stackCount` | `integer` | no | — | >= 1, <= 1000 | — | — | — |
| `containerMode` | `"random"` \| `"stack"` \| `"queue"` | no | — | — | — | — | — |
| `capacityLimit` | `integer` | no | — | >= 1, <= 1000 | — | — | — |
| `container` | `modelContainerDefaultsSchema` | no | — | — | — | — | — |
| `tags` | `string[]` | no | — | <= 100 items; each 1–32 chars | `^[a-z0-9_-]+$` | — | — |
| `metadata` | `Record<string, unknown>` | no | — | — | — | — | — |
| `materialSlots` | `materialSlotsSchema` | no | — | — | — | materialSlots may not hold more than 64 entries. | — |
| `castShadows` | `boolean` | no | — | — | — | — | — |
| `receiveShadows` | `boolean` | no | — | — | — | — | — |
| `lightmapStatic` | `boolean` | no | — | — | — | — | — |
| `originAuthored` | `boolean` | no | — | — | — | — | — |
| `bodyType` | `"static"` \| `"dynamic"` \| `"kinematic"` | no | — | — | — | — | — |
| `mass` | `number` | no | — | > 0 | — | — | — |
| `friction` | `number` | no | — | >= 0, <= 1 | — | — | — |
| `restitution` | `number` | no | — | >= 0, <= 1 | — | — | — |
| `linearDamping` | `number` | no | — | >= 0, <= 1 | — | — | — |
| `angularDamping` | `number` | no | — | >= 0, <= 1 | — | — | — |
| `collisionShape` | `"auto"` \| `"box"` \| `"sphere"` \| `"capsule"` \| `"cylinder"` \| `"convexHull"` \| `"mesh"` | no | — | — | — | — | — |
| `collider` | `modelColliderSchema` | no | — | — | — | — | — |
| `triggers` | `modelTriggerVolumeSchema[]` | no | — | <= 8 items | — | — | — |
| `containerInterior` | `containerInteriorSchema` | no | — | — | — | — | — |

### `kind`

What kind of piece this model spawns as — a `die`, a `token`, a `board`, a `card-holder`, and so on.
Optional: omit the key and the model spawns as `custom`, which is what every model without a sidecar
does and what every sidecar written before this key existed still means.

The kind is what decides which gameplay actions and sound events an object has at all: a model
classified as `die` can be rolled and reports a face value, one classified as `board` is static and
has no pickup sound. Because that is a property of the model itself — a model that *is* a die is a
die every time it is placed — it belongs here rather than on each entity in `setup.json`. The Model
editor's **Spawn defaults ▸ Type** dropdown writes it.

An individual entity can still be reclassified after it is on the table (Edit Mode's **PIECE ▸
Type**), and a `kind` given explicitly in `setup.json` wins over this one. Unlike
[`collider`](https://diceytable.com/docs/mods/files/sidecars#collider), this is not per-asset-only config: it is applied
into the spawn definition, so it reaches replicated state and every peer sees the same
classification without reading the sidecar.

Pairs with [`material`](https://diceytable.com/docs/mods/files/sidecars#material), which the kind supplies a default for.

### `material`

The piece's physical **surface** — `wood`, `cardboard`, `metal`, `plastic`, `card`, `tile`,
`felt`, `cloth`, `glass`, `stone`, `generic` or `silent` — applied to every entity spawned from the model.
Optional: omit the key and the surface is resolved from [`kind`](https://diceytable.com/docs/mods/files/sidecars#kind), so
an unset value means "whatever this kind normally is", never silence.

Surface is a semantic descriptor, not a clip id. It selects which impact sounds a piece makes when
it is placed, dropped or slid, it colours the sound of every piece that lands **on** it (a felt-topped
board muffles, a glass one rings — see [SoundMaterial](https://diceytable.com/docs/reference/enums/sound-material#struck-surface-tone)),
and it supplies the physics baseline — mass scales with the surface's
density and the model's `scale`, friction and bounce come from the surface itself. Changing **Spawn
defaults ▸ Surface** in the Model editor re-derives `mass`, `friction`, `restitution`,
`linearDamping` and `angularDamping` in this same sidecar; you can then tune any of those numbers by
hand and they are kept.

Like `kind`, this is applied into the spawn definition rather than kept as per-asset-only config, and
an entity can override it on the table (Edit Mode's **PIECE ▸ Surface**).

### `flippable`

Whether a `token` spawned from this model offers **Flip** (turn it over 180°). Optional, and
almost always omitted: absent means "decide from the shape" — a token whose height is at most half
its narrower footprint is flat and flips, anything taller does not — which is already right for a
checker, a coin, a chit or a meeple.

Set it when the shape guesses wrong for your model: `true` for a two-sided marker that is chunkier
than half its width, `false` for a flat standee or tile that must never be turned face down. The
Model editor writes it from **Spawn defaults ▸ Flippable** (Auto / Yes / No, shown only while
**Type** is Token); **Auto** removes the key.

Unlike [`castShadows`](https://diceytable.com/docs/mods/files/sidecars#castshadows), this is not per-asset-only config.
`applyModelAssetMetaToDefinition()` copies it into the spawn definition, so it becomes the
entity's own replicated [`flippable`](https://diceytable.com/docs/mods/reference/object-state#flippable) — every peer
agrees on it, it survives a save, and the Inspector (**PIECE ▸ Flippable**) can override it on one
piece. Changing the sidecar later affects pieces spawned afterwards, not ones already on the table.

Ignored for every `kind` but `token`: cards and decks always flip, and no other kind does.

### `color`

For an imported model this tints the procedural stand-in box the entity shows while the GLB is still
loading — and keeps showing if the file never resolves. Once the model attaches, the runtime disables that
box's `render` component and the GLB's own materials take over, so the color you set here is invisible on a
healthy load and is the only thing a player sees on a broken one.

Pick something deliberately unlike the finished piece. A magenta stand-in reads as "this model did not
load"; a wood brown one reads as a wooden piece and hides the failure until someone tries to grab it. To
change how the model itself looks, edit its materials in the
[Material editor](https://diceytable.com/docs/editor/item-editors/material) rather than reaching for a color here.

### `rotation`

Euler angles in **degrees**, applied to the entity at spawn. The runtime rests an imported model with its
X/Z center on the object origin and its lowest point at `y = 0`, so these angles pivot the model around the
point it stands on: a yaw spins it in place, while pitch and roll swing its base through the table surface.

Use it to correct a model that was authored facing the wrong way, not to pose one. A pose that leaves the
model leaning does not survive first contact with gravity unless the entity is `locked` or its `bodyType`
is `static` — see the three axis fields below.

### `scale`

A multiplier on the model's authored size, not a size in feet. The runtime measures an imported model and
rests it on the object origin but leaves its scale at 1 — it deliberately does not normalize it into a unit
box the way a card is normalized — so `2` means "twice as big as whatever came out of your modeling tool".

That makes this the field to reach for when a model arrives at the wrong size, and it makes an extreme value
a signal to fix the export instead: world units are feet, so a model authored in millimeters arrives
hundreds of feet tall. The collider is fitted to the *scaled* bounds, so this changes what the piece
collides with as well as how big it looks.

### `spawnHeight`

Feet above the table surface, and the one sidecar field the overlay deliberately leaves alone:
`applyModelAssetMetaToDefinition` skips it because a spawn position is scene-specific, so Edit Mode reads
it separately when it works out where the drop lands.

It behaves as a floor rather than an exact height — the drop point's own height wins when that is higher —
and Edit Mode falls back to half a foot when the field is absent. The Model editor's Spawn height control
stops at 10 ft, so a hand-edited sidecar can set a value no one can produce through the UI and drop the
model in from off-screen. Raise it for something meant to fall into place; keep it near zero for a board or
a tile you want laid flat, because anything dropped from height drifts before it settles.

### `faceDown`

Applies to: `card` and `deck`. Those are the only kinds with a face — the setup-template schema refuses
`faceDown` on any other kind, and the hidden-information redactor requires `kind` to be `card` or `deck`
*and* this flag to be set before it hides an identity from a peer.

A model sidecar spawns a [`custom`](https://diceytable.com/docs/mods/reference/object-kinds#custom) entity, so a `faceDown` set
here is a replicated boolean that no code path reads. The field is in the shape because the sidecar mirrors
the model preset's default-property block, and a preset can be a card. Leave it out, and turn a card over
with the card's own flip action.

### `locked`

Locked does two things a static `bodyType` does not: the body is created `static` **and** the entity refuses
grabs, drags and pointer transforms. If what you mean is "this never moves and nobody picks it up", this is
the field — `bodyType` on its own only settles how the body simulates.

It is a starting state, not a permission. The lock/unlock object action flips it at the table and the new
value replicates like any other state, so a player can always release a piece you shipped locked. Set it
for boards, terrain and table furniture that a stray die should never shove; leave it off for anything a
player is meant to pick up.

### `stackCount`

Applies to: `deck`. A deck's visible height is its card count multiplied by its paper thickness, and the
draw and deal paths stop running once the count reaches zero — on a deck this one number is both the model
and the gate.

A model sidecar spawns a [`custom`](https://diceytable.com/docs/mods/reference/object-kinds#custom) entity, where neither of
those paths exists: the value rides along in the definition and replicates, and nothing on the table
changes. It is in the shape because the sidecar mirrors the model preset's default-property block, and a
preset can be a deck. Build a real deck in the [Deck editor](https://diceytable.com/docs/editor/item-editors/deck) instead.

### `containerMode`

Applies to: `deck` and `bag`. It names the order the host takes items out — `stack` from the front of the
pile, `queue` from the back, `random` from anywhere — and the draw and deal paths refuse to run on any
other kind.

It is a real default, carried onto every object spawned from this model and obeyed by the draw:
`resolveContainerConfig` (`packages/shared/src/tableContainers.ts`) reads the first-class field first, the
legacy `metadata.containerMode` key second, and the per-kind default (`random` for a `bag`, `stack`
otherwise) last. Set it alongside [`kind`](https://diceytable.com/docs/mods/reference/object-state) — a sidecar that does not
declare a kind spawns a [`custom`](https://diceytable.com/docs/mods/reference/object-kinds#custom) Entity, which has no draw path,
so a draw order on its own governs nothing.

### `capacityLimit`

Applies to: `deck` and `bag`. It is the ceiling on how many items a container is allowed to hold, and the runtime
enforces it in exactly one place: combining two stacks is abandoned when the result would exceed the target
container's capacity, leaving both piles untouched rather than trimming the overflow.

That check reads this field. `containerCapacityFor` (`apps/web/src/playcanvas/TabletopRuntime.ts`) resolves
it through `resolveContainerConfig` — first-class field, then the legacy `metadata.containerCapacity` key,
then unlimited — so the number you write in the sidecar is the number the merge is refused against. It only
bites on a container: a sidecar that does not declare [`kind`](https://diceytable.com/docs/mods/reference/object-state) spawns a
[`custom`](https://diceytable.com/docs/mods/reference/object-kinds#custom) Entity, which never reaches the merge path at all.

### `container`

Applies to: `bag`. The container **configuration** every piece spawned from this model starts with —
which kind of container it is, and whether it never runs out. Optional: absent means a closed bag, the
`bag` kind's own default.

`applyModelAssetMetaToDefinition()` copies it into the spawn definition's replicated
[`container`](https://diceytable.com/docs/mods/reference/object-state) field, so every peer agrees on it and it survives a save.
Only the configuration is an asset default — what is *in* the container is table state and never comes
from the sidecar. Set it alongside [`kind`](https://diceytable.com/docs/mods/reference/object-kinds#bag) `"bag"`; on any other
kind it is ignored.

The Model editor writes it from **Spawn defaults ▸ Container form** and **Infinite source**. A built-in
bowl or tray duplicated into a project carries `{ "form": "holder" }` here, which is what keeps the copy
an open holder rather than a closed bag.

### `tags`

Author tags, and lowercase only here: the sidecar's pattern carries no case-insensitive flag, so `Terrain`
fails sidecar validation at scan time even though the same text typed into the Inspector is lowercased on
the way in and accepted. Write them in the form they are stored in.

`:` is deliberately outside the character class, which is what makes the platform's reserved `dt:` namespace
unforgeable from a sidecar — a mod cannot mint `dt:internal` and hide an entity from the editor. See
[the `dt:` namespace](https://diceytable.com/docs/editor/working/tags-and-groups#the-dt-namespace-is-unauthorable-not-just-discouraged).
At spawn the list is trimmed, lowercased, de-duplicated and order-preserving, and an entry that still fails
is dropped on its own rather than failing the spawn — so a typo costs you one tag, silently.

### `metadata`

Merged per key over the definition's own metadata, with your keys winning — and the definition the model
drop builds already carries `customModelAssetId`, the key that points at the GLB. Set that key in a sidecar
and the entity loads a different model, or none.

Metadata is also where several behaviors that look like top-level fields actually live: the host reads a
container's draw order and capacity, a deck's card entries and snap-grid configuration out of it. That
gives this field the most reach of any in the sidecar and the least checking — unknown *top-level* sidecar
keys are stripped, but everything nested inside `metadata` is kept verbatim. Keep to your own keys, and
prefix them so a later platform key cannot collide with one of yours.

### `materialSlots`

The model's default per-slot material binding: source material **name** → project material id, merged per
key over whatever the spawn definition already carries, with the sidecar winning. The key is the material's
name as it appears inside the GLB — never a mesh-instance index, which shifts every time a model is
re-exported.

Written once, automatically, when a model is imported. Import lifts the GLB's materials into project
materials, writes its embedded images out as project texture files, and then **removes those images from the
GLB** so the bytes are stored once instead of twice. The model keeps its material names, and this record is
what reconnects them to the extracted materials — so the model renders as it always did, and editing one of
those materials now changes the model.

That makes it load-bearing rather than decorative for an imported model: remove the binding and the mesh
falls back to the material the GLB shipped with, which no longer has any textures on it. Per-slot
assignments made on an individual entity still win over this, and so does the entity's whole-object
`metadata.materialId` (a seat's per-seat piece material, for example) — the sidecar sets the default for every
spawn, not a rule the author cannot override.

It reaches a scene by **two** routes, because there are two ways a model is placed. A table entity picks it
up when its spawn definition is built. **Room decor** (`roomPack.decor`) never builds one — it is placed by
`modelPath` — so it reads the same record out of the per-asset authoring registry the sidecar publishes,
alongside `collider`, `triggers` and the shadow flags. Anything that draws a model has to consult one of the
two; a placement that consults neither renders with the GLB's bare colours.

### `castShadows`

The model's default answer to "does this cast a shadow?", applied to every entity spawned from it.
Optional: omit the key and the model casts, which is what every model without a sidecar does.

This is the right place to say it once for a model that should never cast — a flat playmat, a
backdrop, a large decorative prop — instead of repeating
[`castShadows: false`](https://diceytable.com/docs/mods/reference/object-state#castshadows) on every entity in `setup.json`. An
individual entity can still override it in either direction; absent on the entity means "use this".

Like [`collider`](https://diceytable.com/docs/mods/files/sidecars#collider) and
[`triggers`](https://diceytable.com/docs/mods/files/sidecars#triggers), this is per-**asset** authoring config. Every peer
reads it from the sidecar the mod tree already carries, and it is never replicated: it does not
appear in a snapshot, a saved game, or a spawn definition. A peer that has not finished pulling the
model yet simply renders shadows on until it resolves, which corrects itself and changes nothing
about physics or gameplay.

### `receiveShadows`

The model's default answer to "are shadows drawn onto this?", applied to every entity spawned from it.
Optional: omit the key and the model receives shadows.

The mirror of [`castShadows`](https://diceytable.com/docs/mods/files/sidecars#castshadows), with the same per-**asset**,
never-replicated treatment, and independent of it — a table surface typically wants casting off and
receiving on, while a model meant to look self-lit wants the reverse.

Per-entity [`receiveShadows`](https://diceytable.com/docs/mods/reference/object-state#receiveshadows) overrides this; absent on the
entity means "use the model's default".

### `lightmapStatic`

Declares that this model is permanently-static scenery, so its lighting may be **baked into a
lightmap** instead of being lit in real time. Optional, and **absent means `false`** — a model
without this key is never baked.

Note that the default is the opposite way round from
[`castShadows`](https://diceytable.com/docs/mods/files/sidecars#castshadows) and
[`receiveShadows`](https://diceytable.com/docs/mods/files/sidecars#receiveshadows), which are on unless you turn them
off. Baking is opt-in because a baked object that later moves takes its baked shadow with it and
leaves a shadow behind where it used to be, and neither corrects itself until the next bake. The
test is not "is this static right now?" — a card resting in a hand zone is static right now — but
"will this never move again for the whole session?". Only you can answer that, so only you can set
the flag. Backdrops, wall panels, fixed set dressing and bolted-down scenery qualify; anything a
player can pick up, flip, or drag does not.

**The model must carry `TEXCOORD_1`** (a second UV set, used as the lightmap UVs). Models are
skipped at bake time when they lack it, rather than baking black — so setting `lightmapStatic:
true` on a model with no lightmap UVs does nothing at all. Generate them with the **Generate
lightmap UVs** action in the Model editor, which unwraps the mesh and writes `TEXCOORD_1` into the
GLB.

Like [`collider`](https://diceytable.com/docs/mods/files/sidecars#collider),
[`triggers`](https://diceytable.com/docs/mods/files/sidecars#triggers) and the two shadow keys, this is per-**asset**
authoring config and is never replicated — but for a stronger reason than the others: every player
bakes their own lightmaps locally from their own copy of the scene, so there is nothing for peers
to agree on. It does not appear in a snapshot, a saved game, or a spawn definition.

There is deliberately **no per-entity override**. Because the flag lives on the asset, placing the
same model twice flags both placements; if one copy needs to stay dynamic, use a separate model
file for it.

### `originAuthored`

Declares that this model's origin was **placed on purpose**, so the runtime must keep it instead of recentring
the model at spawn. Optional, and **absent means `false`** — a model without this key gets the recentring every
imported model has always had.

By default an imported model is rested for you: it is recentred on its X/Z bounding-box centre with the bottom of
its geometry on the surface. That rule is what makes an arbitrary GLB drop onto the table looking placed rather
than floating or half-buried, and it is also what made a hand-placed origin meaningless, because the runtime
threw it away. Setting this flag skips the recentring: only the bounds are measured, and the model keeps the
origin it was modelled around.

**Set it from the Model editor rather than by hand.** The editor's origin actions write it alongside the
rewritten geometry, and Split writes it on every part it produces, so the pieces of a split model keep the one
shared origin that makes them line up again.

⚠ **The polarity is opt-in, like [`lightmapStatic`](https://diceytable.com/docs/mods/files/sidecars#lightmapstatic) and for the same
kind of reason.** Every model published so far was authored under the recentring rule, so a default of `true`
would let any model whose geometry happens to sit away from its origin — which is most imported scenery — start
spawning in the air or sunk into the table.

Like the other authoring keys in this sidecar, it is **never replicated**: every peer holds the same GLB bytes
and the same sidecar and resolves it locally. A peer that has not pulled the sidecar yet renders the model
recentred — visually off by the authored offset until the asset resolves, and self-correcting once it does.

### `bodyType`

This field and the six after it are flat in the sidecar but land on the spawned entity's `physics` override,
merged over whatever the definition already carries — that override is what the runtime applies to the
`rigidbody` and `collision` components.

Decide the body type first, because it governs whether the rest is read: `mass` is applied only to a
`dynamic` body, and a `mesh` collision shape is refused on one. An imported model always spawns on a static
placeholder body and is promoted to dynamic only once its GLB has attached and the real collider has been
fitted; a `static` or `kinematic` value is never promoted, which makes it the honest way to say "this never
simulates" instead of relying on a large mass. See
[RIGIDBODY § Body fields](https://diceytable.com/docs/editor/inspector/rigidbody#body-fields) for the same choice in the Inspector.

### `mass`

Kilograms, and read only when the effective body type is `dynamic` — Ammo gives a static body infinite
mass, so a `mass` sitting beside `bodyType: "static"` is discarded without complaint. Absent, a `custom`
entity spawns at 0.8 kg.

Mass is not derived from `scale`: doubling a model's size leaves its weight exactly where it was, so a
large model left at the default shoves smaller pieces around like a balloon. Set it in proportion to the
rest of your table rather than to reality — the runtime weighs a card at 0.05 kg and a die at 0.35 kg, and
those are the numbers your piece collides with.

### `friction`

Coulomb friction against whatever the model is touching. It decides whether a flicked piece grips and stops
or keeps going: at `0` a model skates to the edge of the table on the lightest nudge, and a player who
meant to place it precisely ends up chasing it.

The runtime's default for a `custom` entity is 0.82 — deliberately high, because most table pieces are
meant to stay where they are put. Lower it for something whose whole point is to slide, such as a
shuffleboard puck; raise it toward 1 for a piece that must not drift when the piece beside it is knocked.

### `restitution`

Bounciness. This is the physics field that goes wrong quietly: a value that reads as reasonable on its own,
say 0.5, makes a token dropped an inch above the board hop off it and land somewhere the player never
aimed — which they report as "the piece moved by itself", not as a physics setting.

The runtime's default for a `custom` entity is 0.1, near dead, while a die runs at 0.52 because tumbling is
the entire point of a die. Raise it only when the bounce is part of the game, and test it by dropping the
piece from the height a player actually drops it from rather than from the Inspector.

### `linearDamping`

Bleeds straight-line speed out of the body on every simulation step, whether or not it is touching
anything. That is what separates it from `friction`: friction slows a piece that is sliding on a surface,
damping also slows one that is in the air.

The runtime's default for a `custom` entity is 0.05. Raise it when a nudged model coasts further than a
tightly packed board can tolerate. Close to 1 the model stops almost the instant it is released, which
players read as treacle rather than as weight, so move in small steps and watch a throw before committing.

### `angularDamping`

The rotational twin of `linearDamping`: it bleeds spin rather than travel. It is the fix for a model that
keeps slowly pirouetting for a second after a player has set it down — nothing is broken, but it looks like
something is.

The runtime's default for a `custom` entity is 0.08, and a die runs at 0.015: a die whose spin died on
contact would never tumble, so the low value there is the feature, not an oversight. Raise it for tall,
top-heavy models that should settle rather than wobble, and leave it low for anything meant to roll.

### `collisionShape`

`auto` means "keep the collider the runtime already fitted", which for an imported model is a box matched
to the model's measured bounds. Override it only when that box is visibly wrong — an arch a piece should
drop through, a bowl, an L-shaped tile — because every other value costs more to simulate and forces a
rebuild of the Ammo body when it changes.

**The Model tab no longer offers this field.** The authored
[`collider`](https://diceytable.com/docs/mods/files/sidecars#collider) list supersedes it — it says everything this key
says and adds a per-entry transform, several shapes at once, and a mesh source. The key stays
valid, stays parsed, and is projected into the collider list for display, so an existing sidecar
keeps working with no migration and no rewrite; there is simply no longer a control that writes
it. Prefer `collider` in anything new.

`convexHull` and `mesh` are built from the GLB's meshes, so they cannot be applied until the model has
attached; the runtime re-applies the override at that moment and skips the request entirely while no mesh
with usable geometry is there. `mesh` on a dynamic body silently becomes `convexHull`, because Ammo's
triangle-mesh shape is valid only for a static body — a genuinely concave collider needs
[`bodyType`](https://diceytable.com/docs/mods/files/sidecars#bodytype) set to `static`. See
[COLLISION § Shape](https://diceytable.com/docs/editor/inspector/collision#shape).

### `collider`

The model's authored **collider** — the shape the physics engine actually collides with, which is not the
model's visible geometry and never has been. Optional: omit the key and every spawned instance keeps the
collider the runtime already fits, which for an imported model is a box matched to its measured bounds.

It is a **list**, not a single shape, and it is a discriminated union on `mode`:

| `mode` | Shape |
|---|---|
| `"auto"` | `{ "mode": "auto" }` — the empty state. Keep whatever the per-kind default configures. Equivalent to [`collisionShape: "auto"`](https://diceytable.com/docs/mods/files/sidecars#collisionshape), and a real value rather than an absence so the editor can show it as a row and draw it honestly. |
| `"custom"` | `{ "mode": "custom", "entries": [ … ] }` — 1 to 8 entries, assembled into one compound collider. |

Each entry carries an `id` (1–64 chars, yours, unique within the list), an optional `name` (1–64 chars, for the
editor's list), and **its own transform**:

| Key | Type | Meaning |
|---|---|---|
| `offset` | `{ x, y, z }` | Centre offset from the entity's origin, in object-local **feet**. Omit it and the entry is centred on the model's measured centre. |
| `rotation` | `{ x, y, z }` | Euler XYZ in **degrees**. |
| `scale` | `{ x, y, z }` | A multiplier applied on top of the resolved dimensions, not a replacement for them. |

Then one shape, with its own fields:

| `shape` | Fields |
|---|---|
| `"box"` | `size` — the **full** dimensions in object-local feet, all three positive. |
| `"sphere"` | `radius` |
| `"capsule"` | `radius`, `height` (the cylindrical section **only**, excluding the two caps), `axis` (`0`/`1`/`2`, default `1` = Y) |
| `"cylinder"` | `radius`, `height` (the whole height), `axis` (default `1`) |
| `"convexHull"` | `source` (`"render"` \| `"baked"`, default `"render"`), `bakedPath`, `simplifyRatio` (0–1], `maxError` (0–1) |
| `"mesh"` | the same four fields as `convexHull` |

**Every length is in feet, measured at the entity's identity scale** — the same convention as
[`collisionSize`](https://diceytable.com/docs/mods/files/sidecars#collisionshape) — and the entity's own `scale` is applied on top at
spawn. The world unit in DiceyTable is a foot; a playing card is about 0.29 ft wide.

`source: "baked"` reads a collider mesh from a **sibling GLB next to the model**: strip the model file's last
extension and append `.collider.glb`, so `assets/models/keep.glb` pairs with `assets/models/keep.collider.glb`.
Set `bakedPath` when the file lives somewhere else. Bake when the render mesh is too heavy to collide against —
a collider mesh is budgeted at **2,000 triangles**, far below the render budget, because the hull builder feeds
every vertex of the source into the shape with no reduction at all and each one costs time per contact.

`convexHull` and `mesh` cannot be built until the model's geometry has attached, and a **`mesh` collider on a
dynamic body falls back to a convex hull** — a triangle-mesh shape is valid only for a static body. See
[COLLISION § Shape](https://diceytable.com/docs/editor/inspector/collision#shape) for that and the two other conditions the runtime
refuses a mesh-derived collider under.

An eight-entry list is a compound of eight shapes, which is how a concave model gets an honest collider without
a triangle mesh: three boxes around an arch cost far less than the arch's geometry and let a piece pass under it.

Both this key and [`triggers`](https://diceytable.com/docs/mods/files/sidecars#triggers) are read by every peer from the model's own
sidecar. Neither one is replicated per instance and neither appears in a snapshot.

### `triggers`

Up to eight **trigger volumes** authored on the model — invisible shapes that report when something crosses into
or out of them. Optional; omit the key and the model has none.

**A trigger volume never collides and never affects physics.** It has no mass, it stops nothing, and it changes
no simulation result. Firing two events is the entire whole of what it does:

- [`globalEvents.onTriggerEnter`](https://diceytable.com/docs/scripting-api/events#globaleventsontriggerenter) /
  [`onTriggerLeave`](https://diceytable.com/docs/scripting-api/events#globaleventsontriggerleave) for a table script
- [`onTriggerEnter`](https://diceytable.com/docs/scripting-api/hooks-and-capabilities#modhookeventmapontriggerenter) /
  [`onTriggerLeave`](https://diceytable.com/docs/scripting-api/hooks-and-capabilities#modhookeventmapontriggerleave) for a mod, which
  needs the `read-world` capability as well as `subscribe-events`

**And they only do anything if a script or a mod subscribes.** Authoring a volume on a model nobody wrote a rule
for changes nothing at all. A volume never names code to run — the relationship only runs from the volume's
geometry to a handler somebody registered.

Both events are raised by the **host and nowhere else**: the host samples membership on a fixed low-rate pass and
reports the differences. A handler on a player's or spectator's client never runs.

Every volume is `{ id, name, shape, position, rotation, size, tag? }`. Positions and sizes are in object-local
**feet** at the entity's identity scale, rotations are Euler XYZ in **degrees**, and `size` is **full**
dimensions rather than half-extents for every shape. Containment is tested at the crossing entity's **origin
point**, exactly as seat-zone membership is, so a large piece is inside when its origin is — not when its
geometry overlaps.

Volumes are never persisted and never replicated. Each peer rebuilds them from this sidecar when it loads the
model, and only the host's copies are sampled.

```json
{
  "triggers": [
    {
      "id": "goal-slot",
      "name": "Goal Slot",
      "shape": "box",
      "position": { "x": 0, "y": 0.15, "z": -0.4 },
      "rotation": { "x": 0, "y": 0, "z": 0 },
      "size": { "x": 0.35, "y": 0.3, "z": 0.2 },
      "tag": "goal"
    }
  ]
}
```

### `containerInterior`

The model's **interior volume** — where the cavity of a bowl, tray or bag actually is, in object-local feet.

Authoring configuration on the asset, exactly like [`collider`](https://diceytable.com/docs/mods/files/sidecars) and
[`triggers`](https://diceytable.com/docs/mods/files/sidecars): every peer resolves it from the same sidecar bytes, it never appears
in a snapshot, and it is **never replicated** per instance. Optional — omit it and one is derived (below).

Four things read it, which is why it is one shape rather than four settings:

1. **The fill.** The "looks full" heap an infinite container shows is packed inside this volume, with its top
   surface at [`fillLevel`](https://diceytable.com/docs/mods/files/sidecars).
2. **The drop footprint.** Whether a released piece counts as "in" the container is tested against this
   volume's footprint.
3. **The generated collider.** The editor's container-shell generator builds a closed shell whose *inner*
   surface is exactly this volume, thickening the walls outward and downward so a thin bowl still stops a fast
   piece. Nobody can see the outside of a locked container's collider, so the thickness goes there.
4. **The editor's holder `Fill`.** Filling an open holder in the Inspector spawns real pieces, packed into
   this volume up to `fillLevel` — so a short fill ("Placed 40 of 180") is a statement about this volume.

It is deliberately **not** an entry in `triggers[]`, although it borrows that shape's geometry conventions. A
trigger is realised as a real physics trigger entity with script hooks and an author-visible tag, none of
which an interior wants, and the consumers above are not trigger events.

**If you omit it, one is derived from the collider's bounds** — footprint inset 12 %, floor at 15 % of the
height, top at the bounds' top (a container is open, so its rim is its highest point), `fillLevel` 0.85, and
`cylinder` rather than `box` when the footprint is near-square *and* the collider is made of round primitives.
The derived volume is always strictly inside the collider, so a fill drawn in it cannot poke through the
model — but it is visibly approximate, and the editor labels it as derived. Author one when the fit matters.

```json
{
  "containerInterior": {
    "shape": "cylinder",
    "position": { "x": 0, "y": 0.18, "z": 0 },
    "rotation": { "x": 0, "y": 0, "z": 0 },
    "size": { "x": 0.7, "y": 0.3, "z": 0.7 },
    "fillLevel": 0.85
  }
}
```

### `modelAssetMetaSchema.rotation`

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `x` | `number` | **yes** | — | — | — | — | — |
| `y` | `number` | **yes** | — | — | — | — | — |
| `z` | `number` | **yes** | — | — | — | — | — |

#### `rotation.x`

Pitch, in degrees, about the horizontal axis running left to right across the table. It tips the model
forward or backward around the point it stands on, so any non-zero value lifts one edge clear of the
surface and pushes the opposite edge through it.

`180` here is the runtime's own convention for a card turned over, which makes it a useful check on your
export: if you need it to get an imported model sitting the right way up, the model came out of your
modeling tool upside down and the cheaper fix is there.

#### `rotation.y`

Yaw, in degrees, about the vertical axis. It is the only one of the three you can set without changing how
the model meets the table — the model spins in place and still rests flat — which makes it the safe one and
the one worth setting deliberately.

Use it for a directional piece: a miniature that should face down the table, an arrow, a one-way tile.
Players rotate pieces constantly during play, so treat this as the orientation the model arrives in rather
than one it is going to keep.

#### `rotation.z`

Roll, in degrees, about the remaining horizontal axis: it leans the model sideways instead of tipping it
forward. As with pitch, any non-zero value takes part of the base off the table surface.

A `dynamic` body does not hold that lean — gravity settles it back onto whatever face its collider actually
rests on, and a player sees a piece that fell over during load. If the lean is the look you want, pair it
with `locked` or a `static` `bodyType`; otherwise keep this at zero and do your orienting with
`rotation.y`.

### `modelAssetMetaSchema.container`

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `form` | `"holder"` \| `"bag"` | **yes** | — | — | — | — | — |
| `infinite` | `boolean` | no | — | — | — | — | — |

#### `container.form`

`"bag"` — a closed container. Pieces dropped in become its contents (hidden, run-length stored) and a
draw takes one out in [`containerMode`](https://diceytable.com/docs/mods/files/sidecars#containermode) order.

`"holder"` — an open bowl or tray. Pieces stay loose physics bodies resting in its cavity (see
[`containerInterior`](https://diceytable.com/docs/mods/files/sidecars#containerinterior)); there is no hidden pile to draw from,
so draw, peek and search are not offered. A holder is furniture, so pair it with `locked: true`.

#### `container.infinite`

`true` for a never-depleting source: a draw spawns a fresh copy of one authored source piece instead of
removing an item, and a capacity limit has no meaning. Absent or `false` is an ordinary, finite
container. Only meaningful together with `form`.

### `modelAssetMetaSchema.triggers`

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `id` | `string` | **yes** | — | 1–64 chars | — | — | — |
| `name` | `string` | **yes** | — | 1–64 chars | — | — | — |
| `shape` | `"box"` \| `"sphere"` \| `"capsule"` \| `"cylinder"` | **yes** | — | — | — | — | — |
| `position` | `object` | **yes** | — | — | — | — | — |
| `rotation` | `object` <br>same shape as `triggers.position` | **yes** | — | — | — | — | — |
| `size` | `object` | **yes** | — | — | — | — | — |
| `tag` | `string` | no | — | <= 32 chars | — | Expected 1-32 characters matching /^[a-z0-9_-]+$/i and not the reserved "dt:" prefix. | — |

#### `triggers.id`

The volume's identity, 1–64 characters, chosen by you and required. It is what a handler receives as
[`triggerId`](https://diceytable.com/docs/scripting-api/events#triggereventtriggerid), so keep it stable: renaming it breaks any rule
that matched on it, silently, with no error anywhere.

**It is unique only within this model asset.** Two spawned copies of the model both report the same `triggerId`
for the same volume — which is fine, because the payload also carries `ownerObjectId`, the entity the volume is
on. A handler tells two copies apart by keying on the **pair**. Your job is only to keep the id unique among
*this* model's volumes.

Use a slug you would be happy for a script author to type as a literal — `goal-slot`, `card-well`, `space-14` —
rather than `trigger-3`.

#### `triggers.name`

The human-readable label, 1–64 characters, required. It reaches a handler as
[`triggerName`](https://diceytable.com/docs/scripting-api/events#triggereventtriggername) and is the one field on the event payload
written for a person: it is what a log line or a UI label prints.

It is **not** an identifier. Nothing stops two volumes sharing a name, and editing it is expected — which is
exactly why a script should match on [`tag`](https://diceytable.com/docs/mods/files/sidecars#triggers) or
[`id`](https://diceytable.com/docs/mods/files/sidecars#triggers) and print this.

#### `triggers.shape`

Which primitive the volume is: `box`, `sphere`, `capsule` or `cylinder`. Required.

**Primitives only, deliberately.** A trigger volume answers a containment question about a single point, so a
convex hull or a triangle mesh would cost real geometry to answer a question a box answers exactly — and unlike a
collider there is no accuracy to gain, because nothing ever collides with a volume.

The shape decides how [`size`](https://diceytable.com/docs/mods/files/sidecars#triggers) is read: a `box` uses all three dimensions,
a `sphere` takes its radius from the largest half-dimension, and a `capsule` or `cylinder` takes its radius from
the two horizontal dimensions and its height from `size.y`. Capsules and cylinders are always **Y-axis** volumes;
rotate them with [`rotation`](https://diceytable.com/docs/mods/files/sidecars#triggers) if you need another orientation.

Reach for `box` unless the shape is genuinely round. It is the cheapest test and the easiest to reason about
against a rectangular model.

#### `triggers.position`

The volume's **centre**, in object-local **feet** at the entity's identity scale, measured from the entity's
origin. Required — a volume always states where it is.

The origin of an imported model is the point it stands on: the runtime rests the model with its X/Z centre on the
origin and its lowest point at `y = 0`. So `{ "x": 0, "y": 0, "z": 0 }` puts the volume's centre at the surface
the model sits on, and half of a box volume there hangs below the table. Lift it by half the volume's height to
have it sit on the model's footprint.

The entity's own `scale` is applied on top at spawn, so a volume authored at unit scale follows a scaled-up
instance without editing.

Remember the unit. A playing card is about 0.29 ft wide, so a slot that holds one is a fraction of a foot across,
not `1`.

#### `triggers.rotation`

The volume's orientation as Euler XYZ angles in **degrees**. Required, and `{ "x": 0, "y": 0, "z": 0 }` is the
ordinary answer.

It rotates the volume about its own [`position`](https://diceytable.com/docs/mods/files/sidecars#triggers), not about the
entity's origin, so a yaw spins the volume in place. Use it to line a volume up with a slot the model author drew
at an angle, and to orient a `capsule` or `cylinder`, both of which are built as Y-axis volumes before this
rotation is applied.

Rotating a `sphere` does nothing measurable, which is worth knowing only so that a stray value on one is not read
as a bug elsewhere.

#### `triggers.size`

The volume's **full** dimensions in object-local **feet** — not half-extents — all three strictly positive.
Required.

How each shape reads it:

| [`shape`](https://diceytable.com/docs/mods/files/sidecars#triggers) | How `size` is used |
|---|---|
| `box` | All three, directly: the box is `size` across. |
| `sphere` | Radius = the **largest** of the three half-dimensions. The other two are ignored. |
| `cylinder` | Radius = the larger of the `x` and `z` half-dimensions; height = `size.y`; axis = Y. |
| `capsule` | Radius as for a cylinder; height = `size.y` **minus the two caps** (`size.y − 2 × radius`, floored at 0), matching the engine's capsule convention. A capsule whose `size.y` is no more than its diameter is therefore a sphere. |

The entity's `scale` multiplies these at spawn, so author at unit scale and let instances scale.

Make a volume comfortably larger than the thing meant to cross it. Containment is tested at the crossing entity's
**origin point**, so a volume the exact size of a card's footprint reports a crossing only when the card's origin
is inside it — which is a much smaller target than the card looks.

#### `triggers.tag`

The identifier a script or mod should match on, and the reason the tag exists. Optional: a volume without one can
still be recognised by [`id`](https://diceytable.com/docs/mods/files/sidecars#triggers), but a tag is the field that says *"this
volume is here for a rule"*.

It follows the platform's shared author-tag rules — 1–32 characters matching `^[a-z0-9_-]+$` — and the reserved
`dt:` namespace is **rejected**, validated with the same `isUserTag` check every other author tag goes through.
`:` is outside the character class, which is what makes the platform namespace unforgeable from a sidecar. See
[the `dt:` namespace](https://diceytable.com/docs/editor/working/tags-and-groups#the-dt-namespace-is-unauthorable-not-just-discouraged).

A trigger tag is **not** an entity tag. It lives on the volume, never on the entity, so it never appears in
[`tags`](https://diceytable.com/docs/mods/files/sidecars#tags), in `TableObjectState.tags`, or in any tag filter.

Reuse a tag deliberately: several volumes sharing one tag is how a model says *"any of these counts as a goal"*,
and a handler matching that tag then fires for all of them without knowing how many there are.

### `modelAssetMetaSchema.containerInterior`

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `shape` | `"box"` \| `"cylinder"` \| `"sphere"` | **yes** | — | — | — | — | — |
| `position` | `object` <br>same shape as `triggers.position` | **yes** | — | — | — | — | — |
| `rotation` | `object` <br>same shape as `triggers.position` | **yes** | — | — | — | — | — |
| `size` | `object` <br>same shape as `triggers.size` | **yes** | — | — | — | — | — |
| `fillLevel` | `number` | no | `0.85` | >= 0, <= 1 | — | — | — |

#### `containerInterior.shape`

The cavity's shape: `box`, `cylinder` or `sphere`. Required.

- **`box`** — a tray, a crate, a square well. The volume is `size` exactly.
- **`cylinder`** — a round bowl with straight sides. The radius comes from the larger of the two off-axis
  dimensions and the height from `size.y`.
- **`sphere`** — a **bowl**, not a ball. The cavity is a sphere cut open at the top of the declared box, so a
  squat `size` like `{ "x": 1, "y": 0.6, "z": 1 }` gives a wide-mouthed bowl with a rounded bottom. Its
  radius comes from the largest half-dimension.

The sphere case has one clamp worth knowing: the rim is never cut higher than 0.8 of the radius above the
centre. Without it, a cube-ish `size` would cut the sphere at its own north pole and produce a closed ball
with a pinhole — a cavity nothing can get into. A squat, bowl-shaped `size` is unaffected.

Use `sphere` when pieces should settle toward the middle, `cylinder` or `box` when they should spread evenly
across a flat floor. The shape is also what the generated collider shell is built from, so it decides how the
inside of the container *feels*, not just how the fill looks.

#### `containerInterior.position`

The centre of the cavity, in object-local **feet** — the same convention as a trigger volume's `position` and
a collider entry's `offset`, resolved by the same code.

It is the centre of the volume, not its floor and not its rim: a cavity 0.3 ft deep whose floor should sit
0.03 ft above the model's origin has `y: 0.18`. The world unit here is a foot, and a playing card is about
0.29 ft wide, so most bowl interiors are fractions of one.

Measured at the model's **identity scale**. An entity's own `scale` is applied on top at spawn, so a bowl
placed at 2× has an interior twice the size without any change here.

#### `containerInterior.rotation`

The cavity's orientation, Euler XYZ in **degrees** — again the trigger volume's convention.

Usually all zeros. A container's cavity opens upward, and tilting one tilts the surface the fill sits on and
the footprint a dropped piece is tested against, so reach for it only when the model itself is authored at an
angle — a tipped bowl, a sloped hopper — rather than to nudge the fit of an upright one. Move
[`position`](https://diceytable.com/docs/mods/files/sidecars) or change [`size`](https://diceytable.com/docs/mods/files/sidecars) for that.

#### `containerInterior.size`

The cavity's dimensions in object-local **feet**, all three strictly positive.

**These are FULL dimensions, not half-extents** — the same convention as a trigger volume's `size` and a box
collider's `size`. A well 0.7 ft across and 0.3 ft deep is `{ "x": 0.7, "y": 0.3, "z": 0.7 }`, not `0.35`. Getting
this wrong by a factor of two is the single most common authoring mistake here, and it shows up as a fill that
either floats out of the bowl or hides at the bottom of it.

How the non-box shapes read it: a `cylinder` takes its radius from the larger of `x` and `z` and its height
from `y`; a `sphere` takes its radius from the largest half-dimension and is then cut open at `+y/2` to make a
bowl.

Size the cavity to the *visible* inside of the model. The generated collider shell then puts its inner
surface exactly here and grows the wall thickness outward and downward, so pieces come to rest where they look
like they should.

#### `containerInterior.fillLevel`

Where the "looks full" fill's top surface sits, as a fraction of the interior height measured up from its
floor. `0`–`1`, defaulting to `0.85`.

It exists so the four geometric keys can be authored without a fifth decision, and so a full bowl reads as
*nearly* full rather than brim-level — a heap that reaches the rim looks like it is about to spill, and any
piece resting on top of it looks wrong.

Only an infinite container draws a fill, so on a finite bowl or tray this value changes nothing you can see.
It is still worth setting on the asset: the same model is usually used for both, and the value travels with
the model rather than with the placement.

`0` puts the surface on the floor (an effectively invisible fill) and `1` puts it at the rim. Between about
0.75 and 0.9 is the range that looks like a full container.

### `modelAssetMetaSchema.triggers.position`

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `x` | `number` | **yes** | — | — | — | — | — |
| `y` | `number` | **yes** | — | — | — | — | — |
| `z` | `number` | **yes** | — | — | — | — | — |

#### `triggers.position.x`

The volume centre's offset along the horizontal axis running left to right across the table, in object-local
**feet** from the entity's origin. Positive is one way, negative the other; which way is whichever way the model
was exported, so check it in the Model editor rather than reasoning about it.

Zero is the model's own X centre, because the runtime rests an imported model with its X/Z centre on the origin.
Leave it at `0` for anything centred, and use it to place one volume per column when a board carries several.

#### `triggers.position.y`

The volume centre's **height**, in object-local **feet** above the plane the model stands on — an imported model
is rested with its lowest point at `y = 0`, so `0` here is the table surface under it, not the model's middle.

This is the value most often wrong on a first attempt. A box volume centred at `0` has half its height below the
surface, so a rule that should catch a piece resting *on* the model fires from underneath it too. Set it to at
least half the volume's [`size.y`](https://diceytable.com/docs/mods/files/sidecars#triggers) to sit the volume on the footprint,
and higher again to catch something dropped into a well.

Volumes have a ceiling, unlike seat zones: a piece lifted above a volume's top face is outside it. If you want
"anywhere above this spot", make the volume tall on purpose.

#### `triggers.position.z`

The volume centre's offset along the horizontal axis running toward and away from the table's front edge, in
object-local **feet** from the entity's origin.

Zero is the model's own Z centre. Pair it with
[`position.x`](https://diceytable.com/docs/mods/files/sidecars#triggers) to place a volume anywhere on the model's footprint —
one per space on a track, one per slot on a board — and remember both are measured before the entity's `scale` is
applied, so a volume authored at unit scale follows a scaled instance.

### `modelAssetMetaSchema.triggers.size`

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `x` | `number` | **yes** | — | > 0 | — | — | — |
| `y` | `number` | **yes** | — | > 0 | — | — | — |
| `z` | `number` | **yes** | — | > 0 | — | — | — |

#### `triggers.size.x`

The volume's **full** width in object-local **feet**, strictly positive — the whole span, not a half-extent.

For a `box` it is used directly. For a `cylinder` or `capsule` it is one of the two dimensions the radius comes
from (the larger half of `x` and `z` wins). For a `sphere` it competes with `y` and `z` for the largest
half-dimension and is otherwise ignored.

Size it for the crossing entity's **origin point**, not its silhouette: containment is a point test, so a volume
exactly as wide as a card gives you a target the width of the card only if the card is perfectly centred. Err
wide.

#### `triggers.size.y`

The volume's **full** height in object-local **feet**, strictly positive.

It is read differently per shape, and the capsule case surprises people:

- `box` — the height, directly.
- `cylinder` — the height, directly. The axis is Y.
- `capsule` — the **overall** height, from which the two hemispherical caps are subtracted to get the cylindrical
  section (`size.y − 2 × radius`, floored at zero). A capsule no taller than it is wide is therefore just a
  sphere.
- `sphere` — competes with `x` and `z` for the largest half-dimension.

A volume has a top face, so this is what decides whether a piece hovering above the model is inside or outside.
Seat zones deliberately have no ceiling; trigger volumes do. Make it tall when the rule is "somewhere over here"
and shallow when the rule is "resting in this slot".

#### `triggers.size.z`

The volume's **full** depth in object-local **feet**, strictly positive.

For a `box` it is used directly; for a `cylinder` or `capsule` it is the other dimension the radius is taken from
(the larger half of `x` and `z`); for a `sphere` it competes for the largest half-dimension.

As with [`size.x`](https://diceytable.com/docs/mods/files/sidecars#triggers), size it generously: the crossing test is against the
entity's origin point, so a volume matched exactly to a piece's footprint is a much smaller target than it looks.
