# Previewing a Draft and Photo Mode

> Play your unpublished draft in a preview tab that saves nothing, then use photo mode to hide the interface per category and capture Ultra screenshots.

- Source: https://diceytable.com/docs/editor/workflows/preview-and-photo-mode
- Last verified: 2026-09-14

**Preview** lets you play your unpublished draft at the real table, alone, without creating a room
or publishing anything. **Photo mode** hides the interface so you can frame a clean shot of the
table and capture it at the Ultra graphics tier. In Preview, those captures are saved into your
mod, ready to become its cover or store screenshots.

Photo mode is not editor-only. Every player can use it at a normal `/table`, where a capture is
simply downloaded.

## Previewing a draft

### Opening Preview

Click **Preview** on the [topbar](https://diceytable.com/docs/editor/interface/topbar#preview) (Full Editor, Game Editor,
Room Editor or Table Editor). The editor saves every dirty editor tab, saves the draft, and opens
the preview in its own tab at `/table?preview=<projectId>`. Clicking again reuses that tab and
reloads it.

Preview **saves first on purpose**: the preview then shows exactly what Publish would ship, rather
than something in between.

**A game with variants previews the variant on screen.** Whatever the top bar's
[Variant](https://diceytable.com/docs/editor/interface/topbar#the-variant-controls) control shows when you click Preview
is the variant the tab opens, carried in the URL as `&variant=<id>`. To check another variant,
switch to it in the editor and click Preview again — the same tab reloads on that one. A preview
URL with no `variant` opens the game's first declared variant, exactly as a room whose owner never
chose one would. Each variant previews with the scripts its own scene attaches.

### Previewing a room pack or a table pack

A room pack and a table pack are each **half** of a table, so previewing one stands it next to the
other half. The picker beside **Preview** chooses which half that is, and your pack is then loaded
the way a game loads it at play time: as an *assigned pack* of a throwaway scene, composed by the
same code that composes a published one. Nothing else is on the table — no pieces, no seats, no
game — so what you are looking at is your pack and only your pack.

| Previewing | Picker | Options | Default |
|---|---|---|---|
| A **room** pack | *with* | The default table (Square Table), any published table pack, **No table**, or a published **game** | The default table, Square Table |
| A **table** pack | *in room* | The default room (Modern Room), or any published room pack | The default room, Modern Room |
| An **asset** pack | *in room* and *on table* | The default room and table (Modern Room and Square Table), or any published room/table pack | Modern Room and Square Table |

An asset pack is not half of a table — it has no other half to stand next to, it has **both** — so
it gets the two pickers rather than one, and they set what its own editor viewport stands your
pieces in.

The first time you are asked is in the **create dialog**: the step after choosing what you are
making offers exactly the room and/or table the kind can use. Whatever you pick there is what the
pickers start on, and you can change it at any time.

Three things follow from this being a composition rather than a special renderer:

- **It is the real thing.** If your pack composes here, it composes when it is published; if a
  reference is missing or a document is malformed, the preview refuses in the same words the play
  path would use.
- **The pick is never published.** It is remembered against your project, in your editor workspace,
  and it travels to the preview tab in the URL (`&with=…`) — but it never enters your pack. A room
  pack that recorded which table it likes *in its own document* would be a room pack assigning a
  table, which the play path refuses outright, because a pack must not be a second writer for a
  subject it does not own. So the choice follows **you**, not the pack: nobody who installs your
  room gets your preview table with it.
- **The document must be current.** The preview reads the pack document your draft actually holds.
  A project last saved before the pack-document format existed is refused with *"open it in the
  editor and save once"* — publish would ship those same bytes.

**No table** hides the table; it does not remove it. The physics table is still there, so nothing
falls through the floor — it is simply not drawn, exactly like the editor's own render-layer
toggles.

### Previewing a room with a whole game

An empty table in a finished room tells you very little. What a room is actually judged on — does it
read at playing distance, is the light right over the surface, does the wall art compete with the
cards — needs the cards. So a **room** pack may be previewed with a published **game** instead of a
table, listed under **Games** in the same picker.

This is the same choice as picking a table, so picking one clears the other: a room has one thing
standing in it.

When you pick a game, the load **inverts**. Everywhere else your draft is the thing being loaded and
the companion is assigned to it; here the published game is loaded exactly as a player loads it —
its own document, its own pieces, its own repository's files — and **your draft stands in for its
room**. Concretely:

- **Your room replaces the game's room.** If the game assigns a room pack, or authors a room in its
  own document, that room is set aside and yours is used; the status line says which. Nothing else
  about the game is touched.
- **The game keeps its own table.** Its table is part of the set-up you asked to see, and its pieces
  were authored against that surface height. You do not get to override it, and your own table pick
  is ignored while a game is selected.
- **Nothing runs.** The game is *set up* and then left alone: no table scripts, no mod script. You
  are reviewing a room, not playtesting somebody else's game, and a script that deals a hand or
  moves pieces would keep rearranging the thing you are lining a camera up against. The seat ring
  still appears, because that is scene shape rather than behaviour.
- **A game that cannot load degrades.** If it cannot be fetched, or was published without a scene
  document, the status line says so and the room is shown on its own table instead. Your room is
  perfectly reviewable without it, so this is never an error card over a draft you can still work
  in.
- **The pin follows the live record.** A game's `/artifact` is always its currently published
  version — there is no way to fetch an older one — so if your pick names a version the publisher
  has since moved past, the status line names the version you are actually looking at.

The same game also appears in the **editor viewport**, not just the preview tab, so you can author
against it directly. There it is **scenery**: every piece is locked so nothing drifts as you work,
none of it appears in the Hierarchy, none of it can be selected or moved, and none of it is ever
written into your pack. A room pack that shipped another game's cards would be republishing somebody
else's mod.

### What the preview loads

The preview tab runs the **same table app** players use, through the same load path a published
mod takes. Only the source of the files differs:

| Part | Comes from |
|---|---|
| Manifest and setup scene | Your **saved** server draft. Only the owner can load it; anyone else gets *not found*. |
| Entry script | Your local draft files when present, otherwise the server draft |
| Models, textures and other files | Your local draft files, opened **read-only**. A file missing locally is fetched from your linked repository's `wip` branch; with no linked repository it keeps its placeholder. |

**The preview can never change your draft.** Its view of your files has no write, move or delete,
and it takes no editor lease.

### What the preview refuses

Before anything runs, the draft goes through the checks Publish would apply later:

- **Draft validation** (`validateLocalModProjectDraft`). An invalid draft does not load.
- **The script scanner** (`scanModScriptSafety`) on the entry script that would actually run. A
  script the [publish scanner would reject](https://diceytable.com/docs/mods/scanner/what-gets-rejected) does not run.

A refusal is shown in the preview banner, and each individual problem is logged to the browser
console. The sandbox itself is unchanged: a script that passes runs under exactly the rules it
would at a live table.

Findings that do not stop the preview are listed **under the banner text** as well (the first
three, then "and N more"), and recorded in the tab's diagnostics so an AI agent sees them with
`diagnostics_get`:

- a validation **warning** on the draft — for example a scene script with no compiled body, or a
  variant problem;
- **No scene script runs** — scripts are attached but none has compiled output yet. Open each one
  in the code editor and save to compile it;
- **A script is attached but not in this scene's script library** — an entity's or the scene's
  attachment names a script id that no longer exists.

The same lines also appear in the Activity Log's **System** tab.

### What the preview never saves

The banner says it plainly: **"Preview — unpublished draft. Nothing here is saved."**

A preview is a peerless offline session. It is not a room, so it never:

- autosaves the table (to the server or locally), or overwrites a solo offline save;
- restores a previous autosave;
- records a play in the mod's play stats;
- sends a room load report;
- joins or creates a room, sends invites, or triggers push notifications — a `room` in the same
  URL is ignored;
- uploads or stores a named table save.

**Plugins are unavailable.** No plugin is installed in a preview, so `api.listPlugins()` answers
`[]` and `api.callPlugin(...)` answers `not-found`, the same answer as a table without that plugin.
A console notice says so. Publish the mod and play it at a table to use its plugins.

### The banner

Under its text the banner lists any findings from the load (see
[What the preview refuses](https://diceytable.com/docs/editor/workflows/preview-and-photo-mode#what-the-preview-refuses)); it has no list when there are none.

| Button | Does |
|---|---|
| **Reload preview** | Reloads the tab, reading the **saved** draft again. It does not save the editor: save there first (or click Preview again). |
| **Back to editor** | Switches to this project's editor tab when it is still open, instead of opening a second editor on the same files. If there is none, it opens `/editor?project=<projectId>` in a new tab. |
| **Photo mode** | Enters photo mode (below). |

## Photo mode

### Entering and leaving

| Where | How |
|---|---|
| Preview | The banner's **Photo mode** button |
| `/table` | The **Photo** toolbar button (camera icon), available to hosts, players, spectators and offline tables |
| Either | `Shift`+`P` |

Leave with **Exit** in the panel, `Esc`, or `Shift`+`P` again. Photo mode will not start while a
dialog is open, and it is not available inside a VR session (starting one leaves photo mode).

While photo mode is on:

- **all interface panels are hidden** — toolbars, the hand drawer, toasts, banners, mod screen UI —
  and the table fills the window;
- **picking up, flicking, drawing, stamping, selecting, context menus and hover tooltips are
  suspended**, so a stray click cannot move anything;
- **the camera still moves** exactly as usual, so you can frame the shot.

Photo mode is purely local. Nothing about it is sent to other players, and it does not change the
table.

### The Visibility panel

The panel on screen in photo mode chooses, per **photo-mode category**, what stays visible. Its
rows are generated from the shared category list (`PHOTO_MODE_CATEGORY_DESCRIPTORS` in
`packages/shared/src/photoMode.ts`), so the table below is the complete set. Hover a row in the
panel for its description.

| Group | Row | Shows | Default |
|---|---|---|---|
| Interface | **Interface panels** | Toolbars, hand drawer, toasts and banners. | Always hidden — never in a capture (the row is disabled) |
| Interface | **Mouse cursor** | Keeps the pointer visible in the live view. The cursor is never in a capture. | Hidden |
| Selection & tools | **Selection outlines** | Selection and hover-highlight outlines around pieces. | Hidden |
| Selection & tools | **Transform gizmos** | Move, rotate and scale handles. | Hidden |
| Selection & tools | **Editor helpers** | Light helpers, table and model gizmos, room placement guides. | Hidden |
| Selection & tools | **Drag ghosts** | Group drag previews and the drop indicator. | Hidden |
| Selection & tools | **Tooltips** | The in-world object info tooltip. | Hidden |
| Seats | **Seat areas** | The coloured seat zone boxes. | Hidden |
| Seats | **Seat labels** | Seat names and claimed-seat usernames. | Hidden |
| Seats | **Hand zones** | Hand-type seat zones. | Hidden |
| Table guides | **Snap points** | Snap point markers and the snap-grid ghost. | Hidden |
| Table guides | **Zones** | Table zone visuals and the play-area guide. | Hidden |
| Table guides | **Vector lines** | Lines drawn with the vector line tool. | Hidden |
| Table guides | **Debug overlays** | Collider, rigid-body, trigger and player-zone debug drawing. | Hidden |
| Presence | **Presence avatars** | Other players' VR avatars and name tags. (DiceyTable has no remote cursors today.) | Hidden |
| Game content | **Mod in-world UI** | Buttons, panels and text a mod places in the world. | Visible |
| Game content | **Text labels** | Text labels placed on the table. | Visible |
| Game content | **Decals** | Stickers and decals on pieces and the table. | Visible |

In short, the defaults hide every overlay and keep the game's own content. Toggling a row takes
effect immediately in the live view. **Reset to defaults** puts every row back.

With **Mouse cursor** off, the pointer disappears after 1.5 seconds without movement over the
table and comes back when you move the mouse. With it on, the pointer stays. It never reaches a
capture either way.

### Getting the panel out of the way

- The panel **hides itself 3 seconds** after the pointer leaves it (or after it opens with the
  pointer elsewhere). It stays while the pointer is over it or a capture is running.
- Dismiss it with its **✕** or `H`.
- Bring it back with `H`, or by moving the mouse to **any edge of the screen**.

So you can compose a completely clean live view, then capture with `Enter`.

### Remembered choices and presets

Your last visibility choice is **remembered per user, per device** (browser `localStorage`, key
`diceytable.photoMode.v1.<your user id>`, or `anon` when signed out) and shared between Preview and
`/table`. It is not synced to your account.

**Presets** save the current rows under a name, up to **8** per user and device, with names up to
40 characters. Click a preset to apply it, or its delete icon to remove it. Saving under an
existing name (case-insensitive) updates that preset. A ninth new preset is refused until you
delete one.

If the browser blocks storage (some private modes), choices still work for the rest of the session.
A category added in a later release simply takes its default.

### Capturing

Pick a **Size** and **Format** in the panel's Capture section, then press **Capture** or `Enter`.

| Size | Pixels |
|---|---|
| **Screen × Ultra** (default) | Your window size × Ultra's supersampling ratio, `min(devicePixelRatio × 1.5, 2.5)`, but never more pixels than 4K (3840 × 2160, about 8.3 MP). A larger result is scaled down with its aspect ratio kept. |
| **1080p** | 1920 × 1080 |
| **1440p** | 2560 × 1440 |
| **4K** | 3840 × 2160 |

A fixed size shows a framing guide at that aspect ratio. The camera keeps its vertical framing, so
a size whose aspect differs from your window shows more or less at the sides. **Format** is PNG
(default) or WebP.

A capture:

1. switches to the **built-in Ultra tier** (High on a weak device, see below) and renders the
   camera at the chosen size;
2. lets the scene settle (loading, shadows, reflections, anti-aliasing), showing its progress;
3. **reads the rendered frame** and encodes it;
4. **restores your own graphics settings exactly**, even if the capture fails.

**While a capture runs, photo mode is locked.** Exit, the category rows, Reset to defaults, the
presets, the Size and Format pickers and every photo-mode shortcut (`Esc`, `Shift`+`P`, `H`,
`Enter`) do nothing until it finishes. If photo mode ends anyway (for example, a VR session
starts), the capture is abandoned and your settings are restored.

What you see is what you get, with the current visibility rows applied. **The panel, the framing
guide, toasts, the cursor and every interface panel are never in a capture**: the image is read
from the rendered table, never from the page, so no interface element can appear in it, whether it
is on screen or not.

**Limits and safeguards:**

- Any size is shrunk, keeping its aspect, to the largest image your graphics device can render; the
  result message says *"clamped to W×H by this device"*.
- On a device whose **detected** graphics tier is **Low or Medium** (whatever tier you have chosen
  in Settings), a capture renders at **High instead of Ultra** and never turns on soft shadows the
  device was not already using, because that can hang a weak GPU. The size is also capped at 1× the
  screen: *Screen × Ultra* renders at your window's size, and a fixed size is shrunk to your
  window's longest side. The panel shows a warning, and the Preview sidecar's `tier` records the
  tier actually used.
- **In a live room, 4K asks first**, because rendering a 4K Ultra frame briefly loads your GPU and
  the other players may notice a short stall.
- **The simulation is never paused in a room.** Only a Preview, or an offline table that is not in
  any room and has no one connected, holds the simulation still while the capture settles. Anything
  in motion, such as a rolling die, carries on with the same velocity afterwards. A host captures
  live even when the room is momentarily empty.
- A capture is cancelled, and your settings restored, if the tab is hidden, the graphics device is
  lost, photo mode ends, or it takes too long (try a smaller size).

### Where a capture goes

| Where you are | Result |
|---|---|
| **`/table`** | A **browser download** named `diceytable-<mod slug>-<yyyymmdd-hhmmss>.<png\|webp>` (your local time). Nothing else: nothing is uploaded, and nothing is written to a repository or to browser storage. |
| **Preview** | **Saved into your mod** as `screenshots/<yyyymmdd-hhmmss>-<id>.<png\|webp>` plus a `.json` sidecar, by the editor tab that holds the project's lease. The message reads *"Saved to screenshots/…"*. |

In Preview, a capture is never silently lost. Every outcome other than *Saved* offers a
**Download**:

| What happened | Result |
|---|---|
| The editor received it and saved it | *"Saved to screenshots/…"*. The editor confirms receipt first, then writes, so a large image does not time out while it is being saved. |
| No editor tab answered within 3 seconds, or the editor **could not save it yet** (still loading the project's files, read-only because it lost the lease, or the write failed) | **Queued** in this browser and imported the next time you open the project in the editor, which reports *"N screenshots imported from Preview."* Download offered. If even queueing fails, the Download is the only copy, and the message says so. |
| The editor refused it **for good** (the image data is empty or not a valid PNG/WebP) | An error naming the reason, with Download. It is not queued, since it could never be imported. |
| The image is over **40 MB** | *"Too large to save into the mod"*, with Download. It is never sent to the editor or queued; capture at a smaller size to save it into the mod. |

The queue keeps captures for at most **30 days** and at most **50** at a time across all your
projects; older ones are dropped first.

Manage, promote and retake captures in the [Screenshots gallery](https://diceytable.com/docs/editor/interface/screenshots).

### Retaking a capture

**Retake** in the gallery saves the draft and opens Preview at
`/table?preview=<projectId>&retake=screenshots/<name>`. Once the draft loads, the capture's sidecar
puts the **camera** and the **visibility rows** back and photo mode starts, so you can reshoot the
same composition after changing the scene. The restored rows apply to that session only: your
remembered choice is not changed until you toggle a row, reset or apply a preset yourself. If
the sidecar cannot be read, photo mode opens with your current settings instead.

## Common mistakes

- **Expecting Reload preview to show an unsaved edit.** It reloads the saved draft. Click
  **Preview** in the editor, which saves first.
- **Looking for a `/table` capture in `screenshots/`.** Only Preview captures are saved to a mod;
  a `/table` capture is in your downloads folder.
- **Expecting a capture to be on the store page.** `screenshots/` is not `media/`. Use **Use as
  store screenshot** or **Use as cover** in the gallery, then Save Draft.
- **Previewing the wrong variant.** Preview opens the variant the editor is showing, not the
  lobby's default. Switch the top bar's **Variant** control first.
- **Pressing `Enter` with a panel button focused.** `Enter` activates that button instead of
  capturing. Click the table or use the Capture button.

## See also

- [The Topbar](https://diceytable.com/docs/editor/interface/topbar#preview)
- [Making a variant of your game](https://diceytable.com/docs/editor/workflows/make-a-variant)
- [The Screenshots gallery](https://diceytable.com/docs/editor/interface/screenshots)
- [Keyboard shortcuts § Photo mode](https://diceytable.com/docs/editor/keyboard-shortcuts#photo-mode)
- [Where my files live](https://diceytable.com/docs/editor/workflows/where-my-files-live)
- [Required and conventional files](https://diceytable.com/docs/mods/files/required-and-conventional)
