Dicey Table

The Manifest

Manifest reference

Every field of diceytable.mod.json — what it does, who reads it, its constraints and exact validation message, and a worked example, verified against source.

On this page9 sections

Every mod has exactly one manifest, a JSON file validated by modManifestSchema (packages/shared/src/modManifest.ts). This page documents every field: what it does, who reads it, its constraints, the exact validation message you'll see when it's wrong, and a worked example.

Verified field count (2026-10-09): 35 top-level fields. The generated field tables below (schemaSymbols.json) are the authoritative list and are what the field-by-field breakdown is built from — count from there rather than from this page's prose, which has twice fallen behind (an earlier hand count of 20 top-level / 32 leaf fields predates assetRepos, plugins, dependencies and setupOptions, the "25" it replaced predates lobbyRequirements, the "26" after that predates rules, dice, diceEnabled, credits and excludedAssets, the "31" after that predates variants, the "32" after that predates aiModels and bots, and the "34" after that predates diceClearAfterSeconds).

The filename — and a footgun#

The canonical manifest filename is diceytable.mod.json, at the repo root. gametable.mod.json is accepted as a legacy fallback from the pre-rebrand "GameTable" naming.

The fallback logic (apps/server/src/githubScanner.ts, fetchManifestText) tries diceytable.mod.json first and only reads gametable.mod.json if that fetch throws for any reason — a real 404 because the file doesn't exist, but also a GitHub 500, a network blip, or any other transient failure:

TypeScript
async function fetchManifestText(owner, repo, ref) {
  try {
    return await fetchText(rawUrl(owner, repo, ref, "diceytable.mod.json"));
  } catch {
    return await fetchText(rawUrl(owner, repo, ref, "gametable.mod.json"));
  }
}

This is a footgun worth naming explicitly: if diceytable.mod.json exists but GitHub has a transient outage while the scanner is reading it, the scan silently falls through to gametable.mod.json — which may be stale, absent, or (if you keep both in sync, as recommended below) byte-identical and harmless. If you only maintain diceytable.mod.json, a transient failure produces a hard scan error instead of a silent stale-content bug, which is easier to diagnose. Our own reference mod (mods/example) ships both files, kept byte-identical, verified 2026-07-27 with a byte-for-byte diff — that's the safest pattern if you want insurance against the fallback ever firing for the wrong reason.

Required vs. optional, at a glance#

Field Required? Default
schemaVersion required —
id required —
name required —
version required —
type required —
entry required (object; both members optional) —
compatibility required —
license required —
slug optional —
assets defaulted []
assetManifest optional —
excludedAssets optional —
capabilities defaulted { version: "1", allowed: ["log"] }
tags defaulted []
summary optional —
description optional —
category optional —
players optional —
coverImage optional —
screenshots optional —
rules optional —
dice optional —
diceEnabled optional —
diceClearAfterSeconds optional —
soundSets optional —
assetRepos optional —
pluginSettings optional —
plugins optional —
dependencies optional —
setupOptions optional —
lobbyRequirements optional —
variants optional —
aiModels optional —
bots optional —
credits optional —

Field-by-field#

schemaVersion#

  • Type / constraint: literal "1.0" — the only accepted value.
  • Who reads it: the manifest parser (modManifestSchema) itself, before anything else.
  • Validation: fails schema validation (generic Zod literal mismatch) if not exactly "1.0".
  • Example: "schemaVersion": "1.0"

id#

  • Type / constraint: string, 3–96 chars, pattern ^[a-z0-9][a-z0-9._-]*[a-z0-9]$ (case-insensitive) — starts and ends alphanumeric, interior may contain dots, underscores, dashes.
  • Who reads it: the registry (primary key for a registered mod), the scanner, discovery, and every packRefs pin, collection entry and room selectedModIds that names this pack.
  • Where it is edited: Mod ▸ Mod Details… ▸ Details ▸ Mod ID. Editable until the pack is published, then locked — an id is what other people's documents pin, so changing a published one mints a second mod rather than renaming the first.
  • Validation: generic Zod regex/length failure; no custom message is set on this field. Edit Mode states the rule in place and refuses the publish before the push, so a bad id is never discovered as a scanner refusal on the far side of a GitHub commit.
  • Example: "id": "local.example.starter-pack"

slug#

  • Type / constraint: optional string, 1–60 chars, pattern ^[a-z0-9]+(?:-[a-z0-9]+)*$ (lowercase letters/digits, single interior dashes — stricter than id: no dots, no underscores, no leading/trailing/double dashes).
  • Who reads it: the public /games/<slug> (and /mods/<slug>) route. A mod with no slug routes on its id instead — but Edit Mode no longer leaves it absent (see below).
  • Validation message: "Use lowercase letters, numbers, and single dashes."
  • Where it comes from: Mod Details sets it from your title the first time you edit anything there, so a game called "Chess" is served at /games/chess rather than at whatever its project id happens to be. Editing the Game URL field overrides that; Reset re-derives it from the current title.
  • It does not follow a rename. Once stored, the slug stays put when you retitle the game, because a published URL is something other people have linked to and a rename must not silently move it. Press Reset if you do want it to catch up.
  • Both keys keep working. A pack resolves from its id and its slug, so adding a slug never breaks an existing link — the id form permanently redirects (301) to the slug form, which is what the page's canonical names. The same redirect corrects the prefix: a game reached at /mods/<slug> goes to /games/<slug>, and any other pack type reached at /games/<slug> goes to /mods/<slug>.
  • Consequence: once a mod has real players, changing slug changes its public URL — treat it as a stable identifier, not a display label.
  • Example: "slug": "starter-table-pack"

name#

  • Type / constraint: string, 1–80 chars.
  • Who reads it: discovery UI, the mod list, the details page title.
  • Example: "name": "Starter Table Pack"

version#

  • Type / constraint: string matching ^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$ (semver, optional pre-release/build metadata).
  • Who reads it: publish history, discovery. This is a separate string from compatibility.engine, and unrelated to it — version is the mod's own release number; compatibility.engine targets the DiceyTable engine (see Engine compatibility).
  • Validation message: "Use semver, for example 1.0.0"
  • Example: "version": "1.0.0"

type#

  • Type / constraint: enum "game-pack" | "component-pack" | "table-pack" | "room-pack".
  • Who reads it: almost everything. It decides which payload schema your entry.setup is parsed with, which editor the project opens in, which browse taxonomy your category comes from, which listing your pack appears in (/games/ is game packs only; everything else lives under /mods/) — and which manifest fields you may declare at all, per the table in the next section.
  • ⚠ It is immutable after your first publish. The server refuses a changed type with mod-type-immutable (409): the kind is part of what other packs depend on, so it is a one-way door rather than a preference.
  • Disambiguation: component-pack describes this mod's shape and has nothing to do with the server-side "package" concept (packageLifecycle.ts). Its author-facing name is asset pack — "component" means an engine component everywhere else.
  • Example: "type": "game-pack"

Which fields your pack type can use#

The manifest began life as a game manifest and was then handed to three other kinds of pack unchanged, which is how a room could declare the players who sit at it. It no longer can. packages/shared/src/modTypeFields.ts is the one table every layer reads — the schema, the publish scanner and the manifest editor — so the form cannot offer a control that writes a refusal.

Everything not listed here (id, name, version, entry.setup, assets, excludedAssets, assetRepos, compatibility, license, tags, summary, description, category, coverImage, screenshots, soundSets, slug, dependencies) means the same thing for all four kinds.

Field Game Table Room Asset pack Refused by
entry.script ✅ — — ✅ the schema, at parse
capabilities ✅ — — ✅ the schema, at parse
plugins ✅ — — ✅ the schema, at parse
pluginSettings ✅ — — ✅ the schema, at parse
setupOptions ✅ — — — the scanner, at publish
lobbyRequirements ✅ — — — the scanner, at publish
variants ✅ — — — the scanner, at publish
aiModels ✅ — — — the scanner, at publish (bots-not-allowed-for-type)
bots ✅ — — — the scanner, at publish (bots-not-allowed-for-type)
players ✅ ✅ (as Seats) — — nobody — the editor simply does not offer it

Why three different enforcers. A field is refused at parse only when it contradicts the type — a room or table pack runs no script, so plugins describes a reach it cannot have, and no manifest in the wild could legitimately be carrying one. A field that is merely inert is refused at publish instead, where you are present to be told: refusing it at parse would take a pack that is already published and merely carrying a dead key off every table that depends on it. A field that is only wrong as prose — a browse card printing a player count for a room — is refused by nobody; the editor stops offering it, and lists it with a Remove button if a hand-written manifest has one.

Being the room's game is not the same as carrying a script. setupOptions, lobbyRequirements and variants are all read from the one mod the lobby resolves as the game (the room's provider, or its single selected mod). A game pack with no entry.script may still declare lobby requirements and variants — the platform asks and applies them — and an asset pack full of scripts may not, because it is a dependency of a game rather than the game. setupOptions is the one of the three that also needs a script, because a script is the only thing that can read an answer: either the game's table scripts, through world.getSetupOptions(), or its entry.script, as the third argument to setup(api, manifest, options). A game with neither is refused at publish (setup-options-unreadable).

entry#

  • Type / constraint: object { setup?: string (1–180 chars), script?: string (1–180 chars) }. Both members are optional — entry: {} is valid.
  • Who reads it: the scanner (fetches and validates whichever is present), the play-mode artifact fetch (fetchGitHubModArtifact, same conditional fetch).
  • Why both are optional: an asset-only component-pack — a shared model library, a card-back pack — legitimately has no entry point; there's nothing to set up and nothing to script.
  • ⚠ The gap this creates: scanGitHubMod skips whichever branch is absent and falls through to status: "compatible". An empty entry publishes successfully and does nothing at the table. If your mod scans compatible but spawns no objects, check entry first — an empty or missing setup means there was never anything to place.
  • entry.script constraint: if present, must end in .js (validated separately — see unsupported-script-type below).
  • Example (full):
    JSON
    "entry": { "setup": "setup.json", "script": "scripts/main.js" }
    
  • Example (asset-only mod — valid, does nothing at the table):
    JSON
    "entry": {}
    

assets#

  • Type / constraint: array of strings (1–180 chars each), max 2000 (MOD_MAX_DECLARED_ASSETS), defaults to [].
  • Who reads it: the scanner (fetches, hashes and content-type-checks every one — see Assets); treePathsForManifest() includes every entry in the canonical repo-path set.
  • Who writes it: you do not maintain this list by hand. It is a derived inventory: the editor recomputes it from the project's file tree on every add, delete and move (and again on Save Draft), and the publish endpoint recomputes it from the pushed tree. The manifest's own file, entry.setup, entry.script, rulebook pages under rules/, and editor-only files (originals/, thumbnails/, screenshots/, a deck's per-card source images, link records, and any extension outside the allowlist) are always excluded — modAssetUndeclarableReason() in packages/shared/src/modManifest.ts is the one spelling of that rule. If you hand-edit the array, the next save overwrites it.
  • The one thing you can change: keeping a declarable file out, with excludedAssets. The manifest editor's Files tab shows every file's state and is where you set it.
  • Constraint — extension allowlist: every path's extension must be one of the 19 in MOD_ASSET_ALLOWED_EXTENSIONS (see Assets for the full list).
  • Validation message (bad path): "Mod paths must be relative repository paths without traversal or external URLs." (code unsafe-path)
  • Validation message (bad extension): `Unsupported asset type: ${extension || "none"}.` (code unsupported-asset-type)
  • Example: "assets": ["assets/board.png", "assets/models/die.glb"]

assetManifest#

  • Type / constraint: optional array of { path: string (1–180), sha256?: string (64 hex chars) }, max 2000.
  • Who reads it: the scanner and the play-mode pull-cache, as an optional per-asset catalog (repo path + content hash) that lets them verify/dedupe assets without issuing a HEAD request per file. Absent on older manifests — nothing requires it.
  • Example:
    JSON
    "assetManifest": [
      { "path": "assets/board.png", "sha256": "3f9a…64 hex chars…c1" }
    ]
    

excludedAssets#

  • Type / constraint: optional array of strings (1–180 chars each), max 2000. Absent when empty — the editor removes the key rather than writing [].
  • What it is: declarable files you have deliberately kept out of assets. Because assets is recomputed from the file tree on every save and at publish, an exclusion cannot be expressed by deleting a line from assets — the next reconcile would put it back. It is stored here instead.
  • Who reads it: reconcileManifestFilePaths() (the editor, on every save) and the publish endpoint's asset inventory. Both leave the listed paths out of assets. Nothing at the table reads it.
  • What an excluded file does: it is still published to your repository and still loads — on demand, the first time something uses it, unverified and without the registration-time size check and hash. It is not part of the download players make before the table opens.
  • Who writes it: the Pre-load checkbox beside each game file on the manifest editor's Files tab. The reconciler keeps it honest: it prunes an entry whose file is gone, follows a rename, drops an entry that could never be declared (an entry file, a thumbnail, an original), and removes the key when the list empties.
  • Pack types: all four. It is not a type-restricted field.
  • Older servers: a server built before this field strips the key and re-declares the files. The exclusion is ignored; the manifest is never refused for carrying it.
  • Example: "excludedAssets": ["assets/expansion/board-xl.png"]

compatibility#

  • Type / constraint: object { engine: string, 1–40 chars }.
  • Who reads it: the scanner, via isCompatibleEngineRange(manifest.compatibility.engine, ENGINE_VERSION) — the current engine version is "0.1.0".
  • Validation message (incompatible): `Mod targets ${manifest.compatibility.engine}; current engine is ${ENGINE_VERSION}.` (code engine-incompatible)
  • ⚠ Not semver. The grammar is a hand-rolled 2-token parser, not a real range checker — see Engine compatibility for the full, exact grammar (including a form that silently matches everything).
  • Example: "compatibility": { "engine": ">=0.1 <1.0" }

capabilities#

  • Type / constraint: object { version: literal "1" (default "1"), allowed: ModCapability[] (max 20, default ["log"]) }. The 12 capability slugs are documented on Mod capabilities.
  • Who reads it: validateManifestCapabilities() at scan time — cross-checks against capabilities the scanner detects your script using (via 12 regex detectors over entry.script's text). Declaring a capability you don't use is fine; using one you haven't declared is a scan error.
  • Validation message: `Script uses capability "${capability}" but it is not declared in manifest.capabilities.allowed.` (code undeclared-capability)
  • The elevated one: read-hidden-information gates api.getUnredactedSnapshot() alone. It is never implied by read-world — whose six reads are redacted to the least-privileged view on every peer, the host included — and never granted by default. Declaring it tells a reviewer and a player that this mod can see hidden cards.
  • Example: "capabilities": { "version": "1", "allowed": ["log", "spawn-object", "read-world"] }

license#

  • Type / constraint: string, 1–80 chars. Free text — there is no SPDX validation, no enum, no allowlist. "license": "whatever I want" passes as readily as "license": "MIT".
  • Who reads it: discovery UI, displayed as-is on the mod's details page. Nothing parses or enforces it.
  • Example: "license": "MIT"

tags#

  • Type / constraint: array of strings (1–32 chars, pattern ^[a-z0-9-]+$ case-insensitive), max 20, defaults to [].
  • Who reads it: discovery/search filtering. Distinct from category (single, curated) — tags are free-form and multi-valued.
  • Example: "tags": ["cards", "starter", "sandbox"]

summary#

  • Type / constraint: optional string, trimmed, max 200 chars. Plain text — the UI enforces no formatting.
  • Who reads it: mod cards/lists on discovery pages.
  • Example: "summary": "A quick-start pack of cards and dice for prototyping games."

description#

  • Type / constraint: optional string, max 20,000 chars. Markdown (authored via a WYSIWYG editor that emits markdown).
  • Who reads it: the mod's details page (/games/<slug>).
  • Example: "description": "# About this pack\n\nA general-purpose starter set..."

category#

  • Type / constraint: optional, must be one of the 66 curated slugs — see Categories.
  • Who reads it: discovery's browse-by-category filter.
  • Validation: generic Zod enum mismatch if the slug isn't in the curated list.
  • Example: "category": "worker-placement"

players#

  • Type / constraint: optional object { min: int 1–64, max: int 1–64 }, with a refine requiring max >= min.
  • Who reads it: discovery cards/filters (player-count range).
  • Validation message: "players.max must be greater than or equal to players.min."
  • Example: "players": { "min": 2, "max": 4 }

coverImage#

  • Type / constraint: optional string, 1–180 chars — a repo path under media/.
  • Who reads it: discovery cards, the details page hero image. Scanned as an image (see Cover art and screenshots) even though it isn't listed in assets.
  • Validation: must be a safe relative path under media/, or `coverImage and screenshots must be relative paths under the media/ folder.` (code media-path-invalid).
  • Example: "coverImage": "media/cover.webp"

screenshots#

  • Type / constraint: optional array of { path: string 1–180, crop?: CropRect }, max 12. CropRect is { x, y, w, h }, each a fraction 0–1 of the source image (w/h strictly > 0), with a refine requiring the rectangle to stay inside the image.
  • Who reads it: the details page gallery. crop lets the editor re-open and re-crop the original source image rather than re-uploading.
  • Validation message (crop out of bounds): "Crop rectangle must stay within the image bounds (x+w and y+h ≤ 1)." — note this checks both x + w ≤ 1 and y + h ≤ 1 (with a small floating-point epsilon of 0.0001), not just the x-axis.
  • Example:
    JSON
    "screenshots": [
      { "path": "media/screenshot-1.webp", "crop": { "x": 0, "y": 0.1, "w": 1, "h": 0.8 } }
    ]
    

soundSets#

  • Type / constraint: optional array of { name: string (pattern ^[a-z0-9][a-z0-9._-]*$, 1–80), variants: string[] (1–16 repo-relative asset paths), material?: SoundMaterial, action?: SoundAction, loop?: boolean }, max 64.
  • Who reads it: api.playSound({ modSound }) / api.setObjectSound(...) in mod scripts — mods declare and play their own uploaded clips this way; they can never reference the first-party licensed sound library by id (a deliberate licensing constraint, not a technical accident).
  • Example:
    JSON
    "soundSets": [
      { "name": "dice-clatter", "variants": ["assets/sfx/clatter-1.wav", "assets/sfx/clatter-2.wav"], "material": "wood", "action": "roll" }
    ]
    

A complete, minimal, real manifest#

Verified byte-for-byte against mods/example/diceytable.mod.json (2026-07-27):

JSON
{
  "schemaVersion": "1.0",
  "id": "local.example.starter-pack",
  "name": "Starter Table Pack",
  "version": "1.0.0",
  "type": "game-pack",
  "entry": {
    "setup": "setup.json",
    "script": "scripts/main.js"
  },
  "assets": ["setup.json"],
  "compatibility": {
    "engine": ">=0.1 <1.0"
  },
  "capabilities": {
    "version": "1",
    "allowed": ["log", "spawn-object", "register-action", "read-world", "object-action", "saved-data", "subscribe-events"]
  },
  "license": "MIT",
  "tags": ["cards", "starter", "sandbox"]
}

See also#

  • Game variants — offering one game in several set-ups: the variants list here and the matching block in setup.json.
  • Game bots — what aiModels and bots declare, and how a table plays them.
  • Categories — all 66 slugs, grouped.
  • Engine compatibility — the compatibility.engine grammar in full.
  • Required and conventional files — how entry/assets determine the exact repo paths a mod must publish.
  • Assets — the 18-extension allowlist and size caps.
  • ModCapability — the slugs capabilities.allowed accepts.
  • Mod scripting API — ModSetupManifest, the four manifest fields your setup function is actually handed.

modManifestSchema#

Exported from @diceytable/shared as modManifestSchema. 179 fields across 29 tables.

Field Type Required Default Min / Max Pattern Rule Description
schemaVersion "1.0" yes — — — — —
id string yes — 3–96 chars ^[a-z0-9][a-z0-9._-]*[a-z0-9]$ — —
slug string no — 1–60 chars ^[a-z0-9]+(?:-[a-z0-9]+)*$ — —
name string yes — 1–80 chars — — —
version string yes — — ^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$ — —
type "game-pack" | "component-pack" | "table-pack" | "room-pack" yes — — — — —
entry object yes — — — — —
assets string[] no [] <= 2000 items; each 1–180 chars — — —
assetManifest modAssetRefSchema[] no — <= 2000 items — — —
excludedAssets string[] no — <= 2000 items; each 1–180 chars — — —
assetRepos declaredAssetRepoSchema[] no — <= 4 items — — —
pluginSettings Record<string, Record<string, string | number | boolean>> no — — — — —
compatibility object yes — — — — —
capabilities object no {"version":"1","allowed":["log"]} — — — —
license string yes — 1–80 chars — — —
tags string[] no [] <= 20 items; each 1–32 chars ^[a-z0-9-]+$ — —
summary string no — <= 200 chars — — —
description string no — <= 20000 chars — — —
category modCategorySlugSchema no — — — — —
players object no — — — players.max must be greater than or equal to players.min. —
coverImage string no — 1–180 chars — — —
screenshots modScreenshotSchema[] no — <= 12 items — — —
rules modRulesDocumentSchema[] no — <= 8 items — 1 further cross-field rule (message built at validation time). —
dice modDiceEntrySchema[] no — <= 24 items — Each die may be declared once (give dice that share a type distinct ids). —
diceEnabled boolean no — — — — —
diceClearAfterSeconds number no — >= 0, <= 3600 — — —
soundSets modSoundSetSchema[] no — <= 64 items — — —
plugins modPluginUseSchema[] no — <= 8 items — — —
dependencies modDependencySchema[] no — <= 24 items — — —
setupOptions modSetupOptionSchema[] no — <= 12 items — — —
lobbyRequirements modLobbyRequirementSchema[] no — <= 4 items — — —
gameDecks string no — 1–180 chars — gameDecks is a relative .json path inside the pack, such as decks/game-decks.json. —
variants modVariantSchema[] no — <= 12 items — — —
aiModels modAiModelSchema[] no — <= 4 items — — —
bots modBotSchema[] no — <= 8 items — — —
credits assetCreditSchema[] no — <= 500 items — — —

Whole-object rules:

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

schemaVersion#

This is the version of the manifest format, not of your mod — version is the number you bump when you publish. There is one accepted value and no migration path, so a manifest carrying anything else fails to parse before any other field is read: the scan reports a literal mismatch and tells you nothing about the field you were actually editing.

Copy it verbatim into every new manifest and leave it alone.

id#

The address of your mod. The registry keys on it (upsertScannedMod, apps/server/src/store.ts), the public page routes on /games/<id> whenever no slug is set, and favorites, reviews and play stats all hang off it.

Changing it publishes a second mod rather than renaming the first: re-scanning the same repo writes a fresh record under the new id, and the old record keeps the favorites, the reviews and the URL people bookmarked. Pick it once, before anyone plays — and pick it as an identifier, not a title. name is the part a reader sees.

slug#

The pretty half of the public URL: with a slug your details page lives at /games/<slug>, without one it lives at /games/<id>. Both forms keep resolving once a slug exists, so an id link you shared early never dies.

The collision case is quiet rather than loud. Availability is checked against every other mod's id and slug (checkModSlugAvailability, apps/server/src/store.ts), and when a desired slug is already taken the persist path drops it and stores the mod's own id as its public slug instead. A mod whose URL didn't change after you set a slug lost a race for that word — pick another. Treat the slug as a stable identifier too: changing it moves the page every existing link points at.

name#

The human-readable title — the card heading, the details-page headline, and one of the strings free-text search matches against. Nothing resolves a mod by it: id addresses and slug routes.

That makes it the one naming field you can change freely between releases. Rename it the moment the old title stops describing the game.

version#

Your mod's own release number. It is unrelated to schemaVersion (the manifest format) and to compatibility.engine (the engine you target). Play still serves whatever the registered ref points at, so bumping this doesn't by itself change what a running table loads.

But the label is now immutable once published. A version label is a permanent name for the exact commit it was first published at: re-publishing the same label from a different commit is refused with a 409 mod-version-immutable, and you have to bump this field instead. That is what makes a dependency pin mean something — a dependent names (packId, version) and nothing else, so a label that could be repointed would change what every dependent loads without any of them touching their pin. See Fixing a Rejection.

One more thing reads it — the editor copies it onto the publish-history entry it writes (manifestVersion in createProjectVersion, apps/server/src/store.ts). Treat it as a changelog for humans, and move it whenever you push a change you want to be able to point at later.

type#

A one-word statement of what you published: game-pack for a playable game, component-pack for a library of reusable assets other mods draw on, table-pack for a table and its play surface, room-pack for a room — floor, ceiling, walls, lighting and decor. Pick the one that tells a browsing player what they are getting.

The value reaches a reader in two places: free-text search matches against it alongside name, id and tags, and the mod list prints it beside the scan status.

Two rules do branch on it, and both are refusals.

A room-pack and a table-pack carry no code. Declaring an entry.script is rejected, and so is any capability beyond log. That is not a style rule — the capability disclosure a player sees is derived from the mods a room lists, which does not include what those mods depend on, so a script hiding inside a depended-on pack would run with none of the disclosures firing. If your room needs a script, the script belongs to the game pack that uses the room.

Your type is fixed once you publish. Re-publishing under a different type is refused. A dependent pins a version, not a type, so a room pack that turned into a game pack would change what everyone depending on it loads — and what capabilities they inherit — with no version bump and nobody told. If you need a different kind of pack, publish it under a new id.

entry#

The two pointers from the manifest into your repo: the file the table loads, and the file the sandbox runs. Both members are optional, and an empty entry is valid — an asset-only mod has neither.

That validity is the trap. The scanner skips whichever branch is absent and falls through to compatible, so a mod with no setup publishes cleanly and puts nothing on the table. When a mod scans green and plays as an empty room, read this field before you read anything else.

assets#

Declaring a file here is what makes the scanner responsible for it: every listed path is fetched, size-checked, content-type-checked and hashed at registration, so a path that 404s on the published ref is a rejection you see at publish time instead of a missing texture a player sees at the table. Players download everything listed here before the table opens.

You do not maintain this list. It is derived: the editor recomputes it from your project's file tree on every save, and the publish endpoint recomputes it again from the pushed tree. Every table asset in the tree is declared automatically; the manifest itself, the entry files, rulebook pages, and editor-only files (originals/, thumbnails/, screenshots/, a deck's per-card source images, link records) never are. A path you add or remove by hand is overwritten by the next save.

The one decision that is yours is the opposite one — keeping a declarable file out. That is stored in excludedAssets, which the reconciler honours, and it is set per file on the manifest editor's Files tab.

What surprises people is the fate of a file that is not declared. It still loads — AssetResolver falls back to raw.githubusercontent.com/{owner}/{repo}/{ref} for any repo-relative path — but it arrives unverified, uncached, and one request at a time, the first time something asks for it. The bytes stay in your GitHub repo throughout; nothing here uploads them to our servers. See Assets for the extension allowlist and the size cap.

assetManifest#

An optional catalog of the same repo files, one entry per file, that upgrades the play-time download from "fetch what's declared" to "fetch what's declared and check it arrived intact". When it is present and non-empty it replaces assets as the pull list (installModAssetResolver, apps/web/src/ui/App.tsx), and each downloaded file is verified against its recorded hash before it enters the local play cache.

Keep it in step with the bytes you publish. It describes files in your GitHub repo rather than copying them anywhere, and an entry whose hash no longer matches its file costs you the cache rather than the asset — the resolver still reaches the file on GitHub, session after session, without ever storing it.

excludedAssets#

The files you have chosen not to pre-load — the one manual decision about assets that survives a save.

assets is a derived list: the editor recomputes it from your project's file tree on every save and the publish endpoint recomputes it again from the pushed tree, so removing a path from assets by hand only lasts until the next reconcile puts it straight back. "Do not pre-load this one" therefore cannot live in assets. It lives here, and the reconciler reads this list and leaves those paths out.

An excluded file is not removed from your pack. It is still pushed to your repository and it still works at the table: AssetResolver fetches it the first time something uses it. What it skips is everything declaring buys — it is not fetched, size-checked and hashed at registration, and players do not download it before the table opens. That is the trade. It suits a large file most sessions never touch (an optional expansion's board, an alternate art set); it is the wrong choice for anything on the table at load, which would then arrive late and unverified while a player watches a placeholder.

You do not hand-write this either. Open Mod ▸ Mod Details…, go to the Files tab, and switch Pre-load off for the file — its state changes from Pre-loaded to On demand.

The list maintains itself the same way assets does:

  • an entry whose file has been deleted is pruned, so this never names a file the tree does not have;
  • an entry follows its file through a rename or a move;
  • an entry that could never be declared anyway — an entry file, a thumbnail, anything under originals/ — is dropped;
  • when the last entry goes, the key is removed rather than left as [].

Every pack type may use it; it is not one of the type-restricted fields.

An older server ignores it rather than refusing it. A server built before this field existed strips the key from its stored copy and re-declares the files, which is simply the old behaviour: your exclusion is ignored and the files are pre-loaded. A manifest carrying excludedAssets is never rejected for it.

JSON
"assets": ["assets/board.png", "assets/models/die.glb"],
"excludedAssets": ["assets/expansion/board-xl.png"]

assetRepos#

Almost every pack omits this. It exists for one case: a card catalogue whose art lives in somebody else's GitHub repository — set images maintained by a community project, say — rather than in your own. Those rows carry absolute raw.githubusercontent.com URLs, so they never travel the repo-relative path the asset CDN normally routes, and the CDN would refuse them anyway because the repo behind them is not one this platform registered.

Listing a repo here does exactly two things. It puts that coordinate on the edge's allowlist, and it lets the client rewrite absolute GitHub URLs naming it onto cdn.diceytable.com. It grants no read a player's browser did not already have: everything it admits is public on GitHub and fetchable from the same URL by the same browser. What it changes is whose bytes we are willing to serve from our domain — which is why it is capped at four entries, shown on your pack's page, and dies with the pack that declared it. A blocked pack's declarations stop being served with it.

Declared, never inferred — but you rarely write it yourself. The CDN will not read your catalogue and work the hosts out for itself, deliberately: that would make the set of repositories we proxy a function of a data file nobody reviews. An entry here is a line in a public, commit-pinned manifest that a person reads once, which is the same property that makes a mod name a plugin function rather than a URL.

What the platform does instead is write that line for you when you publish from the editor. It reads every card catalogue (*.cards.json) your manifest lists under assets, takes the owner/repo/ref of each absolute raw.githubusercontent.com art URL exactly as the URLs spell it, and appends any coordinate assetRepos does not already cover to the committed diceytable.mod.json. The result is still an ordinary declaration in your published manifest, reviewed like any other line; nothing downstream infers anything.

  • Additive only. Entries you wrote are never removed or edited, even one no catalogue URL uses any more. Delete a stale entry yourself — it still counts toward the cap of four.
  • Literal refs. An art URL at refs/heads/release produces a refs/heads/release entry, never master or main, because the ref is compared literally.
  • Stops at four. Coordinates that do not fit, or that are not a valid declaration, are left out and reported by the scanner's catalogue-art-undeclared warning.
  • Stable. New entries are appended in sorted order, so republishing an unchanged pack does not change the file.

You still declare by hand any outside repository your art reaches other than through a card catalogue, and any pack you publish without the editor (pushing to GitHub yourself and registering the repo).

Undeclared art is not broken — it keeps loading straight from GitHub, exactly as it always has. It is only slower. See Asset Delivery and the CDN.

JSON
"assetRepos": [
  { "owner": "SWTCG", "repo": "SWTCG-LACKEY", "ref": "refs/heads/release" }
]

pluginSettings#

Your pack's answers to the settings a plugin declares, keyed by plugin id and then by setting key.

A plugin manifest may declare a small form — a select of which sets to include, a toggle for promos, a number for a page size. It declares the shape; your manifest supplies the values. Both are public, commit-pinned documents, so anybody reading your pack can see what is configurable and what you configured, without running anything.

You do not hand-write this. Open diceytable.mod.json in the editor (Mod ▸ Mod Details…), go to the Plugins tab, and fill in the Settings form on the plugin's card — the controls, their labels and their bounds all come from the plugin. The same card holds the functions your script may call (plugins), so attaching a plugin and configuring it are one place. A plugin you only use as a deck source, and never call, can be given answers with Configure only, which writes this key without adding a plugins entry. Remove on a card drops both.

Values are flat scalars only: string, number or boolean, matching the four control types. Nesting is refused for the same reason a deck's data bag refuses it — this travels with your pack and is read by other code, and a structure invites a settings form to become a smuggled document.

Two behaviours worth knowing:

  • Leaving a setting unanswered is normal. Every setting falls back to the default the plugin declared. If answers were required, a plugin could break every mod using it just by adding one.
  • An answer to a setting the plugin no longer declares is reported, not silently dropped. That is how a plugin's breakingVersion bump reaches you: the editor shows the stale key with a Remove button rather than quietly discarding configuration you wrote.

Configuring a plugin here does not enable it at a table — a table's owner still chooses that in Settings ▸ Room ▸ Plugins at the table.

A room-pack or table-pack may not declare it, for the reason plugins gives: a pack that runs no script can call no plugin, so there is nothing for these answers to configure. The schema refuses the key by name and the manifest editor has no Plugins tab for those types.

JSON
"pluginSettings": {
  "community.swtcg-deckdb": { "set_filter": "core", "include_promos": false }
}

compatibility#

Your declaration of which engine builds the mod is written against, tested once when the mod is registered or re-scanned. A mod that fails the test is marked incompatible, and an incompatible mod cannot be selected for a room.

The grammar looks like semver and is not — read Engine compatibility before you invent a range, because one natural-looking form matches every engine version there has ever been.

capabilities#

The block a reviewer — or a cautious player — reads before opening your code: a least-privilege statement of which parts of the mod api your script touches. The scanner cross-checks it against the literal api.<method>( call sites it finds in entry.script, and refuses both to register and to serve a mod whose script uses something the manifest doesn't declare.

Omitting the block is a decision rather than an opt-out. A manifest with no capabilities is granted log and nothing else, so a mod that leaves it out and calls api.createObject fails scanning. Mod capabilities covers all 11 slugs, the methods each one unlocks, and what a declaration does and does not guarantee at run time. One of them is worth naming here: read-hidden-information is the only way a mod reaches real card faces, deck order or secretMetadata, it is never implied by read-world, and a player reading your manifest will see it.

license#

Free text, shown as-is on your mod's details page. Nothing parses it: no SPDX check, no enum, no allowlist — "whatever I want" registers as readily as "MIT".

Because it is unchecked, it is also the field most likely to be quietly wrong. Write the identifier you actually mean, and make it the one that matches the LICENSE file in the repo you are publishing.

tags#

Free-form keywords, and the manifest's only working filter: the details page links each tag to /games?tag=<tag>, and discovery matches a tag query against your list case-insensitively (discoverMods, apps/server/src/services/modService.ts). They also join name, id and type in the free-text search haystack.

Use the words a player would type, not the words you use internally. category is the other half of the pair — one curated slug from a fixed taxonomy, where tags are many and entirely yours.

summary#

The one line under your mod's title on cards, the games list and the details page. It renders through the inline markdown renderer, so **bold**, `code` and links come through while paragraphs and headings do not — the field stays on one line by construction.

Leaving it out costs you the first sentence a browsing player reads: the card falls back to printing your tags joined by commas, and to "No description provided." when there are no tags either. Write the sentence that makes someone click.

description#

The long-form body of the details page, rendered as markdown under an "About" heading — the only field with room for rules, credits and attribution. Raw HTML in it is escaped rather than executed, and links are restricted to http, https and mailto, so anything else you paste arrives as plain text.

Write it for someone deciding whether to play. The table never shows this text to the people already at it.

category#

One slug from a curated taxonomy, chosen to tell a browsing player what shape of game this is. It renders as the labeled chip on game cards, on the home page spotlight and on the details page.

What it does not do is filter. Discovery narrows on tags and scan status, and nothing queries by category today (discoverMods, apps/server/src/services/modService.ts). So pick the slug that reads best to a human and put the words you want to be found by into tags. The full list is on Mod categories.

players#

The player count your rules are written for. It renders as a chip on game cards and the details page, and rides along on the home page spotlight payload.

Nothing enforces it: seats belong to the room, so a six-seat table loads a mod that claims four without complaint. Treat it as a promise to a reader rather than a constraint on a session. The whole object is optional, and a mod that omits it shows no chip at all — for a game that plays at any count, that is the honest answer.

A game pack and a table pack use it; a room pack and an asset pack do not. The range describes how many people sit down to the thing — a table publishes it as its Seats, a room seats nobody (the table standing in it does) and neither does a box of parts. The editor drops the control for those two types rather than inviting an answer to a question the pack has none for. Nothing is refused over it, so a manifest that carries one anyway still publishes; the editor lists it as a key the pack cannot use, with a Remove button.

coverImage#

The square artwork that carries your mod everywhere it appears in a list — the game card, the home page spotlight, the details page hero. A mod without one draws a placeholder icon, and the spotlight prefers mods that have artwork over mods that don't, so this is the field that decides whether you are seen at all.

It needs no entry in assets. The scanner sweeps cover and screenshot targets separately and validates them as images wherever they are referenced from. Let the editor's media panel produce the file — it writes the square WebP and the thumbnail that pairs with it. See Cover art and screenshots.

screenshots#

The details-page gallery, shown in array order. The editor's move-left and move-right buttons reorder this array and nothing else sorts it, so whatever sits first is what most people see.

An entry is a screenshot, a video, or a video with a screenshot as its cover. It must be at least one of the two — an entry with neither a path nor a video is refused at publish rather than rendering as a gap in your gallery.

The files these paths point at are already cropped and resized to 16:9 by the editor's media pipeline before they are published; the page renders them as they are. The crop recorded beside each path is a note about how the frame was chosen, not an instruction applied at display time.

Videos share the strip with the stills, because the order is your pitch and we are not going to split it into two sections for you. A video entry draws its cover with a play button over it and loads nothing from YouTube until a visitor presses play — so a gallery full of trailers costs a browsing visitor no more than one full of screenshots. See video for how to add one.

JSON
"screenshots": [
  { "path": "media/screenshot-0.webp" },
  { "video": { "provider": "youtube", "id": "aqz-KE-bpKQ", "title": "Two-minute trailer" } },
  {
    "path": "media/screenshot-1.webp",
    "video": { "provider": "youtube", "id": "aqz-KE-bpKQ", "title": "Setup, start to finish" }
  }
]

rules#

The rulebook players read — on your game's public page, and from the Rules button at the table.

Declare a list. Each entry is one document with a title and one of four kinds, and a game usually publishes two or three: a quick-start, the full rules, a how-to-play video, an FAQ.

kind What you publish Best for
markdown A .md file at rules/<id>.md Rules you write and keep editing
pages Rendered .webp pages at rules/<id>/page-NNN.webp, plus the original PDF An existing PDF rulebook
link Nothing — just an https:// URL Rules already published elsewhere, or too big for the limits
video Nothing, or one cover image at rules/<id>/cover.webp A how-to-play video

Nobody downloads your rulebook until they open it. This is the point of the field, and the reason rules files are not listed in assets. Everything in assets is fetched before the table appears, with a progress bar counting every file — correct for a model, wrong for a 10 MB rulebook most players already know and never open. Rules files are fetched only when someone opens the Rules panel, and the list shows each document's size before they do. Once fetched they are cached like any other file, so the second look is instant and the installed app can read them offline.

⚠ Do not add rules files to assets. Declaring one there puts it back in the up-front download and undoes all of that. The editor will not do it for you: rules/ is excluded from the automatic asset reconciliation.

Upload a PDF and we convert it. The editor renders each page to a web-sized WebP — a fraction of the bytes, legible on a phone, and no PDF reader involved on the reading side, which is also why it works in the installed app. Your original PDF is published alongside as a Download the original PDF link whenever it still fits the budget; when it does not, the pages are published without it and the editor tells you so rather than failing the upload.

The limits, and what to do when you exceed one. A PDF may be up to 20 MB and 120 pages on upload, and one finished document — every page plus the preserved original — may be up to 10 MB. Past any of those, upload the file to a file host (Google Drive, Dropbox, your own site) and add it as a link document instead. That is a first-class option, not a consolation: the Rules panel shows the destination host and lets the reader follow it.

A video rulebook plays in place. Add a video document, paste a YouTube link, and the Rules panel draws a cover with a play button; the player loads only when the reader presses it, so a rulebook video costs a player who never opens it nothing at all. Nothing of the video is published — only an optional cover image of your own, which is worth uploading when you want a particular frame rather than whatever YouTube picked. The panel always offers a Watch on YouTube link beside the player, because an embed can be refused by the uploader's settings or by a viewer's network and a reader who presses play needs somewhere to go.

A game may also put a video in its screenshots gallery. Use the gallery for the trailer — what the game looks like — and a video rulebook for the tutorial someone opens mid-game to check a rule.

⚠ A link must be https://. The pages that render it are HTTPS, so a plain-http rulebook is mixed content and fails silently in every modern browser. It is refused at publish, where you are still around to fix it.

⚠ Only a game-pack may declare rules. The Rules button resolves the room's game — its provider mod, or the one selected mod — and the public Rules section renders on a game's page. A room, table or asset pack is a dependency of a game rather than the game, so rules on one are opened by nobody; the publish scanner refuses them with rules-unread, and the editor does not offer the section for those types.

Every file is fetched, type-checked and hashed at publish like any other published byte, so a missing page or a mislabelled file is refused then rather than discovered by a reader. Omit the field and your game simply has no Rules button.

JSON
"rules": [
  {
    "kind": "markdown",
    "id": "quick-start",
    "title": "Quick start",
    "path": "rules/quick-start.md"
  },
  {
    "kind": "pages",
    "id": "rulebook",
    "title": "Full rulebook",
    "pages": [
      { "path": "rules/rulebook/page-001.webp", "width": 1236, "height": 1600, "bytes": 148213 },
      { "path": "rules/rulebook/page-002.webp", "width": 1236, "height": 1600, "bytes": 151902 }
    ],
    "source": { "path": "rules/rulebook/source.pdf", "bytes": 2418877, "filename": "rulebook.pdf" }
  },
  {
    "kind": "video",
    "id": "how-to-play",
    "title": "How to play in five minutes",
    "video": { "provider": "youtube", "id": "aqz-KE-bpKQ" },
    "cover": { "path": "rules/how-to-play/cover.webp", "width": 1280, "height": 720, "bytes": 62104 }
  },
  {
    "kind": "link",
    "id": "faq",
    "title": "Living FAQ",
    "url": "https://example.com/my-game/faq"
  }
]

dice#

Which dice this game uses: the list the table's dice tray offers instead of the standard set. The tray is the popout behind the round dice button on the right edge of the table screen.

These are the dice anyone at the table may roll. Dice that belong to one player, such as faction dice or the same dice in each player's colour, are declared on the scene's seat template instead, not here. See Dice owned by the seat template.

Declare an array. Each entry names one standard die preset as its face layout, and may rename it, preselect a starting count and give it its own look:

Field Required What it does
preset yes The face layout: face count and numbers. One of the seven standard dice presets.
id no A stable key, needed when two entries share a preset.
label no What the picker prints for it, when the preset's own name is not the word your game uses.
defaultCount no How many the picker starts at, so the common roll is one click.
model no A project model to roll instead of the stock die.
modelPreset no Another built-in die's model to roll instead.
color no A tint.
material no One scene material on every slot of the model.

⚠ Absent — or empty — means the standard d4–d20 set, not "no dice". This is the single most important thing to know about the field. Leaving dice out is the normal case and gives every game the six ordinary dice; publishing dice: [] does exactly the same thing, on purpose, because an empty picker looks broken in precisely the situation (a stripped-down write from a tool) where it is most likely an accident. To turn dice off, use diceEnabled: false, not an empty list. The switch leaves this list alone, so turning dice back on restores the dice you chose.

You don't need to write this by hand. The editor's Game row has a Dice panel that edits both fields.

Declare the field when the default set is wrong for your game, which is most often because it is too wide. A game that rolls two d6 and nothing else is easier to play when the picker offers d6 starting at 2 than when it offers six dice starting at zero. Renaming is the other reason: label lets a d6 read Combat die if that is what your rules call it.

Each entry needs its own key. An entry is keyed by its id, or by its preset when it has no id, and two entries with the same key are refused at parse with Each die may be declared once (give dice that share a type distinct ids). A red d6 and a blue d6 are fine; they just need distinct ids. Up to 24 entries.

Stock dice cost a joining player nothing. An entry that only names a preset declares no assets and downloads no bytes. An entry with a model loads that model from your repo like any other project model. In both cases the numbers come from the preset's face table, which is why every entry still names a preset — see preset.

⚠ Only a game-pack may declare dice. The picker offers the dice declared by the room's game — its provider mod, or the single selected mod — and a room, table or asset pack is a dependency of a game rather than the game. A list declared on one of those is offered to nobody, and, worse, is invisible: the picker goes on showing the default d4–d20 set with nothing to say why the dice you curated never appeared. The publish scanner refuses it with dice-unread.

JSON
"dice": [
  { "preset": "die-d6", "label": "Combat die", "defaultCount": 2 },
  { "preset": "die-d20" }
]

diceEnabled#

Whether this game rolls dice at all. Set it to false for a game that has no dice.

Off does three things:

  • The table's dice button (the round button on the right edge of the table screen) is not shown.
  • The VR fist dice panel never opens.
  • The host refuses every dice-roll, including its own. Hiding the button is only presentation. The refusal is what stops a stale client or a hand-built intent from rolling anyway.

It does not remove dice that are already on the table. The host still accepts dice-clear while dice are off. But the Clear button sits under the dice button, so it is hidden too. Turn dice off before a session starts, not while players have rolled dice they still need to clear.

Absent means on. Every game published before this field existed keeps its dice button, so leave the key out rather than writing true. The editor's Dice panel removes the key when you turn dice back on.

It is a separate flag, not an empty dice list. An empty list already means "the standard set". Keeping the switch separate also means turning dice off and on again leaves your curated list exactly as it was.

⚠ Only a game-pack may switch dice off, for the same reason only a game pack may declare dice. The table reads the switch from the room's game, so a room, table or asset pack that sets it switches dice off for nobody. The publish scanner refuses it with dice-unread.

JSON
"diceEnabled": false

diceClearAfterSeconds#

Clear rolled dice by themselves this many seconds after a roll settles. 0, or leaving the key out, keeps them until someone clears them — the default, so every game published before this field existed is unchanged.

It applies to every roll at the table: the dice button, the VR dice panel, and a table script's world.requestRoll, whose own clearAfterSeconds overrides it for that roll. Whole seconds from 0 to 3600.

Two dice are never cleared:

  • A die someone picked up. Picking a rolled die up makes it an ordinary piece (it leaves the roller's custody), so it stays where it was put.
  • A die someone is holding at the moment its time runs out. It is left alone.

The host does the clearing, and every player sees the dice go. The deadline travels with each die (diceTray.clearAt), so it survives the host leaving.

Set it in the editor on the Game row's Dice panel, Clear rolled dice after.

⚠ Only a game-pack may declare it, like dice: the table reads it from the room's game. The publish scanner refuses it on any other pack with dice-unread.

JSON
"diceClearAfterSeconds": 10

soundSets#

Where a mod declares its own audio: a logical name bound to the clips you uploaded into your repo, optionally tagged with the material and the action they represent. A script reaches them with api.playSound({ modSound }), or attaches one to an entity with api.setObjectSound(...).

A mod can never name a clip from the first-party sound library — that is a licensing boundary rather than an oversight, and it is why every play form is semantic. The host also checks a sound reference against the declaring mod's own names, so one mod cannot override another's audio. See Sound sets.

plugins#

Which plugins this mod calls, and exactly which of their functions.

A mod has no network of its own and never will. plugins is how it declares the one external reach it can have: naming a function that an installed plugin already declared, which the platform then performs from its own servers, to an origin the plugin declared, under that plugin's quota and circuit breaker.

Declaring the plugin alone would not be a declaration worth having — a plugin's exposed surface grows over releases, so { "id": … } on its own would silently widen every time the plugin author shipped a new function. Listing the functions makes a mod's external reach a fixed set that changes only when the mod is re-published and re-scanned, which is what lets a reviewer read this array and know the whole of it.

You rarely write this by hand. The manifest editor's Plugins tab has Add to game for a registered plugin and a checkbox per function, and it keeps plugin-call in capabilities.allowed in step with what you tick.

The publish scanner enforces it in both directions. It reads every api.callPlugin("…", "…") out of the script text and rejects any pair this array does not declare (undeclared-plugin-call), and rejects any call site whose target it cannot read as a literal (dynamic-plugin-call). The runtime enforces it again: an undeclared pair resolves not-found, indistinguishable from a plugin that is not installed.

Declaring a function here requires the plugin-call capability. An entry with "functions": [] — a plugin used only for the files it declares under resources — declares no call and does not require it, so it adds nothing to the read-hidden-information + plugin-call disclosure either. Omitting the field entirely means this mod calls no plugins, which is the default and the fail-closed reading.

A room-pack or table-pack may not declare it at all. Those types carry no script (CAP-1), so they can call nothing — and plugin-call is itself a capability they may not declare. The manifest schema refuses the key by name, at the field you wrote it in, rather than letting it fail one field over as a missing capability you would then be tempted to add. A component-pack (an asset pack) may: prefabs carry scripts. The whole per-type table is packages/shared/src/modTypeFields.ts; the same rule covers pluginSettings.

dependencies#

Published packs this mod builds on, each pinned to one exact version.

A pack is a mod — same repo, same manifest, same registry row — so depending on one is how you reuse someone else's room, table or component library instead of vendoring a copy. Omit the field entirely and you depend on nothing, which is what every manifest published before this field existed means.

Pins are exact, and there are no version ranges. ^1.2.0, ~1.2, 1.x and >=1.0.0 are all rejected. A range would hand you the thing this model exists to prevent — an upstream publish silently changing your game — and it would make a table non-reproducible: two players who resolved the range at different times would load different packs, and nothing in the session would notice. You move to a new version by editing the pin, and only then.

A dependency may have dependencies of its own, and there it stops. The graph is capped at two levels: you, what you depend on, and what that depends on. A pack three levels down is refused by name rather than quietly left out — depend on it directly, or vendor it. Cycles are refused for the same reason: a graph that reaches itself has no order in which its packs can be composed.

Three more rules the publish check enforces, all of them named refusals rather than silent fixes:

  • A pack cannot depend on itself, and cannot list the same pack twice.
  • Two different pins of the same pack anywhere in your graph are refused. One pack, one version.
  • A dependency that cannot be resolved is an error at publish, not a surprise at play.

Licences are surfaced, never enforced: you acknowledge a dependency's licence when you add it, and the attribution on your listing is derived from this list, so there is no credit field for you to forget.

setupOptions#

Per-game options the host chooses in the lobby, before the table exists.

The manifest declares the questions — a small, typed form. The answers are chosen once per room and live on the room record, not in the snapshot and not in mod saved data: they are session configuration, decided before anything is on the table, read once at setup and never mutated by play.

Delivered to a running table. The answers reach your game's table scripts through world.getSetupOptions(), and a mod entry script as the third argument of setup(api, manifest, options). Both are resolved on the host from the room record and your own manifest, never by the sandbox. Every option you declared is present, because a declaration always carries a default.

Author them in the editor, not by hand. The manifest editor's Gameplay tab has a Setup options section that writes this field for you and checks every row with the rules below as you type; see the Gameplay tab.

The form is drawn in the lobby, under Game options, from your declaration: the room's owner answers it before pressing Start, and an owner who touches nothing leaves every option at its default — which is why a sensible default on every option is what the schema requires in the first place.

⚠ Setup options are the OWNER'S answers, one set for the room. For a question each player answers for themselves — "which deck are you bringing?" — see lobbyRequirements, which is enforced: Start is refused until everyone playing has answered.

⚠ Setup options are not the only choice a lobby offers. A game may also declare variants — whole alternative set-ups (a different board, a bigger table, the same game played by hand) that the platform resolves before any script runs. An option is an answer your script acts on; a variant is a different scene. A variant needs no script. The answers reach your scripts whichever variant was chosen, and an option is offered for every variant: it cannot be limited to one. Variants or setup options? has the comparison.

🔴 A game with no script can never read an option, and the scanner refuses it. Only a script has anywhere for an answer to arrive: a table script (any script in the game's scene) or an entry.script. A pack whose entry is a setup.json with no scripts in it has no code at all (instantiating a setup file places the entities it names and consults nothing else), so an option declared there would be answered by a host and then read by no one. A typical scriptless checkers pack is exactly this shape. Declaring setupOptions on such a mod registers it as incompatible with the setup-options-unreadable error, which names the first option key and tells you to add a script or drop the block. A room-pack or table-pack is never a room's game, so its refusal says to remove the options or republish as a game pack. The refusal is deliberate: a silently ignored options block is worse than being turned away, because a host configures something that does nothing and nothing anywhere says so.

A credential pasted into an option is refused too. Defaults, select choice values and labels are walked by the same tripwire the plugin registry uses, and anything credential-shaped is a manifest-secret error. A manifest is public and, once registered, pinned to an immutable commit — a key committed here is a published key.

The vocabulary is the same four controls a plugin declares its settings with, and for the same reason: a mod says which form element, never how it looks or where it sits. Every control here is meant to render as one of our own components, so a manifest can configure a game without becoming a page.

Omitting the field means this mod offers no choices. That is the default and the fail-closed reading: nothing to ask, and nothing for a script to read.

lobbyRequirements#

What each player has to choose before the table opens.

The sibling of setupOptions, and the difference between them is who answers. A setup option is one question the room's owner answers once for everybody, delivered to your setup(). A lobby requirement is one question each seated player answers for themselves, and the room owner cannot press Start until they all have.

A deck requirement puts a picker in the lobby. It lists decks for your game — read with that player's session, not the host's — narrowed by anything you declare here. What they choose shows on the lobby roster, so everybody can see who is still deciding, and it is put on the table for them as they walk in, through the ordinary deck-load path.

Where the picker looks: deckSources

By default the picker offers the player's own decks and nothing else, which is what every pack published before this field shipped with. deckSources widens it, and its order is the tab order:

Source What it lists
mine The player's own decks for this game, at any visibility. Owner-scoped by the server.
community Every deck other players made public for this game. Never anybody's private decks.
database Public lists on an outside provider, through a plugin you have already declared.
game The decks your game ships itself, in its gameDecks file — the same list for every member.

⚠ A wider pool is never a wider read, and your manifest is not what makes that true. mine is scoped to the caller in the statement itself and community is a bare "public only" predicate, so there is no declaration that could reach somebody else's private deck. Widening is a product decision, not a permission.

database — an outside deck site, through your plugin

Name the plugin and the function that lists its public decks:

JSON
"deckSources": ["mine", "community", "database"],
"deckDatabase": {
  "pluginId": "community.swtcg-deckdb",
  "listFunction": "publicDecks",
  "label": "swtcg-deckdb.com"
}

🔴 This is a NAME, never a request — the same contract every other plugin call follows. The chain is requirement → plugin id + function name → plugin manifest → endpoint → origin + path template, all declared data, and the fetch happens server-side under that plugin's own origin allowlist, quota and circuit breaker. There is no URL here and there will not be one.

⚠ The plugin and the function must both be in your plugins block. A requirement is not a second way to reach a plugin you have not declared: publish refuses one that is missing, naming it. That block stays the whole of your pack's external reach, readable without running anything.

The listing function must take no required parameters and return rows carrying at least an id and a name. It is called once when the tab opens and searched in the browser — providers that publish their whole public list as one document (the common case, and the reason this exists) have no search endpoint to call, and turning keystrokes into provider requests would spend that plugin's shared daily budget on typing.

Picking a result imports it. The platform asks your plugin's declared deckImport block for that list, joins it against your game's own card catalogue in the player's browser, and saves the result as a private deck of theirs. So the answer that reaches the roster is an ordinary deck reference like any other, and the player keeps the deck afterwards instead of borrowing it for one game. Cards the provider names that your catalogue does not have are left out and said so — never guessed. A provider whose plugin declares no deckImport cannot be a database source.

This is the part a mod script cannot do. api.setUiElement is host-only, so a picker drawn from inside the sandbox is necessarily built by the host's copy of your script — which means every deck it can list was read with the host's credentials. That is a real constraint, not an oversight, and it is why the packs that ship their own deck dialog offer "my decks" to the host alone. Declaring it here moves the ask to the lobby, where each person's own client reads their own library.

game — the decks your game ships

Starter decks, prebuilt decks, tournament lists: name one .json file of them in gameDecks and list "game" here, and the picker gains a Game decks tab, grouped under Starter decks, Prebuilt decks and Tournament & expert decks by each deck's level, with who made each one.

JSON
"gameDecks": "decks/game-decks.json",
"lobbyRequirements": [
  {
    "id": "deck",
    "kind": "deck",
    "label": "Your deck",
    "deckSources": ["game", "mine", "community"]
  }
]

Picking a game deck imports nothing. The answer on the roster is a reference into your pack (game:<id>), so no player's library gains a deck they did not build, and the table loads the list from the same file when they sit down. A requirement that lists "game" with no gameDecks file fails to parse.

It is also how bots get decks. A bot has no library, so the first deck requirement that lists "game" is the one a bot's deck answers. In an unranked room the owner can choose a game deck for each bot; your scene script reads it as PlayerInfo.deckId. Without a requirement that lists "game", bots cannot be handed a deck at all.

Deck icons: deckIcon

A requirement can show a small picture beside each deck — the Star Wars TCG pack shows each deck's side. Give a default image, or a field to read from each deck row plus a map from its values to images, or both:

JSON
"deckIcon": {
  "field": "side",
  "map": { "L": "ui/side-light.png", "D": "ui/side-dark.png" }
}

Every path is a PNG, JPEG or WebP file of your own pack, declared in assets — never a URL. A deck-database row is read through field; a game deck through its own side, formatId, pool or level; a saved deck through its format id ("field": "formatId") or, for any other field, from its cards' own field values. The full rules are under deckIcon.

Pairing: distinctBy

For a game played side against side, declare that no two decks at the table — players' or bots' — may share a deckIcon value, except the ones you list:

JSON
"distinctBy": { "except": ["N"], "labels": { "L": "Light Side", "D": "Dark Side" } }

The picker greys out a deck that would clash, the owner cannot give a bot one, and Start is refused (lobby-pairing-conflict) while two decks clash. A deck whose value the lobby cannot know — a player's own saved deck has no side — never clashes, so your script remains the backstop. Needs a deckIcon with a field and map. The full rules are under distinctBy.

⚠ Unlike setupOptions, a pack with no entry script may declare these. A requirement is asked, checked and applied entirely by the platform, so there is nothing here that needs a script to read it.

⚠ But only a game-pack may declare them at all. Requirements are read from the single mod the lobby resolves as the room's game — its provider, or the one selected mod. A room, table or asset pack is a dependency of a game rather than the game, so a requirement on one is asked of nobody; the publish scanner refuses it with lobby-requirements-unread, and the manifest editor does not offer the field for those types. Scriptlessness and being the game are two different axes: a game pack with no script is fine here, and an asset pack full of scripts is not.

Nothing is enforced client-side. Every answer is re-checked by the server against this declaration, and Start is refused with lobby-requirements-unmet while a required one is outstanding. The greyed-out row in the picker is courtesy; the refusal is the rule.

Omitting the field means your game requires nothing, and a lobby for it looks exactly as it did before this existed. At most four may be declared: a lobby that asks more questions than that has stopped being a lobby.

JSON
"lobbyRequirements": [
  {
    "id": "deck",
    "kind": "deck",
    "label": "Your deck",
    "help": "60 cards, one side. Build one on this game's Decks tab.",
    "required": true,
    "minCards": 60,
    "deckSources": ["mine", "community"]
  }
]

gameDecks#

The repo path of one .json file of decklists your game ships — starter decks, prebuilt decks, tournament lists, the decks your bots play. A trading-card game is unplayable until each seat has a deck, and a new player has none; this file gives every player something to pick on their first visit.

JSON
"gameDecks": "decks/game-decks.json"

What reads it.

  • The lobby. A deck requirement that lists "game" in deckSources gets a Game decks tab in its picker, listing every deck in the file for every member. Picking one imports nothing: the answer on the roster is a reference (game:<id>) into your pack, nobody's library gains a deck, and the table loads the list from the same file when the player sits down.
  • Bots. In an unranked room the owner can hand a bot one of these decks (Choose deck on the bot's row). Game decks are the only pool a bot's deck can come from — a bot has no library — so this also needs a deck requirement that lists "game". Your scene script reads the choice as PlayerInfo.deckId and builds the bot's deck itself.
  • Your scripts. It is a declared data file like any other, so a scene script reads it with world.readData — to choose a bot's deck when nobody did, say.

Declaring the file. The path must be a relative .json path inside your pack (no .., no URL), at most 180 characters, and listed in assets or excludedAssets exactly as written. Saving the project in Edit Mode declares it; leave it to load on demand (in excludedAssets) so players download it only when the picker or a script asks. Publish refuses an undeclared file (game-decks-undeclared), one it cannot read (game-decks-missing) and one that is not a valid decks file (game-decks-invalid) — a broken file would otherwise show up as an empty picker in every lobby. A requirement that lists "game" while this field is absent fails to parse: its tab would have nothing in it.

The file

JSON
{
  "version": 1,
  "decks": [
    {
      "id": "hope-light",
      "name": "Hope",
      "side": "L",
      "formatId": "Standard",
      "pool": "Standard VII",
      "level": "veteran",
      "description": "A Rebel deck that takes the Space arena early.",
      "credit": {
        "by": "The IDC",
        "source": "IDC prebuilt deck",
        "url": "https://example.com/decks/hope"
      },
      "cards": [
        { "cardId": "ANH-12", "count": 4 },
        { "cardId": "ANH-31", "count": 2, "partitionId": "main" }
      ]
    }
  ]
}
Key Required What it is
version yes Always 1.
decks yes At most 500 decks. Each id must be unique within the file.
decks[].id yes Lowercase letters, digits and dashes, starting with a letter or digit, at most 58 characters — so game:<id> fits the deck-load intent's 64-character limit. A player's choice is stored by this id, so keep it stable between versions.
decks[].name yes What the picker shows.
decks[].side no Your game's own word for which side the deck plays (L, D, N…). Up to 64 characters.
decks[].formatId no The format it is built for, in your game's words (Galaxy, Standard). May be null.
decks[].pool no A narrower card pool within the format (Standard VII). May be null.
decks[].level yes novice, veteran or competitive. The picker groups decks under Starter decks, Prebuilt decks and Tournament & expert decks; your script can use it to match a bot's deck to its difficulty.
decks[].description no One or two plain sentences, up to 600 characters. Shown as plain text.
decks[].credit yes by (who built it, up to 160 characters), source (where it comes from, up to 160) and an optional url, which must be https://. Credit is not optional: a tournament list belongs to the player who built it.
decks[].cards yes 1–400 entries of { cardId, count, partitionId? } — the entry shape a saved deck's list uses, with ids from your game's own card catalogue. count is 1–1000 and defaults to 1; with no partitionId the copies go in your card schema's default partition.

An unknown key on the file, a deck or a credit is refused (keys on a card entry other than these three are ignored). The whole file may be at most 2 MB, the same cap as any world.readData read.

A deck requirement's icon and pairing read the deck's own fields. When the requirement's deckIcon.field is side, formatId, pool or level, a game deck supplies that value — which is how distinctBy can tell a Light Side game deck from a Dark Side one before anyone sits down. Any other field name has no value on a game deck.

⚠ It is public pack data. The file is fetched from your published commit like a cover image and every member can read all of it. Never put anything here you would not print in a rulebook.

⚠ Only a game pack's file is ever read. The lobby and the bots read the room's game — the same single mod lobbyRequirements and variants are read from — so a gameDecks on a room, table or asset pack is offered to nobody. The manifest editor offers the field only on a game pack.

variants#

The ways this game can be set up — Go on a 9×9, 13×13 or 19×19 board; a six-seat and a ten-seat table with the same pieces; a fully scripted, ranked game and the same pieces played by hand. The room's owner picks one in the lobby, before the table exists.

This field is the list: an id, the name and one-line description a lobby shows, an optional player range, whether the variant is fully scripted (rulesEnforced) and how it is ranked (ranking). It is the half the registry stores, so it is the only half the lobby, the server and a listing page can read without fetching your scene. What each variant actually changes — which entities it removes, adds or customises, and whether it has its own table, seats, snap points or scene scripts — lives in the other half, the variants block of your setup.json, keyed by the ids declared here. Game variants explains both halves together.

The first entry is the lobby's default. A room whose owner never touches the dropdown plays the first variant in this array, and so does a room record that names an id your game has since removed. Order the list the way you want the lobby to read, with the set-up most people want first.

A variant the scene says nothing about is the scene unchanged. That is a real and useful case rather than an error: a variant called "Big table" may differ from the first one only by its players range. (A variant played by hand is not one of these: it detaches its scripts in its own scene; see Playing by hand.)

Variants are not setupOptions. A setup option is an answer handed to your script, which then does whatever it likes with it — so a pack with no script cannot use one at all. A variant is resolved by the platform, before any script runs, into an ordinary scene. That is why a variant can swap the table, the board and the seats, and why a game with no entry.script may declare variants. Use a variant when the table itself is different; use a setup option when the same table is played with a different number.

Scripts can read which variant was chosen: world.getVariant() in Table Scripting and api.getVariant() in Mod Scripting, both answering { id, rulesEnforced, ranked }. It is not on the manifest argument of setup(api, manifest, options), and not in options. A scripts key on an entry is refused (variant-scripts-removed): which scripts a variant runs is its scene data now.

At most 12, and two entries may not share an id — a repeated id would leave the owner's choice ambiguous, so it fails the parse rather than letting the last one win. The editor writes this list for you from Mod ▸ Variants…, and removes the key again when fewer than two variants are left: a game with one variant has one way to play, which is exactly what an absent list already means.

Game packs only. The lobby reads variants from the one mod it resolves as the room's game, so a list on a room, table or asset pack is a dropdown nobody is ever shown. Publishing one is refused with variants-unread. The manifest's list and the scene's block must also name the same ids; the three refusals for when they do not are under Variant rules, and a ranked variant has four rules of its own.

Omitting the field means the game has one way to play. That is the default, and every manifest written before variants existed keeps parsing unchanged.

aiModels#

The AI models this game ships for its bots — at most 4 per manifest. Each entry names one .onnx file in your repository and describes it exactly: its size, its SHA-256, its input and output tensors, and the weakest device that should host it. Bots name a model by id (bots[].modelId); a mod script can also evaluate one directly with api.ai.evaluate under the ai-inference capability.

A model is data, never code. DiceyTable loads ONNX and nothing else, and the publish scanner opens every declared file at the pinned commit and refuses it unless it is a plain feed-forward graph built from a fixed list of operators — no loops, no branches, no sub-graphs, no custom operators, no external data, no strings. The full rule set and every refusal code are under What gets rejected.

Sizes. One model may be at most 64 MiB, and all of a mod's models together at most 128 MiB — every host downloads the models its table uses. The in-app Publish sends at most 45 MiB per file, so a larger model must be pushed to your repository with git before you publish. Most board-game models are far smaller: a Reversi-class network is about 2 MB.

Run-time memory is bounded too. The checker works out, from the file alone, how big every value the model computes will be, as a function of the batch size. No single value may exceed 16,777,216 elements and all of them together 536,870,912; a model over either cap for one position is refused (ai-model-shape-unbounded). Otherwise the model gets a batch limit — the largest batch, up to 256, at which both caps hold — and a call with more positions is refused at the table. Ordinary board-game networks keep 256; only large towers on large boards get less. The declared outputs are bounded separately: one position's outputs may be at most 8 MiB, and a call's whole batch of outputs at most 8 MiB. See Limits and caps.

Every file must be declared, and every declaration must be in assets. An .onnx file in assets that no entry here names is refused (ai-model-undeclared), and an entry whose path is not in assets fails the manifest check. Use the editor's Import model… (Manifest ▸ Bots): it checks the file with the scanner's own code, writes it to ai/<id>.onnx, fills in every field below, and keeps assets in step.

Game packs only. A model on a room, table or asset pack would be published and never run, so it is refused at publish (bots-not-allowed-for-type).

Omitting the field means the game ships no model — the right answer for scripted bots, which need none.

bots#

The opponents this game offers in the lobby — at most 8. Each is a seat-holding bot: it takes turns, counts toward the player limit, and is played by your scene script, which registers a handler for it with bots.register.

Two kinds, one contract:

  • "scripted" — script code alone. It runs on any host, needs no model, and can still search: ai.mcts with no modelId scores positions with your rules kernel's heuristic.
  • "ai" — the same, whose script also evaluates one of your aiModels. A table seating one needs a host device at or above the minTier of the model it plays with; name a scripted fallbackBotId for the host that cannot. Its modelId is its default model; each difficulty may name its own (difficulties[].modelId) for a separate network per strength.

Declaring bots earns your listing tags: bots for any, plus bots-ai and/or bots-scripted by kind. They are derived when the catalogue reads your manifest — writing them into tags yourself does nothing — so a pack cannot claim an opponent it does not ship. The game's page shows a Bots section listing each bot, its difficulties and, for an AI bot, the hardware it needs and its model's download size.

Every handler must be registered. Publishing lifts the handler ids each scene script passes to bots.register out of its compiled body and refuses a bot nobody registers (bot-handler-missing).

Hidden information. A bot runs on the host and its script can read the whole table, face-down cards included. The lobby and the table tell players "Bots run on the host and can see the whole table, including hidden cards." whenever your game declares bots and its table has anything that can be hidden (a card, a deck, a card holder, a hand zone or a hidden zone), or your manifest declares read-hidden-information. See Game bots: hidden information for what an honest author declares.

Game packs only — refused at publish elsewhere (bots-not-allowed-for-type).

The manifest check also refuses, with the path of the entry: two bots with one id, two bots on one handler, an AI bot without a modelId or naming a model you do not declare, a difficulty naming a model you do not declare, a modelId or fallbackBotId on a scripted bot or a modelId on one of its difficulties, a fallback that is not one of your scripted bots, a defaultDifficulty the bot does not declare, and a seats.min (only seats.max exists).

credits#

Where the files in your mod came from, and who takes responsibility for them.

You do not write this by hand. Every time you import a file in the editor — art, a model, card images, audio, cover art — a window asks where it came from before the file is written into your project, and your answer is recorded here. It is published in your manifest, so anybody reading your mod can see it, and it is what the Credits tab on your game's page shows.

Each entry covers one import, which may be one file or four hundred, and says one of three things:

  • own-work — you made it, or you hold the rights to publish it.
  • third-party — somebody else made it. This one requires a creator, a link to them (creatorUrl or sourceUrl), and the licence it is used under (licenseName or licenseUrl). A credit nobody can follow credits nobody, which is why the link is not optional.
  • disclaimed — you are publishing it without saying. This is allowed, and it costs a signature: you accept full responsibility for the file and indemnify DiceyTable and its owner. The Credits tab shows these entries as what they are rather than hiding them.

Every entry you answered for carries an attestation — the version of the wording you accepted, when, and the name you signed with. That is what makes the record mean something later, so the texts are versioned and never edited in place. (A credit copied from a library item is the library's, not yours, and carries none; see locked.)

An AI agent may answer for you, and then a person has to check. When an agent working in the editor answers the credit question, the entry carries an aiAttestation instead of your attestation. That entry is unreviewed, and while any entry is unreviewed no publish goes through — not from the editor, and not by any other route, because the scanner refuses the manifest too (ai-credit-unreviewed). Reviewing it adds your signature beside the agent's record. See Credits an AI agent attested for the review, the re-signing rules, and why an older client refuses such an entry outright.

license is a different field and the two get confused constantly. license covers the mod — your rules text, your arrangement, your own work. credits covers the files, most of which you may not have made. A mod can be MIT and still contain art nobody may redistribute.

Your table and room are credited for you. On a game's page, the Credits tab also lists the table the game is played on and the room it is set in, each in its own labelled section. The credits come from those packs' own manifests, at the exact version your game pins - or, when your game pins no room or table, from the default pack's own manifest (Modern Room, Square Table). The built-in Dining Table is credited from DiceyTable's own records. Do not copy any of them into your game's credits. Anything you add to the room from your own game's files is still yours to credit.

Absent means no credits have been recorded, which is the honest state for every mod published before this existed — never a claim of authorship. The editor lists uncredited files under Not yet accounted for in the Credits tab; re-import one to record where it came from. Publishing is not blocked over a missing credit. It is blocked only over an unreviewed AI-attested one, above.

Nothing here is checked for you. DiceyTable does not verify that a named licence permits what you are doing, and it does not review the files you import. What the record does is make the claim yours, attributable and public.

modManifestSchema.entry#

Field Type Required Default Min / Max Pattern Rule Description
setup string no — 1–180 chars — — —
script string no — 1–180 chars — — —

entry.setup

The file the table loads to place your starting entities. Two formats are accepted, and they are told apart by content rather than by filename: the editor-authored scene the Edit Mode shell writes, or the older hand-written setup document.

Leave it out and the mod loads to an empty table — correct for an asset-only mod, and the first thing to check when a game you published starts with nothing on it. Setup JSON covers both formats and how each one is validated.

entry.script

The JavaScript file the sandbox runs, entered through exports.setup(api, manifest). It has to end .js: any other path is the hard unsupported-script-type rejection, "Sandboxed mod scripts must be JavaScript files."

There is no build step on our side. If you write TypeScript, compile it yourself and publish the emitted .js alongside the manifest. TypeScript belongs to the other surface — Table Scripting is authored and compiled inside the editor and uses world/globalEvents rather than api; see Choosing a surface to decide which one you want.

modManifestSchema.assetRepos#

Field Type Required Default Min / Max Pattern Rule Description
owner string yes — 1–39 chars ^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$ — —
repo string yes — 1–100 chars ^[A-Za-z0-9._-]+$ — —
ref string yes — 1–120 chars ^(?:refs\/(?:heads|tags)\/)?[A-Za-z0-9._/-]+$ — —

Whole-object rules:

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

assetRepos.owner

The GitHub account or organisation that owns the repository — the first path segment of its URL.

Matched case-insensitively, because GitHub serves SWTCG and swtcg as the same account and an allowlist that folded one but not the other could be walked round by changing capitalisation. Write it the way the repository owner writes it; nothing depends on which case you choose.

assetRepos.repo

The repository name — the second path segment of its URL, with no .git suffix and no owner prefix.

Case-insensitive for the same reason as owner. The repository must be public: the edge fetches it unauthenticated, exactly as a player's browser would, and holds no credential that could reach a private one.

assetRepos.ref

Which commit, branch or tag the art is read at. A commit sha, a bare branch or tag name, or a fully-qualified refs/heads/<name>.

The ref is matched exactly, and that is load-bearing. Declaring main does not authorise a sha, and a sha does not authorise main — they are different bytes. If your art URLs address a branch, declare that branch.

A sha is preferred and a branch is allowed. Registration emits an asset-repo-unpinned warning for a branch rather than refusing it, because you often cannot pin somebody else's repository: the day they publish a new set, every card in it would render blank until you re-published your pack just to move the pin. The trade-off the warning is telling you about is caching — the edge holds a sha-addressed file for a year and a branch-addressed one for minutes, and a branch's contents can change without your pack being re-published or re-reviewed. Pin a sha whenever the repository is one you control.

Pin the full 40-character sha. An abbreviated sha draws the same warning and gets the branch cache: cafe1234 is also a legal branch name, and GitHub resolves either. A full sha earns the year-long cache only once GitHub's commits API confirms it is a commit in that repository.

modManifestSchema.compatibility#

Field Type Required Default Min / Max Pattern Rule Description
engine string yes — 1–40 chars — — —

compatibility.engine

The range string the scanner tests against the server's ENGINE_VERSION — the whole of what compatibility carries today. It is read once, when the mod is registered or re-scanned; an already registered mod is not re-tested as the engine moves under it.

It looks like semver and is not. The parser reads at most one >= bound and one < bound out of the string and ignores everything else, so a range with no bound it recognizes matches every version silently. Engine compatibility gives the exact grammar and the form to write.

modManifestSchema.capabilities#

Field Type Required Default Min / Max Pattern Rule Description
version "1" no "1" — — — —
allowed modCapabilitySchema[] no ["log"] <= 20 items — — —

capabilities.version

Versions the shape of the capabilities block itself, so a future revision of the grant format could be told apart from this one. There is a single shape today and no second version to migrate to.

Nothing beyond the schema literal reads it. Write it and move on — allowed is the field in this block that decides anything.

capabilities.allowed

The list that decides which parts of the mod api your script is permitted to touch: log, spawn-object, register-action, read-context, read-world, read-hidden-information, object-action, saved-data, subscribe-events, ui and play-sound.

The check runs in one direction only. Declaring a capability you never use is never flagged; calling a method whose capability you didn't declare is refused at registration and again every time the artifact is served, so a script edited after a green scan fails to load rather than running with more reach than it declared. Least privilege here is a discipline you keep — start from what your script calls today and extend the list when you add a call.

Two of the eleven deserve a second look before you commit the list. read-world no longer means "the host's view of the table": all six of its reads are redacted to the least-privileged view on every peer, so a mod that declares it can count a hand but never identify one. read-hidden-information is the elevated read — it gates api.getUnredactedSnapshot() alone, is never implied by read-world, and is what a player reading your listing will understand as "this mod can see hidden cards". Declare it when a rule genuinely has to adjudicate a secret, and take it back off when that call goes. Mod capabilities has the per-capability method matrix and the exact enforcement each one gets at run time.

modManifestSchema.players#

Field Type Required Default Min / Max Pattern Rule Description
min integer yes — >= 1, <= 64 — — —
max integer yes — >= 1, <= 64 — — —

Whole-object rules:

  • players.max must be greater than or equal to players.min.

players.min

The smallest table your rules actually work at. Set it to the count below which the game stops functioning — the count where a trading game has nobody to trade with — rather than to the count you happen to have playtested most.

When min and max are equal the chip collapses from a range to an exact count ("4 players"), which is the right shape for a game that plays at one number and no other.

players.max

The largest table your rules cover — a claim about your design, not a limit on the room. Nothing stops a sixth player sitting down at a mod that says five; seats belong to the room, and this number tells a browsing player what to expect.

Set it to the count past which your game breaks rather than to the number of seats a table can hold. If it lands below min the manifest fails to parse as a whole, so a transposed pair surfaces as a publish failure rather than as a strange chip nobody notices.

modManifestSchema.dice#

Field Type Required Default Min / Max Pattern Rule Description
id string no — 1–48 chars ^[a-z0-9][a-z0-9-]*$ — —
preset "die-d4" | "die-d6" | "die-d8" | "die-d10" | "die-d12" | "die-d20" | "die-piecepack" yes — — — — —
label string no — 1–40 chars — — —
defaultCount integer no — >= 0, <= 40 — — —
model string no — 1–512 chars — — —
modelPreset "die-d4" | "die-d6" | "die-d8" | "die-d10" | "die-d12" | "die-d20" | "die-piecepack" no — — — — —
color string no — — ^#[0-9a-f]{6}$ — —
material string no — 1–128 chars — — —

dice.id

A stable key for this entry. Optional; lowercase letters, digits and hyphens, starting with a letter or digit, up to 48 characters.

Omit it and the entry is keyed by its preset, exactly as before ids existed. Give an entry an id when two entries share a face layout — a red d6 and a blue d6 are both die-d6, and without distinct ids the list is refused at parse with Each die may be declared once (give dice that share a type distinct ids).

The id is what the dice tray's counts and the dice-roll intent address, and the host records it as key on each die of the roll result. It is also what a seat template's per-seat dice overrides are keyed by. Treat it as an identifier rather than a caption: rename a die with label, not by changing its id. A player's saved counts, and every override keyed by the old id, stop applying the moment it changes. The editor's Dice panel gives every die it adds an id, and freezes an id-less entry's current key into id before you change its face layout, so that key does not move.

The table-script DiceRollSummary type does not declare key, so a script cannot read it type-safely. Tell dice apart in a script by preset and sides.

JSON
"dice": [
  { "id": "red-d6", "preset": "die-d6", "color": "#b3261e", "label": "Red die" },
  { "id": "blue-d6", "preset": "die-d6", "color": "#1e4bb3", "label": "Blue die" }
]

dice.preset

Which die this entry is, named as a standard preset id: its face layout. Required, and the only required field of an entry.

The seven that exist are die-d4, die-d6, die-d8, die-d10, die-d12, die-d20 and die-piecepack. The enum is derived from the standard preset table's dice family rather than hand-listed, so it is exactly the dice the app ships — an id outside it is refused at parse.

die-piecepack is a d6 in a wooden coat: it is a sixth-sided die with different art, and it is deliberately not part of the default set, because a picker offering two visually different six-siders reads as a bug. You can still declare it explicitly, which is the point of it being in the enum.

A manifest can change a die's look, not its faces. Face values are read off a per-preset table of authored face normals. A die with no entry in that table always settles unreadable, a roll that can never report a number. So model, modelPreset, color and material change what the die looks like, while the face count and the numbers always come from this preset. A custom model must be authored face-for-face in the stock die's orientation for its numbers to read correctly.

The face count comes from the preset too, so a die-d20 entry always rolls twenty faces; there is no field that changes it.

dice.label

What the dice tray prints for this die, when the preset's own name is not the word your game uses.

Optional, 1–40 characters, trimmed. Omit it and the die shows its standard name (d6, d20). Set it and your rules' vocabulary reaches the table: Combat die, Fate die, Hit die.

This is a display override. It does not change which preset is rolled, how many faces it has, or what the dice notation reads: notation groups by face count, so a renamed d6 is still d6. A roll summary reports preset and sides, never this string.

It does reach one other place. A die rolled from an entry whose label differs from the preset's own name gets that label as its displayName, so the rolled die is called Combat die in the Hierarchy and anywhere else a human-readable name is shown. Its label (the slug) and its id are unaffected. A script should not match on the display name, because an author can change it at any time. Match on preset and sides instead.

Keep it short. It sits under a thumbnail on a tile in the dice tray, so a long name is truncated rather than wrapped. The full name is still shown on hover. 40 characters is already generous for the label of one die.

dice.defaultCount

How many of this die the picker starts at. Optional; omit it and the row starts at zero, like every undeclared die.

An integer from 0 to 40. 0 is a legitimate value and means the same as omitting the field — the die is offered but not preselected.

Set it for the roll your game makes constantly, so the common case is one click instead of one click per die. A Yahtzee-style game declares die-d6 with defaultCount: 5; a game that rolls a single d20 declares defaultCount: 1. Leave it off for dice a player reaches for occasionally: a preselected die they did not want is worse than a stepper they have to touch, because it rolls before they notice.

The cap is 40, and a whole roll is capped at 40 dice as well. Every rolled die is a real physics body and a real entity in the snapshot — that is what makes rolled dice keepable rather than an animation — so a roll costs what spawning that many entities costs. Declaring large default counts across several dice produces a picker whose starting state is already at the ceiling.

dice.model

A project model to roll instead of the stock die — a repo-relative path such as models/rune-d20.glb, the same kind of path every other model object uses. Optional.

The model is only the die's look. Its face count, the numbers it reports and the face table the table reads them from all still come from the entry's preset. That only works if the model is authored face-for-face in the stock die's orientation: the table reads the face whose normal points up and looks its number up in the preset's table, so a model whose "20" faces where the stock die's "7" does will report 7.

Two further behaviours to expect:

  • The model rolls at its own authored size (world units are feet), like any project model placed on the table, not at the stock die's scale.
  • A custom d6 collides as a box fitted to the model; any other face count collides as a convex hull built from the model's mesh, so a custom d20 tumbles like a d20 rather than a cube.

Set at most one of model and modelPreset. color and material apply on top of either.

dice.modelPreset

Roll this entry using another built-in die's model, for example die-piecepack's wooden d6 art on a die-d6 entry. Optional; ignored when model is set.

As with model, this changes only the look. The face count and the numbers come from preset. The collider follows the model that is actually drawn, because a collider that disagrees with the visible mesh makes a die land on a face it does not have. Pairing a model with a different face count (a d20 model on a d6 entry) is therefore allowed but rarely useful: it tumbles like a d20 and reports d6 numbers.

Must name one of the seven die presets; the schema refuses anything else, and the editor refuses a non-die preset dropped on a die slot. To give a die a non-die shape, use a project model authored face-for-face like the stock die.

dice.color

Tint this die, as #rrggbb. Optional.

On a stock die model (the preset's own, or a modelPreset) the body is recoloured and the pips or numbers switch to dark or white ink automatically, so they stay readable on any body colour. On a project model the colour is applied as the object's tint instead. The model's own texture is not recoloured.

The colour is stored on the rolled die itself, so every player sees the same colour without knowing which tray entry the die came from.

Use it for a game-wide die that must stand out, such as a red "wild" d6 next to the white ones, and give the two entries distinct ids. For "the same dice, one colour per player", do not declare one entry per colour here. That would let every player roll every colour. Declare the dice once on the seat template and use its Colour dice per seat button, which tints each seat's copy in that seat's colour. See Dice owned by the seat template.

dice.material

Put one scene material on every material slot of this die's model, by material id (builtin:… or a project material). Optional, up to 128 characters.

It is the all-slots shorthand: any per-slot assignment the model would otherwise carry is cleared, so a single material covers the whole die. It applies after model or modelPreset and, like color, rides on the rolled die itself so every player sees it.

modManifestSchema.plugins#

Field Type Required Default Min / Max Pattern Rule Description
id string yes — 3–96 chars ^[a-z0-9][a-z0-9._-]*[a-z0-9]$ — —
functions string[] yes — <= 24 items; each 1–64 chars ^[a-zA-Z][a-zA-Z0-9_]*$ — —

plugins.id

The plugin's id, in reverse-DNS form (org.example.cards) — the same grammar a mod id uses.

It must match the first argument of every api.callPlugin(...) call in your script, character for character. The scanner compares literals; it does not resolve aliases.

plugins.functions

The names of that plugin's exposed functions this mod calls. May be empty ("functions": []): that is a resource-only use — the mod uses files the plugin declares under resources and calls nothing. An empty list declares no (plugin, function) pair, does not require the plugin-call capability, and grants no call: an api.callPlugin naming that plugin is rejected at publish as undeclared-plugin-call and resolves not-found at runtime.

Each name must match the second argument of the corresponding api.callPlugin(...) call. List only what you actually call: this array is the reviewable statement of your mod's external reach, and padding it with functions you might use later widens that statement for no benefit.

modManifestSchema.dependencies#

Field Type Required Default Min / Max Pattern Rule Description
packId string yes — 1–96 chars — — —
version string yes — 1–40 chars — Pin an exact version, for example 1.0.0. Ranges (^, ~, x, >=) are not supported: a range makes a table non-reproducible between two peers who resolved it at different times. —
commitSha string no — — ^[a-f0-9]{40}$ — —

dependencies.packId

The id of the published pack you depend on — the same id that pack's own manifest declares.

It names the pack, not a repo path and not a type. The registry resolves it to the repo and the commit, and it knows what kind of pack it is, so there is nothing to restate here that could disagree.

dependencies.version

The exact version label to pin, for example 1.4.0. Same shape as your own version.

A published label is immutable: once 1.4.0 exists it always means the same commit, so this one string is enough to make everyone at the table load the same bytes. Ranges are rejected — see dependencies for why.

When a newer version appears you are told, and shown what changing the pin would move, but nothing resolves to it until you edit this field.

dependencies.commitSha

The 40-character Git commit the pinned version resolved to, recorded alongside the label.

Optional, and normally written for you at publish rather than typed. The label alone is already immutable, so this is belt and braces: it keeps the pin reproducible even if a tag is later moved in the upstream repo, and it is what lets a peer verify it fetched the same tree everyone else did.

modManifestSchema.setupOptions#

Field Type Required Default Min / Max Pattern Rule Description
key string yes — 1–64 chars ^[a-z][a-z0-9_]*$ — —
label string yes — 1–80 chars — — —
control "text" | "number" | "toggle" | "select" yes — — — — —
help string no — <= 240 chars — — —
default string | number | boolean yes — — — — —
options pluginSettingOptionSchema[] no — <= 32 items — — —
min number no — — — — —
max number no — — — — —
step number no — > 0 — — —
maxLength integer no — >= 1, <= 2000 — — —

setupOptions.key

The option's stable identifier, and the property name an answer will be filed under.

Lowercase snake_case, starting with a letter, 1 to 64 characters. The pattern is not house style — resolved values are assembled into a record by assignment, so a key that names something on the JavaScript object model has to be unrepresentable rather than merely discouraged. __proto__ cannot match the pattern at all; constructor and prototype can, and are refused by name. The resolved record is additionally built on a null prototype, so neither guard is carrying the weight alone.

Two options may not share a key. A repeated key would leave the chosen value ambiguous, so it is a refusal rather than a last-one-wins. Both rules are enforced when the manifest is parsed.

setupOptions.label

The caption a host will read beside the control.

Plain text, 1 to 80 characters. It is specified to render as a React child, which escapes it — no markdown pass and no link, deliberately: a lobby control is not a place for an author to put a URL in front of players who have not started the game yet. The cap is enforced at parse time, and the lobby's Game options form draws the label exactly this way.

It never reaches your script. A script receives values, not the form they were chosen in.

setupOptions.control

Which form element this option is answered with: text, number, toggle or select.

The same closed four-value vocabulary a plugin declares its settings with, shared as one definition rather than copied (settingControls.ts). Each maps to exactly one JSON type — toggle to a boolean, number to a finite number, text and select to a string — and that mapping is what every other check on this page is written against.

The modifiers are scoped to their control and are refused at parse time, not ignored, on the wrong one: options belongs to a select, min/max/step to a number, maxLength to text. A min on a toggle is an author who believes something is happening that is not.

setupOptions.help

One line of explanation to sit under the control.

Optional, capped at 240 characters, and prose only — like label it is specified to render as text, never as markup. Use it for the sentence that stops a host guessing what a setting does. Like label, it never reaches your script.

setupOptions.default

The value the control starts on, and the value a script gets for an option nobody answered.

Required, which is the one place this schema deliberately parts company with a plugin's settings. A form has to render every control with a value the moment it opens, and a mod must never observe undefined for something it declared. That makes resolution total: every declared option is present in the record resolveModSetupOptionValues builds, so a script will need no fallback of its own.

The default is validated against its own control and its own bounds when the manifest is parsed. A select default must be one of the declared choice values, a number default must sit inside min/max, and a text default must fit maxLength — a control that cannot render its own default is not a control. A string default is itself capped at 2000 characters, because an uncapped one is a megabyte of manifest riding into every render of the form.

setupOptions.options

The choices a select offers. Required for select, refused on anything else.

Literal data, capped at 32 entries — a choice list is written in the manifest, never fetched. Two choices may not share a value, and the option's default must be one of them. All three rules are enforced when the manifest is parsed.

The cap is the plugin one reused rather than re-chosen: an author moving a control between the two surfaces should not discover a different ceiling.

setupOptions.min

The lowest value a number option accepts. Optional, and number only.

At parse time it does two jobs: the option's own default must not fall below it, and a min above max is a refusal. Beyond that it is the bound the shared value check (validateModSetupOptionValues) applies to a host's answer wherever that answer is stored, and the reason an out-of-bounds stored value resolves to the default instead of reaching a script.

setupOptions.max

The highest value a number option accepts. Optional, and number only.

Enforced exactly as min is, at the same two points, and the option's own default must satisfy both.

setupOptions.step

The increment a number control moves in. Optional, number only, and must be positive — a step of zero or below does not describe an increment.

It exists here and not on a plugin setting because of who touches it: a lobby number is nudged by a player mid-conversation rather than typed once by an author in an editor, and a piece count that can land on 7.5 is a bug a script then has to defend against. Note that it constrains the control, not the value: nothing rejects a stored number for being off-step.

setupOptions.maxLength

The longest string a text option accepts. An integer from 1 to 2000, optional, and text only.

The option's own default must fit it, checked at parse time. It is also the bound the shared value check applies to a host's answer; an over-long stored value resolves to the default. Leave it out and the schema's own 2000-character ceiling on a text value still applies.

modManifestSchema.lobbyRequirements#

Field Type Required Default Min / Max Pattern Rule Description
id string yes — 1–64 chars ^[a-z][a-z0-9_]*$ — —
kind "deck" yes — — — — —
label string yes — 1–80 chars — — —
help string no — <= 240 chars — — —
appliesTo "players" | "owner" no "players" — — — —
required boolean no true — — — —
formatId string no — <= 64 chars — — —
minCards integer no — >= 0, <= 100000 — — —
maxCards integer no — >= 1, <= 100000 — — —
deckSources ("mine" | "community" | "database" | "game")[] no ["mine"] 1–4 items — — —
deckDatabase modLobbyDeckDatabaseSchema no — — — — —
deckIcon modLobbyDeckIconSchema no — — — 1 further cross-field rule (message built at validation time). —
distinctBy lobbyDistinctBySchema no — — — 1 further cross-field rule (message built at validation time). —

lobbyRequirements.id

The key each player's answer is filed under.

Lowercase snake_case, starting with a letter. Two requirements may not share one — answers are stored in a record keyed by this, so a duplicate would mean each overwriting the other, and the manifest is refused rather than letting that happen quietly.

The format is the same one setupOptions.key uses, for the same reason: answers are assembled by assignment, so an id that could name something on the object model has to be unrepresentable rather than merely discouraged. __proto__ cannot match the pattern at all, and constructor and prototype are refused by name.

Changing an id in a later version orphans every answer filed under the old one. Those are dropped rather than migrated — they belong to a question nobody is asking any more.

lobbyRequirements.kind

What is being asked for.

deck is the only kind today. It resolves against your game's own deck pool — the decks that player saved for this pack — and nothing you write here can widen that: the pool comes from the room's provider mod, not from the manifest.

It is an enum rather than a boolean so that "pick a faction", "pick a scenario" or "pick a warband" can join it without replacing anything. The lobby roster, the wire format and the editor form are all keyed by kind.

lobbyRequirements.label

The caption a player sees above the picker, and the name they are chased by.

Plain text. It is rendered as a React child and never as markup — not because escaping catches it, but because nothing in the lobby ever asks this string for markup.

It appears in three places, so write it as a thing, not an instruction: above the control ("Your deck"), on every member's roster row when they have not answered ("No your deck yet"), and inside the sentence that tells the owner why Start is greyed out ("sam (Your deck) still has to choose before this game can start").

lobbyRequirements.help

One line under the control, for the rule a label cannot carry.

Prose only, same rule as the label: it is rendered as text, never as markup.

This is the place for what makes a legal answer in your game — "60 cards, one side, no more than four of any card" — rather than for what the control does. The bounds you declare below are already shown by the picker itself.

lobbyRequirements.appliesTo

Which seated members are asked.

players (the default) asks everyone taking a seat. owner asks only the person who owns the room — the right shape for a scenario or a board that is chosen once for the table rather than brought by each person.

A spectator is never asked anything, under either value, including an owner who is spectating. They are not playing, so they have nothing to bring, and a lobby of spectators can always start.

lobbyRequirements.required

Whether an unanswered requirement blocks Start.

true, the default, means the room owner is refused (lobby-requirements-unmet) until every player it applies to has answered — the honest reading for a game with no legal opening position without one.

false still shows the picker, still puts the chosen deck on the table, and still lists the answer on the roster. It just does not stop anybody. That is what a teaching game or a demo wants, and it means offering the affordance and forcing it are separate decisions.

lobbyRequirements.formatId

deck only — the format id from your data/cardSchema.json that an answer must carry.

Leave it out to accept any deck built for your game.

A deck with a different format is shown in the picker greyed out with the reason, rather than missing from it: a player who cannot find the deck they built has no way to learn why, and hunting for an absent row is a worse experience than being told. The same check runs server-side when the answer is filed, so the disabled row is disclosure and the refusal is the rule.

lobbyRequirements.minCards

deck only — the fewest cards an answer may hold, inclusive.

Omit it for no lower bound. Declaring one bigger than maxCards is refused at parse: the smallest legal deck cannot be bigger than the largest one.

Like formatId, a deck outside the bounds is offered greyed out with the reason ("That deck holds 40 cards; at least 60 are needed") rather than hidden.

⚠ This counts what the deck row records, which is every card in every partition. If your game's minimum is about the main list alone, say so in help — the bound cannot express it.

lobbyRequirements.maxCards

deck only — the most cards an answer may hold, inclusive.

Omit it for no upper bound. See minCards for how a deck outside the bounds is presented and for what exactly is counted.

lobbyRequirements.deckSources

deck only — which pools the lobby picker offers, in tab order.

Defaults to ["mine"]: the player's own decks for your game and nothing else, which is exactly the picker every pack published before this field existed. Widening it is your decision, not ours — a game whose decks are meant to be built rather than borrowed keeps the narrow picker by saying nothing.

Value What it lists
mine The player's own decks for this game, at any visibility. Owner-scoped server-side.
community Every deck other players made public for this game.
database Public lists on an outside provider — requires deckDatabase.
game The decks your game ships in its own gameDecks file, shown as the Game decks tab and grouped by level. The same list for every member; picking one imports nothing. Requires gameDecks.

⚠ A wider pool is never a wider read. mine is scoped to the caller inside the query and community is a bare "public only" predicate, so no declaration here can reach a private deck belonging to somebody else. This widens what is offered, never what is readable. game reads only public pack data.

game is also the only pool a bot's deck can come from — a bot has no library — so the room's owner can hand bots a deck only when one of your deck requirements lists it.

database without a deckDatabase is refused at publish, and so is a deckDatabase without database — either one alone is an author who believes something is happening that is not.

game without a gameDecks file fails to parse: the tab would have nothing in it.

lobbyRequirements.deckDatabase

deck only — the outside provider behind the database deck source.

Required when deckSources includes database, and refused when it does not.

JSON
"deckSources": ["mine", "community", "database"],
"deckDatabase": {
  "pluginId": "community.swtcg-deckdb",
  "listFunction": "publicDecks",
  "label": "swtcg-deckdb.com"
}

🔴 A name, never a request. The same contract every plugin call follows: requirement → plugin id + function name → plugin manifest → endpoint → origin + path template, all declared data that a reviewer can follow without running anything. The fetch happens server-side under that plugin's own origin allowlist, quota and circuit breaker. There is no URL here.

⚠ Both names must already be in your plugins block. A requirement is not a second, looser door onto a plugin you have not declared; publish refuses one that is missing, naming it.

Picking a result imports it. The platform asks the plugin's declared deckImport block for that list, joins it against your game's own card catalogue in the player's browser, and saves the result as a private deck of theirs — so the answer on the roster is an ordinary deck reference, and the player keeps the deck afterwards. A plugin that declares no deckImport cannot be a database source.

lobbyRequirements.deckIcon

deck only — a small picture beside each deck in the lobby: in the picker list, on the player's own "What you're bringing" row, and on their chip in the roster. The deck's name is always shown as text next to it; the picture is decoration.

JSON
"deckIcon": {
  "image": "ui/side-neutral.png",
  "field": "side",
  "map": {
    "L": "ui/side-light.png",
    "D": "ui/side-dark.png",
    "N": "ui/side-neutral.png",
    "Y": "ui/side-vong.png"
  }
}
Key What it does
image The icon a deck gets when nothing more specific applies. Optional.
field The key on a deck row that picks the icon — side on a deck-database row, say. Needs map.
map Value → image. At most 32 entries; each value is matched exactly (case-sensitive, trimmed), up to 64 characters. Needs field.

Declare at least one of image or map. A deck whose value is unknown, or not in the map, falls back to image — unless image is also one of the map's pictures. In the example above the default is the Neutral symbol, so drawing it for a deck nobody knows the side of would claim the deck is Neutral; such a deck shows no icon instead. A default that is no value's picture (a generic deck back) is drawn for every unknown deck. With no image, an unknown deck simply has no icon.

Making image one of the map's pictures also says something: that value is your "no particular side" value. A saved deck's side is worked out from its cards (below), and cards carrying that value — like distinctBy.except values — do not decide it.

🔴 Every image that can ever be drawn is one you declared. Each path is a repo-relative PNG, JPEG or WebP file of your pack — never a URL, never .., never SVG — and publish refuses one that is not listed in assets (lobby-deck-icon-undeclared). A deck row from an outside provider cannot name an image: it can only carry a value, and a value reaches the screen only by being one of your map keys. A provider row that says "side": "https://…" is just an unmapped value.

Where the per-deck value comes from.

  • Deck-database rows (database source): the provider row's own field key, read when the list loads. Picking one carries that value onto the roster with the imported deck.
  • Game decks (game): the deck's own side, formatId, pool or level in your gameDecks file, whichever field names. Any other field gives a game deck no value.
  • Saved decks (mine, community): with "field": "formatId", the deck's format id. With any other field, the value is worked out from the deck's cards: the lobby reads the chooser's decklist against your card catalogue and looks up each card's field value through the map. If the cards that commit to a value all agree on one, that is the deck's value — a deck of Light Side and Neutral cards is Light Side. If every card carries the same neutral value (a distinctBy.except value, or the value whose picture is image), the deck is that value. Anything else — two committing values, no card with the field, a catalogue that cannot be read — is unknown: no claimed icon, and never refused by distinctBy. Your cards need the field key in their data for this to work.

What rides the lobby roster is the value ("L"), never a path. Every member's lobby looks it up in your map itself, and the server drops a value your map does not list before anyone else sees it.

lobbyRequirements.distinctBy

deck only — no two decks at the table may share a value, for a game played side against side.

Star Wars TCG is the case it was built for: a game is a Light Side deck against a Dark Side deck, or a Neutral deck against either — never Light against Light. Declare which values may repeat, and what each value is called when a pairing is refused:

JSON
"deckIcon": {
  "field": "side",
  "map": { "L": "ui/side-light.png", "D": "ui/side-dark.png", "N": "ui/side-neutral.png" }
},
"distinctBy": {
  "except": ["N"],
  "labels": { "L": "Light Side", "D": "Dark Side" }
}

The value compared is the deck's deckIcon value — the one per-deck value the lobby already carries for every choice and already checks against your declared words. So distinctBy needs a deckIcon with a field and a map; a requirement without one fails to parse. {} is a valid rule: every value must differ.

Who takes part: every seated member's choice and every bot's deck. Spectators hold no deck that plays.

Where it is checked — one shared rule, three places, one verdict:

  1. The picker greys out a deck that would clash with one somebody else already holds, and says why — in every tab, including deck-database rows, whose value is known before the import.
  2. A bot's deck that would clash is refused when the owner chooses it (bot-deck-pairing).
  3. Start is refused with lobby-pairing-conflict while two decks clash, and the Start control says which.

⚠ An unknown value never clashes. A saved deck's side is worked out from its cards (see deckIcon); a deck whose cards do not settle it — mixed sides, no card carrying the field — is unknown, and the lobby lets it through. Declaring except matters here too: a Light Side deck usually holds Neutral cards, and only a value listed in except (or pictured by deckIcon.image) is ignored when the side is worked out. The value is worked out by the choosing player's own client; the server keeps only values your map lists and cannot re-check the cards. Your game's script is the backstop: check the pairing at the table when it matters to your rules.

modManifestSchema.variants#

Field Type Required Default Min / Max Pattern Rule Description
id string yes — 1–40 chars ^[a-z0-9]+(?:-[a-z0-9]+)*$ This id is reserved and cannot name a variant. —
name string yes — 1–60 chars — — —
description string no — <= 240 chars — — —
players object no — — — players.max must be greater than or equal to players.min. —
rulesEnforced boolean no — — — — —
ranking modVariantRankingSchema no — — — — —

variants.id

The variant's stable identifier: what the room record stores as the owner's choice, and the key your setup.json files this variant's differences under.

Lowercase letters, digits and single interior dashes, 1 to 40 characters — 9x9, six-players, by-hand. The pattern is not house style. Scene differences are stored in a record keyed by this id and assembled by assignment, so an id that names a slot on the JavaScript object model has to be unrepresentable rather than merely discouraged: __proto__ cannot match the pattern at all, and constructor and prototype, which can, are refused by name with "This id is reserved and cannot name a variant."

Two variants may not share an id. The failure names the id and nothing else you wrote.

Treat it as permanent once published. The id is what links the manifest's entry to the scene's differences and to every lobby that has already chosen it. Renaming a variant in the editor changes its name and leaves the id alone for exactly this reason — the id is derived from the name once, when the variant is created (9×9 becomes 9x9), and never follows it afterwards. A room that stored an id your game no longer declares is not broken by it: it opens on the first declared variant instead.

variants.name

What the lobby's Variant dropdown shows for this entry, and what the lobby's header tells every member they are about to play.

Plain text, 1 to 60 characters after trimming. It is rendered as a React child, which escapes it — no markdown pass and no link. Name the thing that differs, not the game: in a dropdown under the game's own title, 9×9 and 19×19 read better than Go (small board).

It never reaches a script, and it is not an identifier: nothing resolves a variant by name, and two variants are told apart by id. Renaming is therefore always safe.

variants.description

One line of prose shown under the lobby's dropdown while this variant is selected, and under the variant's name in the lobby header that every member sees.

Optional, at most 240 characters after trimming, plain text only — rendered as a React child, never as markup. Use it for what the name cannot carry: "Quick game, about 20 minutes", or "No rules are enforced — move the stones yourself". Leave it out when the name already says everything; an absent description draws nothing.

variants.players

This variant's player range, when it differs from the game's own players. Absent means "the game's range".

It exists for the case that motivates variants in the first place: a larger table seating more people. A ten-seat variant of a six-seat game declares { "min": 2, "max": 10 } here and leaves the game's headline range alone.

It bounds the seat cap, with the same rule the server enforces. While this variant is selected, the lobby's seat-cap control accepts only a number inside this range, and the note beside it reads "This variant seats 2–10 players." The server validates the same write against the same range, so the control and the refusal are one rule evaluated twice. Switching to a variant that cannot seat the cap already set clears the cap and says so — it is never clamped silently, because a cap of 8 chosen for the ten-seat variant means nothing on the six-seat one.

The range is also printed beside the variant's name in the lobby header, and under the dropdown as "Seats 2–10 players." The platform seats at most ten players whatever a manifest says, so a max above ten is accepted by the schema and treated as ten.

max must be greater than or equal to min, or the manifest fails to parse with "players.max must be greater than or equal to players.min."

variants.rulesEnforced

Whether this variant is Fully scripted: its scene script enforces the rules and reports the result with match.end. Absent or false is an ordinary variant.

Only a fully scripted variant may carry a ranking block, and so only a fully scripted variant can be ranked. The lobby shows a Fully scripted badge beside it.

When the match ends, the table offers every player Return to lobby or Exit. Everyone who returns lands in the same new lobby, set up as this one was and owned by whoever was the table's host. For its first 30 seconds only that table's players can join it.

It does not decide which scripts run. Script attachments are scene data: each variant attaches its own scene scripts (sceneScriptIds in its differences) and entity scripts, and the entry script runs in every variant. An ordinary variant may run scripts; it simply does not promise that they referee the game. This field replaces the removed scripts flag, and a manifest that still carries scripts is refused with variant-scripts-removed.

The editor writes it from the Fully scripted switch in Mod ▸ Variants…. Switching it on also adds a ranking block with every field at its default; switching it off removes both.

variants.ranking

Ranked-play settings for a fully scripted variant. Every field is optional and has a system default, so "ranking": {} is a complete, ranked-by-default configuration.

JSON
{
  "id": "standard",
  "name": "Standard",
  "rulesEnforced": true,
  "ranking": { "placementGames": 5, "draws": true }
}

A variant with this block (and enabled not false) shows Ranked available in the lobby, and the room's owner may switch Ranked on. What a ranked match is, what it guarantees and how Scores and Player Trust work is on Ranked games, Rankings and Player Trust.

Publishing checks the block in two places:

  • When the manifest is read (ranked-variant-bad-config): ranking without rulesEnforced: true; a field out of range or an unknown key; a variant that can start with one player unless bots are ranked and the game declares bots; two variants on one ladder that rank different sides or seat different player ranges.
  • With the scene in hand: a variant whose attached scripts never call match.end( (ranked-variant-no-match-end), and sides: "teams" (ranked-variant-teams-undeclared).

The system's own numbers are not configurable here: everyone starts at a Score of 1500, bots included, and the trust rules, caps and timeouts are the same for every game.

modManifestSchema.aiModels#

Field Type Required Default Min / Max Pattern Rule Description
id string yes — 1–40 chars ^[a-z][a-z0-9-]*$ — —
label string yes — 1–40 chars — — —
path string yes — 1–180 chars \.onnx$ — —
format "onnx" yes — — — — —
sizeBytes integer yes — >= 1, <= 67108864 — — —
sha256 string yes — — ^[a-f0-9]{64}$ — —
inputs modAiTensorSchema[] yes — 1–8 items — — —
outputs modAiTensorSchema[] <br>same shape as aiModels.inputs yes — 1–8 items — — —
minTier "cpu-basic" | "cpu-fast" | "gpu" yes — — — — —
opset integer no — >= 11, <= 21 — — —
difficulties modAiModelDifficultySchema[] no — <= 8 items — — —
description string no — <= 200 chars — — —

aiModels.id

The model's id: lowercase letters, digits and hyphens, starting with a letter, at most 40 characters. Unique among this mod's models. It is what bots[].modelId, ai.evaluate, ai.mcts and api.ai.evaluate name.

Changing it breaks every bot and script that names the old id; re-importing a file under an existing id replaces that model in place instead.

aiModels.label

The model's display name, wherever the game lists it. Plain text, 1–40 characters. Players rarely see it — they see the bot's label — so it is mostly for you.

aiModels.path

The model file's repo-relative path. Must end in .onnx and must also appear in assets, spelled exactly the same (GitHub paths are case-sensitive). Two models may not share a file. The editor's import writes new models to ai/<id>.onnx.

A path that is not .onnx — .pt, .pth, .h5, .safetensors, .tflite, .pb, .ckpt, .pkl, .bin — refuses the whole registration with a 400 mod-scan-failed naming ai-model-format. Export your model to ONNX and declare that file.

aiModels.format

Always "onnx", the one format DiceyTable loads. Required so that the declaration says what it is; the file's extension and the scanner's parse are what actually decide it.

aiModels.sizeBytes

The model file's exact size in bytes — required, unlike on an ordinary asset. 1 byte to 64 MiB.

The scanner, the editor and the host all compare the file against it before doing anything else; a file of a different size is ai-model-sha-mismatch (it is not the file this entry describes).

aiModels.sha256

The model file's SHA-256, as 64 hexadecimal characters — required. The scanner hashes the file it fetched at the pinned commit, and the host hashes the file it downloads before creating a session; a mismatch at either point is ai-model-sha-mismatch and the model is not run.

Never type it by hand. The editor's import fills it in, and diceytable-bot-trainer model check --print-entry prints a ready-to-paste entry. Re-import whenever the file changes.

aiModels.inputs

The model's inputs, 1–8 of them, each with the exact name, shape and dtype the ONNX graph declares. The scanner compares the two and refuses any difference (ai-model-io-mismatch), and the host checks every ai.evaluate call against this list — it is the contract your script's arrays are measured against.

A model searched with ai.mcts needs exactly one float32 input of shape [-1, planes, height, width], matching the kernel's encoding.

aiModels.outputs

The model's outputs, 1–8, described like inputs. Every output must be float32.

For ai.mcts a model needs a policy output with one value per policy slot and a value output with one value, both batched. Name them policy and value; the search matches by those names first and only falls back to matching by size.

aiModels.minTier

The weakest host device a table using this model should start on: "cpu-basic", "cpu-fast" or "gpu" (there is no "none" — a model that needs no hardware is not a model).

It gates hosting, not joining. The lobby refuses to Start a room seating an AI bot whose model the owner's device is below (bot-tier-unmet); when the host changes, the server prefers a peer that meets it, and a promoted host that does not pauses the bot. Anybody can join and play against it.

What to declare, from the size bands the editor's import uses: up to about 2 MiB (a Reversi-class network) → cpu-basic; about 2–12 MiB → cpu-fast; above about 12 MiB → gpu. The import measures your own device and suggests a tier, and warns when you pick one below its estimate. Game bots: hardware tiers has the measured costs.

aiModels.opset

The ONNX operator-set version the model imports, 11 to 21. Optional; when present it must match the file, or the model is refused as ai-model-opset. The editor's import fills it in from the file.

aiModels.difficulties

Named strength presets for this model, at most 8: an id, a label, and optionally simsPerMove, temperature and numeric params.

Be clear about what reads them. A bot playing at a difficulty with the same id is handed this preset in its turn as ctx.difficulty — simsPerMove, temperature and params — and your script passes them on (ai.mcts uses only what you give it). The platform itself applies exactly one thing from here: params.turnBudgetMs, the bot's per-turn time budget. The import suggests Easy 16, Normal 64, Hard 256 simulations; the training page writes its own. Give your bot's difficulties the same ids as its model's so the two line up.

Ids must be unique within the model.

aiModels.description

One optional line about the model, at most 200 characters. For your own records and the editor; players are shown the bot's description, not the model's.

modManifestSchema.bots#

Field Type Required Default Min / Max Pattern Rule Description
id string yes — 1–40 chars ^[a-z][a-z0-9-]*$ — —
label string yes — 1–40 chars — — —
kind "scripted" | "ai" yes — — — — —
modelId string no — 1–40 chars ^[a-z][a-z0-9-]*$ — —
fallbackBotId string no — 1–40 chars ^[a-z][a-z0-9-]*$ — —
handler string yes — 1–40 chars ^[a-z][a-z0-9-]*$ — —
difficulties modBotDifficultySchema[] no — <= 8 items — — —
defaultDifficulty string no — 1–40 chars ^[a-z][a-z0-9-]*$ — —
seats object no — — — — —
description string no — <= 200 chars — — —

bots.id

The bot's id: lowercase letters, digits and hyphens, starting with a letter, at most 40 characters, unique among this game's bots. A room remembers a seated bot by it (across saves, reloads and host migrations), an AI bot's fallbackBotId names it, and scripts see it as botId. Renaming it orphans bots already seated at saved tables.

bots.label

The bot's name in the lobby's Add bot list, the seat list and the table's Bots panel. Plain text, 1–40 characters.

bots.kind

"scripted" (script code only) or "ai" (its script also evaluates one of this game's aiModels). The kind is what puts a hardware requirement on a table: a scripted bot runs on any host, an AI bot needs the host to meet its model's minTier. It also decides which listing tag the game earns (bots-scripted / bots-ai).

bots.modelId

For an "ai" bot — and required there — the id of the aiModels entry it evaluates: its default model. A scripted bot may not have one. A difficulty may name its own model instead (difficulties[].modelId); this one plays every difficulty that does not, and a bot with no difficulties. The model a difficulty plays with decides the bot's hardware requirement at that difficulty, which model the host downloads and loads ahead of the bot's first turn, and ctx.modelId.

It does not force your script to use that model: the script chooses what to evaluate. Keep the two in step.

bots.fallbackBotId

For an "ai" bot: the id of one of this game's scripted bots that may take its seat when the table's host changes to a device that cannot run the model.

When that happens the AI bot is paused and the new host is asked "You are now the host": keep it paused (its turns are skipped; a person can take the seat), swap it for this fallback in the same seat and at the matching difficulty, or end the table. Without a fallback only the first and last are offered. It must name a scripted bot of this game, or the manifest is refused.

bots.handler

The id your scene script passes to bots.register({ id: "<handler>", onTurn }): lowercase letters, digits and hyphens, at most 40 characters. Each bot needs its own handler.

Publishing reads the handler ids out of every scene script's compiled body (base scripts — not a variant's changes) and refuses a bot whose handler no script registers (bot-handler-missing). Only a plain string literal written inside the call counts: bots.register({ id: "greedy", … }). A constant, a template with ${…}, a registration object built elsewhere, or a handler registered by a mod script (which has no bots) is not seen.

bots.difficulties

Named strengths players can pick for this bot, at most 8: an id your script reads as ctx.difficultyId, a label players see, and an optional one-line description. The bot plays at the room's choice, else defaultDifficulty, else the first in this list.

What a difficulty does is entirely your script's: more simulations, deeper search, less randomness. Ids must be unique within the bot.

On an "ai" bot a difficulty may also name its own modelId — a separate network per strength. The bot's own modelId plays every difficulty that does not.

bots.defaultDifficulty

The difficulty a newly added bot starts on — the id of one of this bot's difficulties. Optional; without it the first difficulty is the default. Naming a difficulty the bot does not declare fails the manifest check.

bots.seats

How many of this bot one table may seat: max, optional, 1–9. Without it the only limit is the game's player count (bots count toward it) and the table's nine-bot ceiling; with max: 1 the lobby offers this bot at most once. There is no minimum: the room's owner decides how many bots to seat, and a manifest naming seats.min is refused.

bots.description

One optional line about the bot, at most 200 characters, shown where it is offered — the lobby's Add bot list and the game page's Bots section.

modManifestSchema.credits#

Field Type Required Default Min / Max Pattern Rule Description
id string yes — 1–64 chars — — —
paths string[] yes — 1–2000 items; each 1–300 chars — — —
origin "own-work" | "third-party" | "disclaimed" yes — — — — —
title string no — <= 160 chars — — —
creator string no — <= 160 chars — — —
creatorUrl string no — <= 500 chars — Use a full http(s):// link. —
sourceUrl string no — <= 500 chars — Use a full http(s):// link. —
licenseName string no — <= 120 chars — — —
licenseUrl string no — <= 500 chars — Use a full http(s):// link. —
notes string no — <= 1000 chars — — —
recordedAt string yes — — ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ — —
attestation creditAttestationSchema no — — — — —
aiAttestation creditAiAttestationSchema no — — — — —
source assetSourceRefSchema no — — — — —
locked true no — — — — —
derivedFrom assetSourceRefSchema no — — — — —

Whole-object rules:

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

credits.id

A stable id for this credit entry, minted when the record is created.

It exists so an entry survives an edit and can be pointed at — by the Credits tab, by a problems list, by anything that needs to name one record among several. The publish refusal ai-credits-unreviewed and the scanner's ai-credit-unreviewed both name the records still waiting for a review by this id. It is not meaningful to a reader otherwise, and nothing resolves it to anything outside the manifest.

credits.paths

The repo-relative files this record accounts for — textures/board.png, not /textures/board.png and never ../.

One entry covers a whole import, which is usually many files. That is deliberate: the unit of decision is the import, not the file. An author who drops in a 220-card set got it from one place under one licence, and splitting that into 220 identical records would make the Credits tab unreadable and the manifest enormous while saying nothing extra. The editor's import dialog does offer Credit files separately for a mixed drop, which produces one entry per file.

A file may appear in exactly one entry. Two records claiming the same path can disagree, and then "who made this file" has two published answers; the manifest refuses it. When you re-import a file over itself the new record takes the path off the old one, so correcting a credit is just importing again.

The paths here are the ones actually written to your repo, not the names you dropped in. Import hull.fbx and it is converted on the way in, so the record names models/hull.glb — the file that is published is the file that is credited.

credits.origin

Which of the three things this entry says: own-work, third-party or disclaimed.

There is deliberately no fourth value and no empty state. Every file that reaches a mod through the editor has passed through one of these, because the point of the mechanism is that no file enters a mod without a recorded decision.

third-party is the only one with further requirements — a creator, a link, and a licence. disclaimed is the escape hatch for when you cannot supply those, and it is priced: a signature and an acceptance of full responsibility.

credits.title

What the work is called, when it has a name of its own — "Boardgame Pack", "Dungeon Tiles Vol. 2".

Optional, and available on all three origins. It is what the Credits tab leads the line with, so a set of forty files reads as one named thing rather than as forty filenames.

credits.creator

Who made it. Required when origin is third-party, and ignored otherwise.

A name, as they would want to be credited — the person, the studio, the account you got it from. This is the field somebody searching for their own work will find, so write it the way they spell it rather than the way your file is named.

credits.creatorUrl

A link to the creator — their site, their shop, their profile.

A full http(s):// address. Either this or sourceUrl is required for a third-party credit, because a credit nobody can follow credits nobody: a name with no link cannot be verified, cannot be found by the person it names, and does not tell a reader where the work actually lives.

If you truly have no link for either, the honest record is disclaimed, not a bare name.

credits.sourceUrl

A link to where the file itself came from — the asset page, the download, the listing.

Distinct from creatorUrl: one names the person, the other names the thing. Either satisfies the third-party link requirement, and giving both is better than giving one, because the pair is what lets a reader check the licence for themselves.

credits.licenseName

The licence these files are used under, by name — "CC BY 4.0", "CC0 1.0 (Public Domain)", "Purchased / commercial licence".

Either this or licenseUrl is required for a third-party credit. The editor offers a shortlist of common licences and fills the name and URL together, because a free-text field alone produces "CC-BY", "cc by 4.0" and "creative commons attribution 4.0 international" for one licence, none of which links anywhere. Anything not on the list can still be typed.

Naming a licence is not holding one. If the licence does not permit redistribution, or requires terms you have not met, you must not publish the files — recording the name here changes nothing about that.

credits.licenseUrl

A full http(s):// link to the licence text.

Either this or licenseName satisfies the third-party requirement, and the link is the more useful half: it is what lets a reader check the terms rather than take your word for which licence you meant.

credits.notes

Anything the other fields cannot say — an order number, the email that granted permission, a caveat about which files in the set the licence covers.

Available on all three origins, including disclaimed, which is where a "bought in a bundle years ago, receipt lost" belongs. It is published like the rest of the record, so do not put anything in here you would not want read.

credits.recordedAt

When this record was made, as an ISO timestamp.

Set by the editor at the moment the import is confirmed, and again whenever an edit re-signs the record. When you sign at import, it is the same instant as attestation.acceptedAt, because the credit and the signature are one act.

A review does not move it. An AI-attested record that a person reviews later keeps the import time here, and the review time goes into attestation.acceptedAt and aiAttestation.review.reviewedAt.

credits.attestation

The signature on this record: which wording you accepted, when, and the name you signed with.

It is what turns a form field into a statement. All three origins carry one — the wording differs (an ownership warranty, an accuracy warranty, or the full indemnity) and termsVersion names which you were shown.

A record an AI agent answered for has none at first; it carries an aiAttestation instead. Reviewing that record writes this signature, alongside the agent's record rather than in place of it.

credits.aiAttestation

Set when an AI agent answered the import credit question on your behalf, instead of you. It records which agent session did it, which client it was, which version of the wording it was given, and when.

An agent working in the editor may answer the credit question for the files it imports, with any of the three origins, including the disclaimed indemnity. The record then carries this field instead of a human attestation, and that satisfies the rule that every record the author answered for must be signed. It is not a free pass:

  • Until a person reviews it, it blocks every publish. A record with aiAttestation and no review is unreviewed. The publish step refuses with 409 ai-credits-unreviewed, and the scanner refuses registration with ai-credit-unreviewed. Both name the record by its id. This holds for a re-publish of an unchanged tree too.
  • A review is a signature. Reviewing adds review and an ordinary human attestation with the same wording version, time and name. The aiAttestation stays, so the record keeps saying that an agent answered it and a person checked it.

You never write this field by hand. What you do with it is review it before you publish; see Credits an AI agent attested and Mod Details: the Credits tab.

Re-signing depends on who makes the edit. Some edits need a fresh signature: a changed origin or details, files added to the record, or a new record. Made by an agent, such an edit drops the record's human attestation and any review and stamps a new aiAttestation, so a record you signed becomes unreviewed again. Made by you in the credits editor, the same edit signs the record, and that counts as the review. Removing files or deleting a record changes nothing about who signed it, whoever does it.

Older clients and servers refuse it, on purpose. A validator from before this field existed (a stale browser tab, or a server before its deploy) strips the unknown key, finds no attestation on an unreviewed record, and refuses it outright. A reviewed record also carries the human attestation, so it passes there. That is the compatibility design: it fails closed, and nothing is migrated.

A record with review but no human attestation is refused by the schema: A reviewed AI-attested credit must also carry the reviewer's signature (attestation). Review it again from the Publish dialog.

A locked library credit does not get one: its files are not put to the credit question, and a locked record cannot be re-signed by anybody. A derivedFrom copy gets one only if an agent later makes an edit to it that needs a signature.

credits.source

The library item this record's files were copied from, when they were copied rather than imported.

It takes one of two shapes: a platform preset ({ "type": "preset", "presetKind", "presetId" }, where presetKind is model, material, texture or deck), or a plugin resource ({ "type": "plugin", "pluginId", "commitSha", "resourcePath" }). A plugin source must name a full 40-character commit sha, the same commit the plugin's resources were scanned and served at.

The platform writes source; you do not author it. It is what makes a locked record checkable: it names where the credit came from.

credits.locked

true when this record is the source's credit, carried verbatim onto files copied from a library item — a platform preset, or a plugin resource, whose credit the plugin manifest was required to carry.

A locked record is not your statement, so it cannot be edited, re-signed, merged into another record or deleted. It leaves only when its files do. For the same reason it validates without an attestation: demanding a signature would demand one nobody can give.

Three rules the schema enforces:

  • locked requires source. A lock naming no source is an unsigned claim nobody can check, and is refused.
  • locked and derivedFrom never appear together.
  • A locked record whose origin is disclaimed still needs an attestation. A disclaimer is a statement only you can make, and no library supplies one: plugin manifests refuse disclaimed resource credits, and no platform preset is disclaimed.

The exemption is record-keeping, not trust: a hand-written manifest can claim a lock it has no right to.

credits.derivedFrom

Where the work came from, on a copy that has been detached from its library source because its bytes were changed locally. Same shape as source.

A detached copy no longer receives updates, and its credit is no longer locked. It is an ordinary, editable record that still says where the files originated. Detaching does not invent a statement you never made, so the record validates without an attestation. Editing it later goes through the normal re-attestation rule like any other change.

The exception is a disclaimed origin: that record always needs an attestation, with or without derivedFrom, because only you can accept responsibility for files with no creator or licence.

Never present together with locked.

modManifestSchema.setupOptions.options#

Field Type Required Default Min / Max Pattern Rule Description
value string yes — 1–120 chars — — —
label string yes — 1–120 chars — — —

setupOptions.options.value

The string a script will receive when the host picks this choice. 1 to 120 characters.

It is the identity of the choice, so keep it stable across releases: changing a value orphans the answer already stored against the old one, and resolution then falls back to the option's default. Unique within the option.

setupOptions.options.label

What the host reads for this choice. 1 to 120 characters.

Display only — a script never sees it, so it is free to change between releases in a way value is not.

modManifestSchema.lobbyRequirements.deckDatabase#

Field Type Required Default Min / Max Pattern Rule Description
pluginId string yes — 1–120 chars — — —
listFunction string yes — 1–80 chars — — —
label string no — <= 60 chars — — —

lobbyRequirements.deckDatabase.pluginId

The registered plugin holding the deck database.

Must be a plugin your manifest already lists in plugins. Publish refuses an id that is not there, because the plugins block is meant to be the whole of your pack's external reach — readable without running the script.

lobbyRequirements.deckDatabase.listFunction

The exposedApi function that lists the provider's public decks.

Must be one of the functions named for that plugin in your plugins block; publish refuses one that is not.

It has to take no required parameters and return an array of rows carrying at least an id and a name. Rows may also carry side, format, pool, card_count, owner_username and played_by, which the picker shows when they are there and ignores when they are not — a provider returning something else is normal, not a fault.

It is called once when the tab opens, and searched in the browser. The providers this exists for publish their entire public list as one document and have no search endpoint at all; turning keystrokes into provider requests would be the wrong shape and would spend that plugin's shared daily budget on typing.

lobbyRequirements.deckDatabase.label

What the picker calls the database tab. Plain text, rendered as text.

Omit it and the tab reads "Deck database". Naming the site — "swtcg-deckdb.com" — usually reads better, because a player recognises where their lists actually live.

modManifestSchema.lobbyRequirements.deckIcon#

Field Type Required Default Min / Max Pattern Rule Description
image string no — — — 1 further cross-field rule (message built at validation time). —
field string no — 1–64 chars ^[A-Za-z_][A-Za-z0-9_]*$ That key names something on the object model. —
map Record<string, string> no — — — — —

Whole-object rules:

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

lobbyRequirements.deckIcon.image

The icon a deck gets when nothing more specific applies — including any deck whose value is unknown or not in map. One exception: when this same image is also one of the map's pictures (a Neutral symbol as the default), an unknown deck shows no icon rather than claim that value, and that value counts as your "no particular side" value when a saved deck's value is worked out from its cards. A repo-relative PNG, JPEG or WebP file of your pack, declared in assets; never a URL, .. or SVG.

JSON
"deckIcon": { "image": "ui/deck-back.webp" }

lobbyRequirements.deckIcon.field

The key on each deck row whose value picks the icon from map. A plain key such as side — letters, digits and _, never a dotted path. Requires map.

On a deck-database row it is the provider row's own key (a string or a number). On a game deck it is the deck's own side, formatId, pool or level; any other key reads nothing. A saved deck carries no provider fields, so for mine and community decks the only field that reads anything is formatId; with any other field they show the default image.

lobbyRequirements.deckIcon.map

Which image each value of field shows. At most 32 entries; keys up to 64 characters, matched exactly (case-sensitive, after trimming the row's value). Every value is a repo-relative PNG, JPEG or WebP file of your pack, declared in assets.

JSON
"deckIcon": {
  "field": "side",
  "map": { "L": "ui/side-light.png", "D": "ui/side-dark.png" }
}

🔴 This map is the only way a value becomes a picture. A provider row cannot name an image; a value your map does not list is just unmapped, and falls back to the default image (unless that image is itself one of this map's pictures) or no icon.

modManifestSchema.lobbyRequirements.distinctBy#

Field Type Required Default Min / Max Pattern Rule Description
except string[] no — <= 16 items; each 1–64 chars — — —
labels Record<string, string> no — — — — —

Whole-object rules:

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

lobbyRequirements.distinctBy.except

The values two or more decks may share — the exceptions to distinctBy. For Star Wars TCG, ["N"]: Neutral decks may face anything, including each other.

At most 16 values, each up to 64 characters and matched exactly against the deck's deckIcon value. Omit it and every value must differ. In the manifest editor this is May repeat, typed as a comma-separated list.

lobbyRequirements.distinctBy.labels

What each value is called when a pairing is refused, so a player reads "Light Side" rather than "L":

JSON
"labels": { "L": "Light Side", "D": "Dark Side" }

Optional. At most 32 entries; keys up to 64 characters, names up to 40 characters of plain text. A value with no label is shown as itself. In the manifest editor this is Value names, typed as L=Light Side, D=Dark Side.

modManifestSchema.variants.players#

Field Type Required Default Min / Max Pattern Rule Description
min integer yes — >= 1, <= 64 — — —
max integer yes — >= 1, <= 64 — — —

Whole-object rules:

  • players.max must be greater than or equal to players.min.

variants.players.min

The fewest players this variant works with. A whole number from 1 to 64.

Set it only when this variant's floor genuinely differs from the game's — a team variant that needs four where the base game plays with two. The pair is declared together, so a variant that only raises the ceiling repeats the game's own minimum here.

When min and max are equal the lobby states an exact count ("4 players") rather than a range, and the seat cap can only be that number or empty.

variants.players.max

The most players this variant seats. A whole number from 1 to 64, and never below min.

This is the number that makes a bigger-table variant mean something: with it set, the lobby's seat cap for this variant may go as high as this value. It is a claim about your set-up as well as a limit — the variant needs a seat, and whatever each seat is dealt, for every player you allow.

The platform's own ceiling is ten seats, one per player colour, so the effective maximum is the smaller of this number and ten.

modManifestSchema.variants.ranking#

Field Type Required Default Min / Max Pattern Rule Description
enabled boolean no — — — — —
pool string no — 1–40 chars ^[a-z0-9]+(?:-[a-z0-9]+)*$ — —
season integer no — >= 1, <= 999 — — —
placementGames integer no — >= 3, <= 25 — — —
sides "seats" | "teams" no — — — — —
draws boolean no — — — — —
requireKernel boolean no — — — — —
minMoves integer no — >= 0, <= 500 — — —
minSeconds integer no — >= 0, <= 3600 — — —
reconnectGraceSeconds integer no — >= 15, <= 600 — — —
botsRanked boolean no — — — — —
takebacks boolean no — — — — —

variants.ranking.enabled

Whether the lobby may offer Ranked for this variant. Default true.

false keeps every other setting but offers casual play only: the switch is not shown and no Score moves. Use it to pause a ladder without losing its configuration, for example while you fix a rules bug.

variants.ranking.pool

The ladder this variant's matches count toward. Default: the variant's own id. Lowercase letters, digits and single dashes, at most 40 characters.

Give two variants the same pool and they share one set of Scores: "Standard" and "Standard, scripted bots" may be one ladder, where "9×9" and "19×19" should not be. Variants on one ladder must rank the same sides and seat the same player range, or the manifest is refused with ranked-variant-bad-config.

A ladder is identified by the game, the pool and the season, so renaming a pool starts a fresh ladder just as bumping the season does.

variants.ranking.season

Which season of the ladder this is. A whole number from 1 to 999. Default 1.

Bump it when the rules change enough that old Scores no longer mean the same thing. Once you publish, every match counts toward the new season, everyone starts again at 1500, and the old season stays readable. The editor's Start a new season button does the bump. A match records the season it was played in, so nothing already played moves.

variants.ranking.placementGames

How many ranked games a player plays before their Score is shown publicly. A whole number from 3 to 25. Default 5.

Until then the player is in placement: their Score moves as usual but they are hidden from Rankings and shown as "Placement 3/5". Raise it for a game with a lot of luck in a single result, where five games say little.

variants.ranking.sides

What is ranked: "seats" ranks each seat on its own; "teams" ranks table teams. Default "seats".

"teams" cannot be published yet. A team is assigned to a player by the host at the table, and no manifest or scene field declares seat teams, so a teams ladder would rank whatever the host happened to assign. Publishing refuses it with ranked-variant-teams-undeclared, and the editor says so beside the choice. Use "seats".

variants.ranking.draws

Whether players get the platform's Offer draw button during a ranked match. Default false.

When every player accepts, the script's match.onDrawAgreed fires, and the match ends as a draw (by your script, or by the platform about 1.5 seconds later). Leave it off for games where a draw by agreement makes no sense; your script can still end a match with { draw: true } on its own.

variants.ranking.requireKernel

Whether only kernel matches are ranked. Default false.

A kernel match is one your script starts with match.start({ kernel }): every move is recorded and the other players replay the record to check the result, which grades it kernel-verified. With this on, a match started without a kernel plays on unranked (kernel-required), and a finished ranked match must carry its record.

Turn it on when your game has a rules kernel and you want every ranked result checked by replay rather than confirmed by eye. The editor's ranked checklist says whether it found a kernel in the variant's scripts.

variants.ranking.minMoves

The fewest moves a kernel match needs to count. A whole number from 0 to 500. Default 2.

A kernel match with fewer effective moves (takebacks removed) ends as no contest: nobody's Score moves. It stops "resign on move one" from being farmed for Score. Matches without a kernel are not counted by moves; they use minSeconds.

variants.ranking.minSeconds

The shortest a match may last and still count, in seconds. A whole number from 0 to 3600. Default 30.

Shorter matches end as no contest. Set it to something below the length of the quickest honest game.

variants.ranking.reconnectGraceSeconds

How long a disconnected player has to come back before they forfeit, in seconds. A whole number from 15 to 600. Default 90.

A player who returns in time carries on as if nothing happened. One who does not forfeits, ranks below everyone still playing, and (unless the platform can tell it was not their fault) the abandon counts against their Player Trust. Raise it for long, slow games where a phone call should not lose the match.

variants.ranking.botsRanked

Whether matches that include bots are ranked, for the people and for the bots. Default true.

Bots have Scores of their own, one per bot and difficulty, and they start at 1500 like everyone else. With this on, one person against a bot is a legitimate ranked match (graded self-hosted, at most 20 a day per player per ladder), which is also what lets a ranked variant start with a single human. Turn it off and seating a bot makes the lobby refuse a ranked Start (bots-not-ranked).

variants.ranking.takebacks

Whether players may ask to take a move back during a ranked match. Default true.

A takeback always needs every other human player to agree, and is refused outright in a match against bots only. Turn it off for games where a move cannot honestly be undone, such as a draw from a hidden deck that has already been seen. See Takebacks need everyone to agree.

modManifestSchema.aiModels.inputs#

Field Type Required Default Min / Max Pattern Rule Description
name string yes — 1–64 chars ^[A-Za-z_][A-Za-z0-9_.:/-]*$ — —
shape number[] yes — 1–6 items; each >= -1, <= 16777216 — — —
dtype "float32" | "int64" yes — — — — —

aiModels.inputs.name

The tensor's name exactly as the ONNX graph spells it: letters, digits and _ . : / -, starting with a letter or _, at most 64 characters. Unique across this model's inputs and outputs. It is the key your script uses in the inputs object it passes and reads in the result.

aiModels.inputs.shape

The tensor's dimensions, 1 to 6 of them. -1 is allowed only as the first dimension, where it means "the batch": ai.evaluate stacks positions along it. Every other dimension is a fixed positive size. A tensor may not declare more than 16,777,216 elements per position.

[-1, 3, 8, 8] reads: any number of positions, each three 8 × 8 planes.

aiModels.inputs.dtype

The element type: "float32" or "int64". Outputs must be float32. A script passes a Float32Array for a float32 input and a BigInt64Array for an int64 one.

modManifestSchema.aiModels.difficulties#

Field Type Required Default Min / Max Pattern Rule Description
id string yes — 1–40 chars ^[a-z][a-z0-9-]*$ — —
label string yes — 1–40 chars — — —
simsPerMove integer no — >= 1, <= 4096 — — —
temperature number no — >= 0, <= 2 — — —
params Record<string, number> no — — — — —

aiModels.difficulties.id

The preset's id: lowercase letters, digits and hyphens, unique within this model. Match it to a difficulty id of the bot that uses the model if you want its params.turnBudgetMs to apply.

aiModels.difficulties.label

The preset's display name, 1–40 characters of plain text. Players pick a bot's difficulty, not a model's, so this is mainly for the editor.

aiModels.difficulties.simsPerMove

Search simulations per move at this preset, 1 to 4096. Optional. A bot playing at this difficulty reads it as ctx.difficulty.simsPerMove; pass it to ai.mcts as simulations — nothing applies it for you.

aiModels.difficulties.temperature

Move-sampling temperature at this preset, 0 to 2 (0 always plays the most-visited move). Optional. A bot playing at this difficulty reads it as ctx.difficulty.temperature; pass it to ai.mcts yourself if you want it.

aiModels.difficulties.params

Free numeric settings for this preset: a map of names (up to 40 characters) to finite numbers.

A bot playing at a difficulty with this preset's id reads them in its turn as ctx.difficulty.params — a search depth, a bluff rate, anything your script wants per difficulty. One name is also read by the platform: turnBudgetMs — how long, in milliseconds, such a bot may think before its turn is skipped (default 30,000; the host keeps it between 250 ms and 5 minutes).

modManifestSchema.bots.difficulties#

Field Type Required Default Min / Max Pattern Rule Description
id string yes — 1–40 chars ^[a-z][a-z0-9-]*$ — —
label string yes — 1–40 chars — — —
description string no — <= 120 chars — — —
modelId string no — 1–40 chars ^[a-z][a-z0-9-]*$ — —

bots.difficulties.id

The difficulty's id: lowercase letters, digits and hyphens, unique within this bot. What your script receives as ctx.difficultyId. If the bot's model declares a difficulty with the same id, that one's params.turnBudgetMs applies.

bots.difficulties.label

What players pick: the difficulty's name in the lobby and the table's Bots panel. Plain text, 1–40 characters.

bots.difficulties.description

One optional line about the difficulty, at most 120 characters.

bots.difficulties.modelId

For an "ai" bot only: the id of the aiModels entry this difficulty plays with. Leave it out and the difficulty uses the bot's own modelId — its default model. A scripted bot's difficulties may not name one, and every id named here must be a model you declare.

Use it when your Easy, Medium and Hard are genuinely different networks rather than one network searched harder:

JSON
{
  "id": "othello-ai",
  "label": "Othello AI",
  "kind": "ai",
  "modelId": "othello-net-hard",
  "handler": "othello-ai",
  "difficulties": [
    { "id": "easy", "label": "Easy", "modelId": "othello-net-easy" },
    { "id": "medium", "label": "Medium", "modelId": "othello-net-medium" },
    { "id": "hard", "label": "Hard", "modelId": "othello-net-hard" }
  ]
}

The model a difficulty names is the one the platform treats as that difficulty's model everywhere:

  • the host's hardware requirement — a table seating the bot at Easy needs only the Easy model's minTier;
  • which model the host downloads and loads ahead of the bot's first turn;
  • ctx.modelId in the bot's onTurn, and the dials in ctx.difficulty (read from that model's own difficulties entry with the same id);
  • the bot's Rankings identity: each difficulty is ranked on the exact file it plays with, so retraining only the Easy network starts Easy on a fresh score and leaves Medium and Hard where they were.

When no difficulty is chosen the bot plays at its defaultDifficulty (else the first), and that difficulty's model applies.

modManifestSchema.bots.seats#

Field Type Required Default Min / Max Pattern Rule Description
max integer no — >= 1, <= 9 — — —

bots.seats.max

The most of this bot one table may seat, 1–9. The lobby and the table's Bots panel refuse another one past it ("Only one Bot may sit at a table." / "At most n … bots").

modManifestSchema.credits.attestation#

Field Type Required Default Min / Max Pattern Rule Description
termsVersion string yes — 1–40 chars — — —
acceptedAt string yes — — ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ — —
signedName string yes — 1–120 chars — — —

credits.attestation.termsVersion

Which version of the attestation wording was on screen when you signed.

This is the field that makes a stored signature mean something years later: it names the text you actually accepted. The wording is versioned and never edited in place, so a record written under an older version still resolves to what it said at the time.

credits.attestation.acceptedAt

When the attestation was accepted, as an ISO timestamp. For a record you signed at import it is the same instant as recordedAt — the credit and the signature are one act.

For an AI-attested record, the human attestation is written by the review, so this is the review time (the same value as aiAttestation.review.reviewedAt) and can be much later than recordedAt.

credits.attestation.signedName

The name you typed to sign the record.

Typed by hand on purpose. Your account is already on the publish, so this adds no identity that was not already there — what it adds is the deliberateness of having typed your own name, which is the difference between a claim and a checkbox.

modManifestSchema.credits.aiAttestation#

Field Type Required Default Min / Max Pattern Rule Description
termsVersion string yes — 1–40 chars — — —
agentSessionId string yes — — ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ — —
client string yes — 1–80 chars — — —
attestedAt string yes — — ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ — —
fetch creditAiFetchSchema no — — — — —
review creditAiReviewSchema no — — — — —

credits.aiAttestation.termsVersion

Which version of the attestation wording the agent was given when it answered the credit question.

The agent is sent the full text for the origin it chose, the same text you would see, and this field names it. It works exactly like the human attestation.termsVersion: the wording is versioned and never edited in place, so the value still resolves to what the agent was given.

It can differ from review.termsVersion. The reviewer signs the wording the editor shows at review time, which may be a newer version than the one the agent was given.

credits.aiAttestation.agentSessionId

The id of the agent session that answered the credit question: a UUID naming one pairing between an AI agent and your editor.

It ties the record to one session, so you can tell which run of which agent made the claim. It is published with the manifest like everything else in credits. On its own it is an opaque id and identifies nobody.

Only its shape is checked. Neither the publish step nor the scanner looks it up against a real session, so treat it as a record-keeping pointer, not as proof.

credits.aiAttestation.client

The AI client that answered, as it named itself (for example Claude Code 2.x). 1 to 80 characters.

It is there so the person reviewing the record knows which tool made the claim. It is display only: the client reports its own name, nothing verifies it, and nothing is decided from it.

credits.aiAttestation.attestedAt

When the agent answered the credit question, as an ISO timestamp in UTC (ending in Z).

It records the agent's act, the way attestation.acceptedAt records yours. An agent edit that re-stamps the record moves it to the time of that edit.

credits.aiAttestation.fetch

URL imports only: evidence of what was actually downloaded, when an agent imported a file from a web address rather than from your disk.

The requested address becomes the record's ordinary sourceUrl. This object records the other half: the address the download ended on after redirects, the sha256 digest and size of the bytes received, and when. The editor checks the digest against the bytes it receives before importing them.

It is there for the reviewer. A sourceUrl on one site and a finalUrl on an unrelated host is worth a second look before you sign.

Absent for a file imported from disk, which has no download to describe.

credits.aiAttestation.review

The human sign-off on an AI-attested record: when it was reviewed, the name the reviewer typed, and the wording version they signed.

Absent means unreviewed, and unreviewed means no publish. While any record has an aiAttestation without a review, the publish step refuses with 409 ai-credits-unreviewed and the scanner refuses registration with ai-credit-unreviewed.

A review always writes two things at once: this object, and an ordinary human attestation with the same wording version, time and name. The pair is required. A review without the attestation is refused by the schema, and the publish step treats it as unreviewed. The reason is compatibility: a client or server that predates aiAttestation reads only attestation, so a reviewed record has to look signed to it as well.

Only a person can add it. An agent has no way to review a record, including one it attested itself. Reviewing a record that was already reviewed stamps it again with the new name and time.

An agent edit that needs a fresh signature removes it, and the record is unreviewed again.

modManifestSchema.credits.aiAttestation.fetch#

Field Type Required Default Min / Max Pattern Rule Description
finalUrl string yes — <= 2000 chars — Use a full https:// link. —
sha256 string yes — — ^[0-9a-f]{64}$ — —
bytes integer yes — >= 0, <= 9007199254740991 — — —
fetchedAt string yes — — ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ — —

credits.aiAttestation.fetch.finalUrl

The address the download ended on, after every redirect. Up to 2000 characters, and always https://. The download service refuses plain http, so an http value never occurs, and the schema refuses one: Use a full https:// link.

Compare it with the record's sourceUrl, the address that was asked for. A download page that redirects to a file host is normal. A redirect to somewhere unrelated is the thing to notice.

credits.aiAttestation.fetch.sha256

The sha256 digest of the downloaded bytes, as 64 lower-case hex characters.

It identifies the exact file that was fetched. An upper-case or short digest is refused: Use a 64-character lower-case hex sha256.

It describes the bytes as they were downloaded. A model converted to .glb, or an image optimised on import, is stored as different bytes, so hashing the file in your repo will not reproduce it. That is expected, not a sign of tampering.

credits.aiAttestation.fetch.bytes

The size of the downloaded file, in bytes. A whole number, zero or more.

Like sha256, it describes the download, not the file as stored after any conversion or optimisation on import.

credits.aiAttestation.fetch.fetchedAt

When the download finished, as an ISO timestamp in UTC (ending in Z).

It normally comes shortly before attestedAt: the file is fetched first, then imported, and the credit question is answered as part of the import.

modManifestSchema.credits.aiAttestation.review#

Field Type Required Default Min / Max Pattern Rule Description
reviewedAt string yes — — ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ — —
signedName string yes — 1–120 chars — — —
termsVersion string yes — 1–40 chars — — —

credits.aiAttestation.review.reviewedAt

When the person reviewed the record, as an ISO timestamp in UTC (ending in Z).

It is written together with the record's attestation.acceptedAt, with the same value. The record's recordedAt does not change: it still says when the file was imported.

credits.aiAttestation.review.signedName

The name the reviewer typed to sign the review. 1 to 120 characters.

Typed by hand for the same reason as attestation.signedName: your account is already on the publish, and what a typed name adds is the deliberateness of signing. You type it once for every record you review together, and the same name goes into each record's human attestation.

credits.aiAttestation.review.termsVersion

Which version of the attestation wording the reviewer signed.

It is the wording the editor shows at review time, which can be newer than the aiAttestation.termsVersion the agent was given if the wording changed in between: you sign the current text, not the agent's. The same value goes into the record's human attestation.termsVersion.

modAssetRefSchema#

Exported from @diceytable/shared as modAssetRefSchema. 2 fields across 1 table.

Field Type Required Default Min / Max Pattern Rule Description
path string yes — 1–180 chars — — —
sha256 string no — — ^[a-f0-9]{64}$ — —

path#

The repo-relative path that identifies the file — the same string that appears in assets, in your repo, and as the key the local play cache stores the bytes under. It is what ties a catalog entry to a real file.

Because it is also the download target it has to match the published path exactly, case included. A path that isn't in the repo at the published commit is recorded as a failed pull, its bytes never reach the cache, and anything referencing it falls through to a GitHub URL that 404s in the same way.

sha256#

The integrity check for one file. pullModTree (apps/web/src/publish/githubPull.ts) hashes each downloaded blob and compares it with this value; a mismatch aborts that file, so bytes that failed verification never enter the play cache. This is defense in depth, not the acceptance gate — the server-side scan is that.

Omit it and the file downloads and caches with no verification, which is why older manifests keep working. Leave a stale one behind and the file fails verification on every session, falls back to loading straight from raw.githubusercontent.com, and quietly costs you the cache instead of the asset. Regenerate the hash whenever you republish changed bytes.

modScreenshotSchema#

Exported from @diceytable/shared as modScreenshotSchema. 13 fields across 3 tables.

Field Type Required Default Min / Max Pattern Rule Description
path string no — 1–180 chars — — —
crop cropRectSchema no — — — Crop rectangle must stay within the image bounds (x+w and y+h ≤ 1). —
video modVideoSchema no — — — — —
title string no — 1–120 chars — — —
alt string no — 1–300 chars — — —
kind "marketing" | "gameplay" | "component" no — — — — —

Whole-object rules:

  • A gallery entry needs either an image path or a video.

path#

The repo path of the published screenshot — the 16:9 WebP the media pipeline produced, not the picture you uploaded. Nothing in the manifest points at your original, so keep it somewhere you can find it again.

The editor names these files by slot (media/screenshot-1.webp and upward) and overwrites in place, so replacing or re-cropping a screenshot reuses its path instead of piling spare images into the repo.

crop#

A record of how the published image was framed, in fractions of the source, so the editor can reopen the crop tool on the same rectangle instead of making you upload the picture again. Nothing reads it at display time — the file at path is already cropped.

The reach of that record has a limit worth knowing before you lean on it. While the authoring session that uploaded the image is still open, a re-crop starts from your original with this rectangle as its frame. Once that session is gone the original is gone with it, and a later re-crop works from the published 16:9 derivative — so it can tighten the frame and never recover what the first crop cut away. Keep originals outside the mod if you expect to reframe them later.

video#

Links a YouTube video into the gallery entry. With no path beside it the entry is the video; with one, that image is the video's cover.

A video is the one gallery item whose bytes are not yours — nothing is published for it and nothing is scanned. It also costs a visitor nothing until they want it: the page draws the cover and loads YouTube's player only when somebody presses play.

Add one from Mod Details ▸ Screenshots & videos ▸ Add a video, and give it a cover with the image button on its tile. Without a cover, YouTube's own still is used — upload one only when you want a particular frame to introduce the video.

A game may also publish a video as a rulebook (rules[] with kind: "video"), which is the right place for a how-to-play. Use the gallery for the trailer and the rulebook for the tutorial.

title#

A short caption for this gallery entry, shown beside the image on the details page and used as its press label.

It is not alt text and does not replace it. A caption says what to notice — "Turn three, the trade phase" — while alt says what is in the picture for someone who cannot see it. Writing one sentence and using it for both leaves the gallery reading as the same line twice.

Leave it out when the image speaks for itself. An absent caption renders nothing; it does not render an empty line.

alt#

Alternative text: what a reader who does not see this image should be told about it.

It is read out by screen readers and shown in the image's place when it fails to load. Without one the page falls back to a positional label — "Catan screenshot 3" — which locates the image without saying anything about it. That fallback exists because a missing alt attribute is worse than a weak one, not because it is good enough.

Describe the picture, not its job: "four players around a table mid-auction, the board half-built", not "gameplay screenshot". Keep it to a sentence.

kind#

What this entry is FOR, so a surface that is not the gallery can pick the right image on its own:

  • marketing — like what you would see on an ad or game box.
  • gameplay — screenshots showing the game being played.
  • component — close-up screenshots or renders of game components, like pieces, gameboards, etc.

The gallery itself ignores it: there, your array order is the pitch and nothing re-sorts it. The field is for everywhere else — a listing tile that wants marketing art, a "how it plays" block that wants a real table, a component list that wants the close-up.

It is optional, and an absent value means unclassified, never a default. A pack published before this field existed has no answer, and we do not invent one for it — a consumer with nothing to match falls back to gallery order.

modScreenshotSchema.crop#

Field Type Required Default Min / Max Pattern Rule Description
x number yes — >= 0, <= 1 — — —
y number yes — >= 0, <= 1 — — —
w number yes — > 0, <= 1 — — —
h number yes — > 0, <= 1 — — —

Whole-object rules:

  • Crop rectangle must stay within the image bounds (x+w and y+h ≤ 1).

crop.x

The left edge of the crop window, as a fraction of the source image's width. 0 starts at the left edge; 0.25 skips the first quarter of the picture.

Fractions rather than pixels are what let the rectangle survive re-encoding: the same four numbers describe the same framing on the original upload and on a resized copy of it, which is the whole reason a crop can be reopened at all.

crop.y

The top edge of the crop window, as a fraction of the source image's height, measured downward from the top. 0 starts at the top of the picture, and a larger y slides the window toward the bottom.

This is the axis to double-check when you write a rectangle by hand: image space puts the origin at the top-left and counts down, the opposite of the Y-up convention the table's world coordinates use.

crop.w

How much of the source's width the window keeps, measured rightward from x. 1 keeps the full width.

What is easy to miss is that w and h are fractions of two different dimensions, so equal values do not describe a square window unless the source itself is square. The editor's crop tool sidesteps the problem by locking the window to the output aspect as you drag it; a rectangle typed into the manifest by hand carries no such guarantee.

crop.h

How much of the source's height the window keeps, measured downward from y.

The output aspect is fixed — square for a cover, 16:9 for a screenshot — and the pipeline cover-fits your window into it, trimming the long axis symmetrically rather than letterboxing or stretching (resolveSourceDrawRect, apps/web/src/ui/editor/mediaPipeline.ts). A window that isn't already at the output aspect therefore loses part of what you asked for on one axis. Frame at the target aspect when the exact edges matter.

modScreenshotSchema.video#

Field Type Required Default Min / Max Pattern Rule Description
provider "youtube" yes — — — — —
id string yes — — ^[A-Za-z0-9_-]{11}$ — —
title string no — 1–120 chars — — —

video.provider

Which service hosts the video. "youtube" is the only value.

It is stored explicitly rather than inferred so that a second provider, if one is ever added, is a change you can see in your manifest instead of a link that silently starts behaving differently.

video.id

The YouTube video id — the eleven characters after watch?v=, and not a URL.

Paste any normal YouTube link into the editor (a watch page, a youtu.be link, a Short, or the id on its own) and it extracts the id for you. The manifest stores only the id because that is the narrowest thing that can be turned back into a player: a reviewer reading your manifest can see exactly which video plays and nothing else can be smuggled in beside it.

Hand-writing one? It must match [A-Za-z0-9_-]{11} exactly; anything longer or shorter is refused at publish.

video.title

An optional label, shown over the cover and used as the video's accessible name.

Worth setting when a pack has more than one video, so the play buttons read as "Play video: Setup in two minutes" rather than "Play video: Video" to anyone using a screen reader. Up to 120 characters.

Did this page answer your question?