Dicey Table

The Interface

The Topbar and Menu Bar

Edit Mode's top two rows — the logo bar (project, variant, save pill, Save Draft, Preview, Publish) and the File / Edit / View / Mod / Help menu bar.

On this page3 sections

The top of Edit Mode is two rows, the same in every editor mode (Game, Room, Table, Asset and the Full Editor):

  1. The logo bar (<header className="em-topbar"> in TableEditModeShell.tsx): which mod you are in, whether your work is saved, and the three actions you use all the time — Save Draft, Preview and Publish.
  2. The menu bar under it (EditorMenuBar): File, Edit, View, Mod and Help, like a desktop application. Everything else lives here, including the actions that used to be buttons on the logo bar (Undo/Redo, Export, Mod Details, Collections, Asset Packs, Updates, Verify, Screenshots, Help and Exit). Save Draft, Preview and Publish are in the menus too.

The logo bar#

Left group — where am I?#

Element Symbol What it is
Dice mark and DiceyTable em-logo The DiceyTable logo mark and wordmark. Static, not a link. Editors that open in a tab (such as the advanced image editor) do not repeat it.
Mode pill em-mode-pill The editor mode — Game Editor, Room Editor, Table Editor, Asset Editor, or Edit in the Full Editor.
Project name and status em-project-name-btn "{project.displayName} · {project.status}", or No project loaded before a project opens. Click it to open File ▸ Open Project….
Variant controls em-variant-bar Game packs only, in the Game Editor and the Full Editor. Which variant of the game is on screen, where your next edit lands, and the Variants button. See The variant controls.
Read-only em-mode-pill-readonly Only when another tab owns this mod's draft. Click it to ask that tab for control. See One mod, one writing tab.

To change the mod's title you use Mod ▸ Mod Details…, below.

The variant controls#

A game pack can be offered in several set-ups — a 9×9 and a 19×19 board, a six-seat and a ten-seat table, scripted and by hand. Each is a variant, and the room's owner picks one in the lobby. Game variants explains the feature; Making a variant of your game is the walkthrough.

You edit one variant at a time. The controls sit beside the project name because they answer the same question one level down — what am I editing? — and they stay visible the whole time an edit could go to the wrong place.

Control What it does
Variant The variant the editor is showing. Switching swaps the whole scene — viewport, Hierarchy and Inspector — to that variant's. Nothing is lost by switching. The base variant is marked (base) in the list.
Changes apply to Where your next edit goes: All variants or Only variant. See below.
A number, when present How many things differ from the base in the variant on screen. Hover it for the wording; open the Variants dialog for the list. Not shown on the base.
Variants Opens the Variants dialog: create, describe, compare, reorder, delete.

A game with no variants yet shows only the Variants button. One way to play needs no switcher. The controls are absent altogether in the Room, Table and Asset Editors, and for any pack that is not a game.

Changes apply to is the one decision variants add to editing:

  • Only variant — an edit becomes that variant's own difference. Move an entity, and this variant has its own version of it. Delete one, and it is removed from this variant only. Add one, and only this variant has it. Every other variant is untouched.
  • All variants — an edit is written to the base, so it reaches every variant that has not changed that same thing itself.

Two rules decide the cases in between, and both follow "you are editing what you are looking at":

  • Something this variant already has its own version of stays its own, whichever setting is chosen. If 9×9 has its own board, editing that board with All variants selected still edits 9×9's board.
  • On the base variant there is nothing to choose. The base is what the others start from, so the control reads All variants and is disabled — kept in place rather than hidden so the bar does not jump when you switch variants.

⚠ Deleting an entity with All variants selected deletes it from every variant, including one that had its own version of it. Use Only variant, or the Inspector's Remove here, to take it out of one.

The setting starts at Only variant each time you open a project and each time you create a variant, which is the safe default: an edit made in a variant stays in that variant until you say otherwise. Changing the setting does not re-file edits you have already made.

Entities are tracked one at a time. The rest of the scene is tracked in four groups — Table & room, Seats & zones, Snap points and Scene scripts — and a variant either follows the base's for a group or holds its own copy of it. Editing a seat zone with Only variant selected gives that variant its own seats and zones from then on; the Variants dialog shows which groups a variant holds and can hand them back.

Switching variants is not an undo step — it changes what is on screen, not the project. Every edit is an undo step as usual, and a step remembers the variant it was made in: undoing it puts that variant back on screen so you can see what changed. The editor reopens a project on the variant you last had open in this browser.

Script, material, texture and prefab libraries are shared by every variant, and so are the Hierarchy's folders. Edits to them reach every variant regardless of the setting.

Right group — the actions#

The save-state pill, Save Draft, Preview (with its with / in room picker in the Room and Table Editors) and Publish. Each is described below.

The save-state pill#

A pill (em-save-pill) showing saveStateLabel, derived from saveState:

Pill saveState Meaning
Saved saved The draft on the server matches what is in front of you.
Dirty changes dirty You have unsaved edits to the scene, the manifest, the draft label, or an open editor tab that owns a backing file.
Invalid draft invalid Draft or scene validation is failing. This wins over dirty — an invalid draft is reported as invalid whether or not it is also unsaved.

"Dirty" is computed from hasUnsavedChanges, which compares three things against the copy loaded from the server — the draft label, the serialized scene document, and the canonical manifest text (canonicalised so whitespace and key-order differences do not read as an edit) — plus hasUnsavedItemTabs, which is true while a Deck, Model, File or Script tab holds edits that have not been written to its file.

That last term matters: those tabs write their own backing file (.deck.json, <model>.meta.json, the file's bytes) rather than going through the scene draft, so without it the pill could read Saved while a renamed deck sat unsaved in a tab — and Publish would then ship the previous file. Save Draft and Publish now flush every such tab first, and Publish refuses to run if one of them cannot save, naming it rather than publishing stale contents.

Whenever anything is wrong or unsaved, the pill stops being inert text. With errors or warnings it grows a badge counting them (red / amber). Clicking it opens:

  • on Dirty changes, the Unsaved changes dialog (below);
  • on Invalid draft, or on Saved with warnings, the Problems panel with the full list — including failures the pill itself cannot express, such as a WIP checkpoint that could not reach GitHub.

The badge counts only problems that are true now — the draft, scene, GitHub, publishing and last-operation rows, which clear themselves when fixed. The tab's diagnostics log (a script's old compile error, a missing asset, a sync conflict you already resolved) is listed in the panel but never counted, because nothing removes a log entry and the pill would otherwise stay an error button for the rest of the session.

With nothing to report it stays a plain, non-interactive pill.

The Unsaved changes dialog#

Says what is unsaved, in the same terms the pill computes it, and offers the fix for each:

Section Shown when What you can do
Validation the draft is invalid Show problems opens the Problems panel.
Scene the scene document differs from the saved one Lists entities Added, Removed and Changed (with the fields that changed) — click one to select it — plus any other part of the scene that changed (environment, seatZones, …).
Scene — formatting only the scene differs only in how it is written (for example the field order of a newly placed entity), so the server already holds exactly this scene Mark as saved re-baselines without a save. Nothing is discarded.
Project name the draft label was edited — (Save Draft)
Mod details / manifest the canonical manifest differs — (Save Draft)
Project files files were added, moved or deleted — (Save Draft)
Open editor tabs a Deck / Model / File / Script tab holds unsaved edits Click the tab name to switch to it.

Save Draft at the bottom does the same as the topbar button.

The same three signals are reported in more detail on the status bar.

Save Draft#

Writes your work back to the server. Disabled while busy, with no project loaded, or when there is nothing to save — neither draft changes nor an unsaved editor tab. Tooltip: "Save the draft (Ctrl+S)".

saveDraft does four things worth knowing:

  1. It flushes every dirty editor tab that owns a backing file — Deck, Model, File and Script. Those tabs do not go through the scene draft, so without this step their files would keep their previous contents while the pill reported Saved. A tab that fails to save is named in the result rather than passed over.
  2. It validates the scene document (editSceneSnapshotSchema.safeParse). If the parse fails it refuses to save and reports "Scene draft is invalid. Fix validation errors before saving." Nothing is sent.
  3. It PUTs the validated document — label, manifest text, the scene document as setupText, and editor metadata — to /api/editor/projects/{id}/draft.
  4. On success it re-baselines: the saved bytes become the new comparison point, so the pill returns to Saved and the dirty dots clear on open material tabs.

Material and Texture tabs are not in step 1, and do not need to be: their edits mutate the scene draft directly, so they are already inside step 3's payload.

Saving a draft is not publishing. It puts your work on the DiceyTable server as a draft; it does not push anything to GitHub. See Publish below.

Preview#

Full Editor (plain /editor), Game Editor, Room Editor and Table Editor. A Preview button with a play icon on the logo bar, directly before Publish, and File ▸ Preview in the menu bar. It lets you play your unpublished draft at a real table without creating a room or publishing anything. Tooltip: "Save the draft, then play it in a new tab — no room, no publish".

Clicking it does three things in order:

  1. Flushes every dirty editor tab that owns a backing file — the same gate Save Draft and Publish use. If a tab cannot save, Preview is not opened and the error names the tab, because the preview would otherwise show that file's previous contents.
  2. Saves the draft. If the save fails, nothing opens. The button reads Saving… meanwhile.
  3. Opens the preview tab at /table?preview=<projectId>. The tab is named per project, so a second click reuses (and reloads) the preview you already have instead of opening another.

For a game with variants, Preview opens the variant on screen — what you are looking at is what you are asking to play. It travels in the URL as &variant=<id>, so the preview tab can be reloaded and still show the same variant. A variant with scripts switched off previews with no scripts running, exactly as it will play.

In the Room Editor and Table Editor a small picker sits beside the button: with for a room pack, in room for a table pack. It chooses what your pack is previewed against, and it is a viewing choice only — it is never written into your pack and never published. It travels in the preview URL as &with=…, so the preview tab can be reloaded or shared with yourself and still show the same pairing.

  • A room may be previewed with the default table (Square Table), with any published table pack, with No table — useful for judging the room on its own; the physics table still exists, it is simply not drawn — or, under Games, with a whole published game set up in it.
  • A table is always previewed in a room: the default room (Modern Room), or any published room pack. There is no "no room" option, because a table floating in a void says nothing about scale, light or reach. A table is never previewed with a game — a game is what stands on a table, so the two would be two tables in one scene.

Picking a game is the same choice as picking a table, not a second one, so the two clear each other: a room has one thing standing in it. The game brings its own table, which is why the table options grey out of relevance — its table is part of the set-up you asked to see, and letting your table pick win would stand its pieces at a height it was never authored against. Choosing a game also changes the editor viewport, not just the preview tab: the game's pieces appear in the room you are authoring as locked scenery — not in the Hierarchy, not selectable, never saved into your pack. See Preview and photo mode.

An Asset Editor project has no Preview button: an asset pack is framed on a turntable in the editor viewport and has no scene to stand in.

If your browser blocks the new tab, the status line says so and an Open Preview link appears beside the button. A link click is always allowed, so clicking it opens the tab.

Preview is disabled while the tab is read-only (another tab holds this project's editor lease), with no project loaded, or while another operation is running.

What the preview tab loads, what it refuses, and why nothing in it is saved: Previewing a draft and photo mode.

Publish#

Opens the Publish to GitHub dialog, from the logo bar's Publish button or File ▸ Publish to GitHub…. Disabled with no project loaded.

Publishing is the step that makes a mod real for other people: files live in your GitHub repository, not on a DiceyTable server. The dialog itself, the OAuth connection and the wip → main model are documented in Publish to GitHub and The publish flow.

If an AI agent answered the import credit question for any file, those credits must be reviewed by a person before a publish goes through; see the Credits tab.

The menu bar#

Click a menu title to open it. While a menu is open, moving the pointer onto another title switches to it. From the keyboard, ←/→ move between menus, ↑/↓ between items, → or Enter opens a submenu and ← closes it, and Enter or Space runs an item. Escape or a click anywhere else closes the menu. Escape only closes the menu; it does not also clear your selection.

The shortcut shown beside an item is the same key binding described on Keyboard shortcuts. The item and the key call the same handler. Items that do not apply right now are greyed out, and items for panels your editor mode does not have are not listed at all.

Notices appear at the right-hand end of the menu bar:

Notice When
Read-only Another tab owns this mod's draft. Click it (or the topbar Read-only badge) to ask that tab for control; it says whether the request is pending, was declined, or went unanswered (then it offers to take control anyway)
This is a kind mod The mod is open in an editor its kind does not belong in. It offers a link to the right editor. Nothing redirects on its own
N pack updates A pack you reference has published a newer version. Opens the same list as Mod ▸ Pack Updates…

File#

Item Shortcut Does
New Mod… Opens the New Mod dialog — see Opening Projects
Open Project… Ctrl+O The project picker, with a folder per kind — see Opening Projects
Open Recent ▸ Your eight most recently updated other projects
Save Draft Ctrl+S Same as the Save Draft button
Preview Same as the Preview button. Not listed in the Asset Editor
Publish to GitHub… Same as the Publish button
Sync with GitHub… The GitHub sync dialog (conflicts, re-sync, reset). Greyed out until the mod is linked to a repository. The status bar's ⇅ indicator opens the same dialog
Export Project JSON See Export
Preferences… Your own editor settings — currently the unit lengths are shown in. See Preferences and Display Units
Exit Editor See Exit

Export

Downloads a JSON snapshot of the project. exportProject fetches /api/editor/projects/{id}/export and saves it as {slug}.diceytable.json via a temporary object URL. It exports the server's copy, so anything you have not saved is not in the file.

Walkthrough: Export a project.

Exit

Leaves Edit Mode and returns to wherever you came from (the onExit callback the shell was mounted with). It does not prompt and it does not save — but leaving does not discard your draft either: the draft is on the server as of your last Save Draft, and the layout and undo history are flushed to localStorage on unmount.

There is a second Exit control, an icon button at the foot of the transform rail. Both call the same handler.

Edit#

Item Shortcut Does
Undo Ctrl+Z Undo the last scene change
Redo Ctrl+Shift+Z Redo. Ctrl+Y also works
Copy Ctrl+C Copy the selection
Paste Ctrl+V Paste what was copied
Duplicate Ctrl+D Duplicate the selection
Delete Del Delete the selection. A multi-selection asks once first
Rename F2 Focus the Inspector's Name field

These act on the scene, so they are greyed out while an item-editor tab (Deck, Model, File, Script…) is in front, the same way their keys are ignored there.

History is a snapshot history of the whole scene document, the draft label, the manifest, the Table Editor's table pack and the Room Editor's placed scenery, not a per-field command stack — so undo also reverses a Mod Details (manifest) edit, a table model or seat-ring change, and a moved or deleted piece of room decor.

Only your manifest edits are undo steps — the Manifest tab, Mod Details, pack references, sound sets, and an AI agent's manifest_set. The editor also rewrites the manifest itself: it re-declares a file after you move, rename, import or delete it, reconciles the file list when you save, merges a GitHub sync-down, records an import's credit, and commits the version you publish. Those are facts about files and GitHub, not edits, so undo never reverses them. They are folded into every step of the history instead: undoing a scene edit made before you moved a file keeps the file's new path, and undoing after a sync or a publish never brings back the manifest from before it. A step that only changed something the editor has since rewritten drops out of the stack.

A checkpoint is taken 450 ms after you stop changing things (serializeEditorHistory behind a debounce), so one drag, or one burst of typing, becomes one undo step. The stack holds HISTORY_LIMIT = 50 steps and is persisted per user and per project in localStorage under diceytable.editor.history.{userId}.{projectId}, so it survives a reload. The stored history carries a format number; history written by an older version of the editor is discarded on load rather than half-applied, so after an update the stack simply starts empty. Because a checkpoint is a whole document, undo also reverses things that have no obvious "field" — a spawn, a delete, a reparent.

View#

Item Shortcut Does
Select / Move / Rotate / Scale Tool Q / W / E / R Switch the transform tool. The active one is ticked. Same as the transform rail
Frame Selection F Re-select the selection and re-attach the gizmo. The camera does not move yet — see Frame selection
Orthographic View Drop perspective — see Orthographic view. Ticked when on. Greyed out unless you are on the Orbit camera
Bake Static Lighting Bake the room and any static scenery into lightmaps, and capture a reflection probe. See Static lighting. Not listed in the Asset Editor
Auto Bake Re-bake by itself after a change that invalidates the bake. Ticked when on, and on by default. See Static lighting. Not listed in the Asset Editor
Problems The Problems panel. Greyed out when there is nothing to report
Screenshots… See Screenshots. Listed wherever Preview is

Orthographic view#

View ▸ Orthographic View switches the viewport between the normal perspective camera and an orthographic one. It is ticked while orthographic, and it is a view setting only — nothing about your document changes, nothing is saved, and nothing reaches another player.

Two things change, and the second is the reason to reach for it:

  • Parallel lines stay parallel, and a thing is the same size on screen wherever it sits in the frame. A square board looks square rather than trapezoidal, and two rows of pieces you meant to line up either line up or visibly do not.
  • A click projects along one direction. With perspective, the ray under your cursor fans out from an eye point, so a click near the edge of the frame travels diagonally and lands further from where it looked than you expected. With orthographic, every click travels the same way the camera is looking — so from a top-down orbit it goes straight down, and a snap point, decal or dropped preset lands directly under the cursor.

That makes it the view to be in while laying out snap points and anything else whose position you are judging by eye against the surface below it.

Zoom works exactly as it did: the wheel still changes the orbit distance, and the orthographic frame is sized from it, so switching between the two projections never resizes what you are looking at.

It applies to the Orbit camera only. First person and Fly are always perspective — an orthographic first-person view is not a view of anything, and Fly steers by moving forward, which an orthographic camera cannot show. A VR or AR headset likewise always renders perspective. The setting is remembered while you are in those cameras and comes back on its own when you return to Orbit, so you never have to re-enable it.

Static lighting#

A bake produces two things from the same inputs, which is why it is one action:

  • Lightmaps — the diffuse half. The room's surfaces, its decor, the table model and any model flagged Static scenery get their lighting burned into a second UV set. A mesh exported without TEXCOORD_1 is skipped, and the status line says how many were.
  • A reflection probe — the specular half. The room is rendered into a cubemap from just above the middle of the play surface, prefiltered, and published as the scene's environment. Every material picks it up automatically, so Metalness, Gloss and Reflectivity start reflecting the room the table is actually standing in. Without a bake there is nothing for them to reflect, which is why a metallic piece can look flat or black.

While it runs, the menu item shows Baking… and then what it did — for example 15 baked · probe 256² · 279ms. The same action is on the Environment inspector as Static lighting ▸ Bake in the Game and Room editors; the Table Editor reaches it only from this menu.

Auto Bake re-runs it for you after any change that makes the last bake wrong — a room edit, decor, lights, the table model. It waits for a pause before baking, so dragging a slider produces one bake and not one per frame, and it stands down while you are mid-drag or the tab is in the background. Turning it off keeps whatever is already baked; turning it back on bakes once straight away.

Three things worth knowing:

  • A bake is yours alone. Lightmaps and the probe are local render state — they are not saved into the mod, not written to the scene, and not sent to other players. Each client bakes its own.
  • A baked object is frozen. Move something after baking and its baked contact shadow stays where the object used to be. That is why only the room, the table and models you explicitly flag as static scenery are eligible.
  • It does nothing on the Low graphics tier, which captures no probe at all. The menu action still works; only the automatic re-bake stands down.

Mod#

Item Where Does
Mod Details… Every editor See Mod Details
Variants… Game packs, in the Game Editor and the Full Editor Opens the Variants dialog — the same dialog as the logo bar's Variants button. Not listed for a room, table or asset pack. Greyed out until a project and its scene are loaded
New ▸ Every editor The asset explorer's create actions — Folder, Material, Material from Texture Maps…, Script, Deck, Board from Image… and Card Data — see The toolbar. Only the entries this editor offers are listed, and Card Data is listed only until the mod has card data
Open In ▸ Every editor, once a mod is open Switch this tab to another editor mode for this mod. Only the modes the mod's kind allows are listed — see Opening Projects
Collections… Game Editor See Collections
Browse Asset Packs… Game Editor Browse published Asset packs to reference or copy in — see Import an asset pack
Pack Updates… Game Editor Referenced packs and whether a newer version exists. Opening it changes nothing. When there are updates the item shows a count and the Mod title gets a dot
Verify as a New Player… Game Editor Re-fetch the published project cold — see Verify as a new player

Mod Details#

Mod ▸ Mod Details… opens the manifest editor — an item-editor tab named diceytable.mod.json, the same tab you get by double-clicking that file in the asset explorer. It is a form over the whole manifest: everything that ends up in diceytable.mod.json rather than in the scene is edited here, and nowhere else. Disabled with no project loaded.

The form is split into tabs by the question you arrive with. A tab with something worth seeing before you open it carries a count:

Tab Holds Count on the tab
Details How the pack is listed: title, Mod ID, version, public URL, summary, description, category, seat counts, tags, cover image, screenshots, and the performance budget for a room or an asset pack —
Gameplay Entry points (the scene and the script, picked from the project's files so a path cannot be mistyped), Rules (the rulebooks players open from the table), Setup options (the room owner's game options) and Lobby requirements, with the game's own decks file — see the Gameplay tab Problems that would fail a publish
Files Every file in the project and what publishing does with it, plus Serves art from (outside asset repositories) — see the Files tab Declared files that do not exist
Bots Game packs only: the AI models the game ships and the opponents it offers — see the Bots tab Bot or model problems that would fail a publish
Plugins The plugins this pack uses, the functions its script may call, and its answers to their settings — see the Plugins tab. Absent for a room or a table pack, which run no script Plugins in the pack
Credits Where the pack's files came from and what it inherits from the packs it depends on, and the review of any credits an AI agent attested — see the Credits tab Files with no credit recorded
File The manifest itself, as read-only JSON, so the file is never a black box —

The red counts (Gameplay, Files) are things to fix; the others are information. Only the sections your pack's type can use are shown — a field the type cannot declare, left behind by a hand-written manifest, is listed above the tabs with the reason and a Remove button rather than silently hidden.

Closing the tab after making changes saves the draft and checkpoints it, the same way Save Draft does.

Once the project is published, a Published mod row under the URL field on the Details tab also offers Make private and Delete for the registered mod. These act on the server immediately, not through Save Draft. See Private and deleted mods.

The Details tab follows your pack's type. A game, a table, a room and an asset pack are not published the same way, so the fields and the copy differ:

type Category list Seat range Public URL
game-pack Game genres, mechanics and themes Players, min–max diceytable.com/games/<slug>
table-pack Table shapes and styles Seats, min–max diceytable.com/mods/<slug>
room-pack Room settings and styles — diceytable.com/mods/<slug>
component-pack The kinds of part the pack carries — diceytable.com/mods/<slug>

A room and an asset pack have no seat range at all, and that is a removal rather than an oversight: the range says how many people sit down to the thing, and a room seats nobody (the table in it does). /games/ is likewise reserved for game packs — it is the listing they are the only members of — so every other type is published under /mods/.

Mod ID is the pack's permanent identity — the value other mods and games use to refer to it, and the thing the library keys its record on. It is not the public web address; that is the URL field. It must be 3–96 characters, start and end with a letter or a digit, and otherwise contain only letters, digits, ., - and _. The editor picks one for you from the title when you create the pack; an id that does not meet the rule is called out in place, with a legal replacement one click away, and publishing is refused until it is fixed.

You can change it right up until you publish, and not afterwards. Once a pack is registered the field locks, because an id is not a label: it is what every game's room and table assignments pin, what collections list, and what the registry row is keyed by. Changing it then would not rename your pack — it would create a second one and leave the published one behind.

There is no way to free a published id, and deleting is not one: a deleted mod keeps its row as a tombstone precisely so its id stays reserved, and the project leaves your Projects rail with it. Publishing under a different id means starting a new mod. So it is worth reading the id once before your first publish.

Version is the one field on the Details tab that is not discovery metadata, and it is the one that decides whether a re-publish is accepted at all. A published version is immutable: the library refuses to repoint an already-published version at new bytes, so once you have published, changing anything means bumping the version before you publish again. Bump patch beside the field does the common case (1.0.0 → 1.0.1); type any semver value for anything else. A malformed version is listed alongside a missing cover in the pre-publish requirements rather than surfacing as a failed publish.

Edits made there are merged into the draft manifest, which means they are covered by the same Dirty changes → Save Draft cycle as the scene.

Field-by-field reference: Manifest reference.

Mod Details: the Gameplay tab#

Entry points picks the scene and the script the pack loads, from the project's own files. Rules lists the rulebooks players open from the table. The rest of the tab is for game packs only: Setup options, the questions the room owner answers once for the whole room, and Lobby requirements, what each player has to choose before the table opens. Problems are shown under the row and counted on the tab.

Setup options

Each row is one control the room owner sees under Game options in the lobby, before pressing Start: a board size, a scoring rule, a house rule switched on or off. An owner who changes nothing leaves every option at its default. Your scripts read the answers: world.getSetupOptions() in a table script, or the third argument of setup(api, manifest, options) in a mod entry script. Every field writes the manifest's setupOptions. Add an option adds an on/off switch, off by default, which is valid as it stands; a game may offer at most 12.

Field Writes What it does
Key key The name your script reads the answer by: lowercase snake_case, unique in the pack. Players never see it.
Label label The caption beside the control in the lobby.
Help help One optional line under the control.
Control control On / off, A choice from a list, A number or Text. Changing it keeps what still applies and resets the default to one the new control can hold.
On by default default On / off only: whether the switch starts on.
Choices options A choice from a list only: one row per choice, a value your script reads (small) and a label the owner sees (Small board). Add a choice adds one (at most 32). Renaming the default choice's value renames the default with it; removing it makes the first remaining choice the default.
Default default The answer before anyone chooses: a choice, a number or text, matching the control.
Lowest, Highest, Step min, max, step A number only. Leave a box empty for no limit. A step of 1 keeps the answer a whole number.
Longest maxLength Text only: the most characters the owner may type. Zero means no limit beyond 2000.

The form checks each row with the same rules publish uses: a duplicate key, a default outside the bounds or not among the choices, or a setting that does not belong to the control is named under the row. A game with options but no script to read them gets a warning, because nothing would ever see the answers.

Lobby requirements

Every field below writes the manifest's lobbyRequirements or gameDecks.

Game decks file (one per pack, above the requirement rows) names the .json file of decklists the game ships — starter decks, prebuilt decks, decks for its bots. For example decks/game-decks.json. Every player can pick these without building a deck, the room owner can hand one to a bot in unranked games, and your scripts can read the file with world.readData. The form warns when the path is not a .json file or is not one of the pack's files yet: add it on the Files tab (load on demand is fine), because publish refuses an undeclared file. Leave it empty for none. The file format is under gameDecks.

Each requirement row has:

Field Writes What it does
Asks for kind What the requirement asks each player for. A deck is the only kind today.
Id id The key each answer is filed under: lowercase snake_case, unique in the pack. Players never see it.
Label label The caption above the picker in the lobby.
Help help One optional line under the picker.
Asked of appliesTo Everyone playing, or The host only.
Blocks Start required Off still offers the picker and loads the deck; it just does not stop the owner starting without an answer.
Deck sources deckSources The picker's tabs, in the order ticked: Yours, Community, Deck database and Game decks. At least one stays on. Game decks lists the decks in the game decks file and is the only pool a bot's deck can come from; ticking it with no file named above is flagged.
Database plugin, Listing function, Tab label deckDatabase Shown with Deck database ticked: the declared plugin and function that list the provider's decks.
Format formatId A format id from the pack's card schema that a chosen deck must be built for.
Fewest cards, Most cards minCards, maxCards The legal deck size. Zero means no limit.
Deck icon, Icon field, Icon map deckIcon A picture beside each deck; the field and map choose one per value (L=ui/side-light.png, D=ui/side-dark.png).
Decks must differ distinctBy No two decks at the table — players' or bots' — may share an icon value, for a game played side against side. Needs Icon field and Icon map.
May repeat distinctBy.except Shown with Decks must differ on: icon values two decks may share, comma-separated — N for Neutral.
Value names distinctBy.labels Shown with Decks must differ on: what each value is called when a pairing is refused, as L=Light Side, D=Dark Side.

With Decks must differ on, the lobby greys out a deck that would clash, the room owner cannot give a bot one, and Start is refused while two decks clash. A deck whose value is unknown — a player's own saved deck carries no side — is left to your game's script to check at the table.

Mod Details: the Files tab#

The Files tab lists every file in the project and what publishing does with it. The list keeps itself up to date: adding, moving or deleting a file anywhere in the editor updates the manifest for you, because the manifest's assets is recomputed from the file tree on every save and again at publish. There is no checklist to maintain. The two things left to decide here are whether a game file is pre-loaded, and whether a file should exist at all.

Every file is in one of four states:

State Means
Pre-loaded Listed in assets. Fetched, size-checked and hashed when the pack is registered — so a broken file is a rejection you see at publish time — and downloaded by players before the table opens. Every table asset starts here automatically
On demand A game file you switched Pre-load off for. Saved in the manifest as excludedAssets. Still published and still works; it is fetched the first time something uses it, unverified. Worth it for a large file most sessions never touch
Entry The manifest, the scene and the script. Loaded first, on their own; chosen on the Gameplay tab. Cannot be deleted from here
Editor-only Thumbnails, original uploads, a deck's per-card source images, photo-mode captures, library link records, rulebook pages, and file types that are not table assets. Pushed to your repository so the project can be re-opened and re-edited, but never pre-loaded, so they can never be declared. Each row says which of these it is

Pre-loaded and On demand rows carry the Pre-load checkbox; that checkbox is the only manual edit to the file list that survives a save. A summary line above the list counts each state.

Finding a file. The list is a collapsible folder tree with a Filter by path… box, and five views, each with a count:

View Shows
Game files (default) What players download — pre-loaded, on-demand and entry files. Editor-only files are left out so several hundred thumbnails are not the first thing you scroll through
On demand Files you chose not to pre-load
Editor-only Thumbnails, originals, card sources and the rest of that state
Cleanup Leftovers, and files nothing seems to use — see below
Everything Every file in the project

Deleting. Any file except an entry file has a delete button on its row. It is a two-step inline confirm (Delete / Keep), and it goes through the editor's ordinary delete — the same one the asset explorer uses, so companion files and the manifest are kept in step. A whole-folder delete is offered only in the Cleanup and Editor-only views; in Game files it would be one slip from deleting assets/.

Cleanup separates what is certain from what is a guess:

  • Leftovers are certain: the card images and sheets of a deck that was deleted, and thumbnails whose source file no longer exists. Nothing uses them, but they are still published with your pack. Delete N leftover files removes them all, after the same confirm.
  • Scan for unused files is a best guess, and the panel says so. It reads your scene (including edits you have not saved yet), decks, scripts and glTF models, and lists the images, models and sounds that none of them name. It only judges binary assets — JSON and text files are loaded by convention too often for a text search to see — and it never judges media/, the folder of a deck that still exists, an entry file or an editor-only file. A file your script loads by a name it builds at runtime will look unused, so check before deleting. Flagged rows read No reference found.

Where are my materials? Materials, prefabs and table scripts are not files. They are stored inside the scene (setup.json) and ship with it, so they never appear in this list — only the textures a material uses do.

If the manifest declares a path that does not exist, an alert at the top of the tab lists it. Saving the draft clears a stale assets entry on its own (Remove does it immediately); a missing entry point is never removed for you — fix that one on the Gameplay tab.

Below the list, Serves art from declares the outside GitHub repositories the pack reads art from — see Art in somebody else's repository.

Mod Details: the Plugins tab#

Everything the pack has to do with plugins is one list. (Attaching a plugin and answering its settings used to be two sections on two surfaces, which read as two different plugin systems.)

  • In this pack (N) — one card per plugin the pack uses. A card shows the plugin's capability badge, Functions this game may call (a checkbox per function; these become the manifest's plugins and keep the plugin-call capability in step), a Settings form built from what the plugin declares (your answers become pluginSettings), and Details, which shows the plugin's attribution, the origins it reaches and a ready-to-paste api.callPlugin snippet. One Remove drops the attachment and the settings in a single write.
  • Plugin registry — search registered plugins that are not in the pack yet. Add to game attaches the plugin with its callable functions ticked. Configure only (offered when the plugin declares settings) records settings without attaching it, for a plugin used as a deck source that your script never calls; the card then reads Configured only — this pack's script cannot call it, with Add it to the game beside it.

Adding a plugin here does not switch it on at a table — a table's owner still chooses that in Settings ▸ Room ▸ Plugins at the table. How the call itself works: Calling a plugin from a mod.

Mod Details: the Credits tab#

Where the pack's files came from, recorded when each file was imported, plus what it inherits from the packs it depends on. A summary line at the top counts the credits, the files they account for, and the files not yet accounted for. The list below it is the same view the pack's public page shows.

Edit credits opens the credits editor, to group files into one credit or correct an entry; an Edit button on each of your own entries opens it on that entry. Anything that changes what a credit says must be signed again. Files with no credit are listed but never block a publish. Field by field: credits.

Credits an AI agent attested. When an AI agent answered the import credit question for you, its entry carries an AI-attested · unreviewed chip and is unreviewed until you sign it. While any is waiting, the Credits tab's count shows how many (in place of the uncredited-file count), and a review panel sits at the top of the tab. It lists each such entry with what the agent recorded: the files, origin, creator, licence, source address, the fetched file's final address, sha256 and size for a web download, the agent client, and the time. Under each entry is the full statement you are signing for its origin, at today's wording, the indemnity included. Tick each entry you have checked (or Select all), type your name once, and Sign reviews signs every ticked entry and saves the draft. A signed entry's chip reads AI-attested · reviewed.

  • Publishing is refused while any entry is unreviewed, by the server as well as the editor — see Credits an AI agent attested must be reviewed.
  • Only a person can review. The review controls are not available to an agent, and the review is refused if anything other than your own click triggers it.
  • Re-signing an AI-attested entry in the credits editor also counts as reviewing it; the editor marks such an entry Signing it counts as your review once your change needs a signature. An agent edit that needs a signature makes the entry unreviewed again.

What you are signing, and why an older editor tab refuses these entries: Credits an AI agent attested.

The Variants dialog#

Mod ▸ Variants…, or the Variants button on the logo bar. Game packs only. It answers the two questions the variant controls cannot: what variants are there, and what will a player see? and what does this one actually change?

Everything in it applies the moment you change it and is undoable, so there is no Save button and closing abandons nothing. Escape, Close or a click outside the dialog closes it.

With no variants yet, the dialog explains what one is and offers a name field and Create a variant. Creating your first variant does two things at once: the scene you have now becomes a variant called Standard — the base — and the new variant starts as a copy of it. The editor switches to the new one.

With variants, top to bottom:

Control What it does
Variant Which variant the rest of the dialog describes. Entries are marked base and lobby default where they apply. Choosing one here does not change what the editor shows.
Edit this variant Switches the editor to the variant selected in the dialog. Reads Editing now when it already is.
Name field and New variant from variant Adds a variant that starts as a copy of the one selected in the dialog, and switches the editor to it. A blank name becomes New variant. Disabled at 12 variants.

Under What players see — the half a lobby reads, stored in the manifest's variants list:

Field Notes
Name What the lobby's dropdown shows. Up to 60 characters. Renaming never changes the variant's id, which is set once when the variant is created.
Description One optional line under the lobby's dropdown. Up to 240 characters.
Own player range Off: the variant uses the game's range from Mod Details, and the dialog says which. On: Min and Max appear (1–64) and this variant seats that range instead.
Rules enforced Off by default (its hover card reads "Fully scripted"). On marks the variant as one whose scene script enforces the rules and reports the result with match.end, writes rulesEnforced, and offers ranked play: the Ranked play section below appears with every setting at its default. Off removes both. It does not decide which scripts run; that is the variant's scene (its Scene scripts row, and each entity's script).
Lobby order The variant's position in the lobby's dropdown, with up and down arrows. The first variant is the lobby's default.

Under What variant changes — the half stored in the scene:

Row Reads Action
Entities Same as the base, or counts such as 2 added · 1 changed · 1 removed Added and changed entities are marked in the Hierarchy while you edit the variant; revert them from the Inspector's Variant row.
Table & room, Seats & zones, Snap points, Scene scripts Its own, or Same as the base Use base's drops this variant's own copy of that group, so it follows the base again.
Removed from variant A list of the base entities this variant does not have Restore brings the chosen one back into this variant.

A variant that changes nothing says so — "Nothing yet — 9×9 is identical to Standard" — and that is a legitimate finished state for a variant that differs only in what players see (its name, its player range, Fully scripted).

Ranked play

Shown under Fully scripted while it is on. It writes the variant's ranking block; what the settings mean for players is on Ranked games, Rankings and Player Trust.

First, a checklist, worked out live from the scripts this variant attaches:

  • Match end — whether an attached script calls match.end. Without one, a ranked variant will not publish (ranked-variant-no-match-end).
  • Rules kernel — whether a const kernel was found, so the other players can check results by replaying the moves. A warning only when Require kernel is on and none was found.
  • Any ranked-variant-bad-config problem (a ranked variant that can start with one player, two variants on one ladder that disagree), and the teams refusal below.

Then the settings:

Field Default Notes
Offer ranked play On Off keeps the settings but offers casual play only.
Placement games 5 3–25. Ranked games before a player's Score is shown publicly.
Ladder (pool) The variant's id Variants with the same ladder share one set of Scores. Blank means this variant's own.
Season 1 Start a new season begins a fresh ladder once you publish; the old season stays readable.
Rank Seats Teams cannot publish yet, because seat teams cannot be declared (ranked-variant-teams-undeclared).
Offer draw button Off Whether players get Offer draw during a ranked match.
Allow takebacks On Whether players may ask for a takeback (every human must agree).
Require kernel Off Only matches started with a rules kernel are ranked.
Minimum moves 2 0–500. Kernel matches with fewer moves end as no contest.
Minimum seconds 30 0–3600. Shorter matches end as no contest.
Reconnect grace (seconds) 90 15–600. How long a disconnected player has before they forfeit.
Rank matches with bots On Whether matches with bots are ranked, for the people and the bots.

For the base variant this section is replaced by a note: its scene is the game, every other variant is recorded as what it changes about this one, and it is what a copy of DiceyTable that has never heard of variants will load.

At the bottom:

Button What it does
Make this the base Makes the selected variant the scene every other variant is recorded against. What each variant plays does not change — only which one is stored whole. Not offered on the base itself.
Delete variant Asks first. Deletes the variant and everything it alone changes; the other variants are not affected. Deleting the base makes another variant the base first, so nothing else is lost. Deleting down to one variant returns the game to having one way to play: the survivor's scene becomes the game and the variant list is removed.

The base and the lobby default are separate things, and the dialog labels both. See The base is not the default.

Collections#

Game Editor only (Mod ▸ Collections…). Opens the Collections dialog, where a collection — a named bundle of mods that share one table — names the single member that supplies the room and the table. Every other member's room and table are ignored, and the dialog marks each of them so.

It is absent from the pre-mode editor (/editor) entirely, along with the registry request behind it.

Full walkthrough, including the four outcomes and why the provider is never chosen for you: Collections: which mod supplies the room and the table.

Screenshots#

View ▸ Screenshots…, listed wherever Preview is (so Room and Table packs get a screenshots gallery too). It opens the Screenshots gallery: every capture you took in Preview's photo mode, saved under the mod's screenshots/ folder. Disabled with no project loaded.

Help#

Item Opens
Developer Docs /docs
Editor Guide /docs/editor
Scripting API /docs/scripting-api
Keyboard Shortcuts /docs/editor/keyboard-shortcuts
Menus & Topbar This page
Connect AI agent… The consent dialog that pairs an AI agent (through the DiceyTable MCP bridge) with this tab: you type the pairing code your agent shows you. Nothing agent-related runs until you open it. While an agent is connected, an Agent connected: client indicator at the bottom-left of the viewport offers Pause, Disconnect and Activity…, and other players see an AI badge beside your name. See Pairing a tab.
Disconnect AI agent Listed only while an agent is connected to this tab. Ends the agent session and detaches every tab paired with it, the same as Disconnect in the indicator's menu. Pairing again needs a new code.

Every documentation item is a real link that opens in a new tab (target="_blank", rel="noopener noreferrer"), so reading the docs can never navigate away from the tab holding your unsaved draft.

What the topbar and menus write#

Control Written where
Edit ▸ Undo / Redo The scene draft, the draft label, the manifest text, the table pack and the room decor, in memory; the history stack to localStorage
Edit ▸ Copy / Paste / Duplicate / Delete / Rename The scene draft, in memory until Save Draft
Save Draft The server draft (PUT /api/editor/projects/{id}/draft)
File ▸ Export Project JSON Nothing — read-only download
File ▸ New Mod… / Open Project… See Opening Projects
File ▸ Preferences… Your per-user preferences (editorUnits), plus a localStorage mirror. Never the mod — see Preferences and Display Units
Mod ▸ Mod Details… The draft manifest text, in memory until Save Draft (closing the tab saves). Deleting a file from the Files tab deletes it from the local draft tree
Variant (logo bar) Nothing in the mod. Which variant you last had open is kept in this browser's localStorage
Changes apply to (logo bar) Nothing by itself — it decides whether your next edits are written to the base scene or to the variant's own differences
Mod ▸ Variants… The manifest's variants list and the scene's variants block, in memory until Save Draft. An action that changes both (create, delete) is one undo step
Preview The server draft (it saves first). The preview tab itself writes nothing to the draft
View ▸ Screenshots… screenshots/ and media/ in the local draft tree, depending on the action — see Screenshots
Publish Your GitHub repository, via the publish flow
View ▸ Auto Bake Your per-user preferences (editorBake), plus a localStorage mirror. Never the mod
View (tools, Frame Selection, Orthographic View, Bake Static Lighting, Problems), Help, Exit Nothing

Did this page answer your question?