# The Screenshots Gallery

> The gallery of Preview photo-mode captures stored under screenshots/ — download, delete, promote one to the store page or cover, or retake it.

- Source: https://diceytable.com/docs/editor/interface/screenshots
- Last verified: 2026-09-14

The Screenshots gallery (`ScreenshotsPanel.tsx`) lists every photo-mode capture you have taken in
[Preview](https://diceytable.com/docs/editor/workflows/preview-and-photo-mode). Open it from **View ▸ Screenshots…** in the
[menu bar](https://diceytable.com/docs/editor/interface/topbar#view). It appears in the
same places Preview does: the Full Editor (plain `/editor`), the Game Editor, the Room Editor and
the Table Editor.

Use it after a photo session to keep the good shots, delete the rest, and turn a capture into your
mod's cover or a store-page screenshot without leaving the editor.

## Where captures live

A Preview capture is an ordinary file in your mod, written by the editor tab that holds the
project's lease:

```
screenshots/
  20260914-153012-k3f9a1c2b7xq.png    ← the image (PNG or WebP)
  20260914-153012-k3f9a1c2b7xq.json   ← its sidecar
```

The name is `<yyyymmdd-hhmmss>-<id>.<ext>`. The timestamp is in **UTC**, so captures sort the same
on every author's machine; the gallery shows each one in your local time.

The folder follows the same rules as generated [thumbnails](https://diceytable.com/docs/mods/files/sidecars#baked-thumbnails-thumbnails):

- **Published and synced** with the rest of the mod. It is in your GitHub repository.
- **Never a declared asset.** `isDeclarableModAsset` excludes `screenshots/`, so a capture is
  never in `manifest.assets` and players never download one before a table starts. A folder of 4K
  PNG masters is exactly the download no player should pay for.
- **Never thumbnailed.** A capture already is a picture of the table.
- **Not `media/`.** `media/` holds the processed images the store page actually shows. A capture
  only reaches the store page when you promote it (below).

The folder stays visible in the [Asset Explorer](https://diceytable.com/docs/editor/interface/asset-explorer), so you
can also browse it there.

### The sidecar

The `.json` beside each image records how it was taken, which is what makes **Retake** possible:

| Field | Meaning |
|---|---|
| `version` | Always `1` |
| `camera` | `position` and `rotation` (Euler degrees), plus the vertical `fov` when known |
| `width`, `height` | The captured size in pixels |
| `tier` | The graphics tier it was actually rendered at: `ultra`, or `high` on a device detected as Low/Medium |
| `visibility` | The photo-mode [Visibility panel](https://diceytable.com/docs/editor/workflows/preview-and-photo-mode#the-visibility-panel) choices in effect |
| `capturedAt` | ISO timestamp |

### What the gallery lists

Only files that match the capture naming above become gallery entries. An image you put under
`screenshots/` yourself stays an ordinary file in the explorer and is not offered here, since it
has no camera to retake from. A sidecar whose image is gone is ignored.

## Using the gallery

Captures are shown as a grid, **newest first**. Click one to see it full size, with its file name,
time, and (from the sidecar) its size and tier. With no captures yet, the gallery says so and
offers a **Preview** button.

| Action | What it does |
|---|---|
| **Download** | Saves a copy of the image to your computer. |
| **Use as store screenshot** | Crops the capture to 16:9 from the centre, re-encodes it at the store screenshot size, and writes it to `media/` as the next `media/screenshot-N.webp`, then adds it to the manifest's `screenshots`. Disabled once the store page already has **12** screenshots; remove one in Mod Details first. |
| **Use as cover** | Crops the capture to a centred square and **replaces** the cover (`media/cover.webp` and `media/cover-thumb.webp`), then points `coverImage` at it. |
| **Retake** | Saves the draft and opens Preview with this capture's camera and visibility restored, straight into photo mode. Disabled when the capture has no sidecar. |
| **Delete** | Click once, then **Confirm delete**. Removes the image **and** its sidecar. |

**Promoting goes through the credit dialog.** Both *Use as* actions run exactly the pipeline Mod
Details uses: you are asked who made the image before anything is written (for your own capture,
answer that it is your own work). Cancelling writes nothing. The capture itself stays in
`screenshots/` either way.

**Save Draft after promoting.** The processed image is written to `media/` straight away, but the
manifest change (`screenshots` or `coverImage`) is a draft edit like any Mod Details change, and
the gallery tells you so: *"Save Draft to keep the manifest change."*

**Deleting is removed upstream on your next publish.** Delete uses the editor's ordinary file
delete, which records the removal for GitHub sync, so the files disappear from the repository the
next time you publish, not before.

**Read-only tabs.** If another tab holds this project's lease, the gallery still shows captures and
Download still works, but promote, Retake, Delete and the empty-state Preview are disabled.

## When a capture cannot be saved

The preview tab offers a Download whenever a capture does not reach this gallery. What happens to
it depends on why:

- **Could not save it yet** — this editor tab is read-only (it does not hold the lease), the
  project's local draft files are not open yet, or the write failed. The capture is **queued** in
  the preview's browser and imported the next time the project is opened in the editor.
- **Refused for good** — the image is empty or not actually a PNG/WebP, or its timestamp is
  invalid. It is not queued; the Download is the only copy.
- **Over 40 MB** — the preview never sends it at all (*"Too large to save into the mod"*). Capture
  at a smaller size to keep it in the mod.

Details: [Where a capture goes](https://diceytable.com/docs/editor/workflows/preview-and-photo-mode#where-a-capture-goes).

A capture that arrives twice (a retry, or a queued capture imported again) lands on the same path
and is not written a second time.

## See also

- [Previewing a draft and photo mode](https://diceytable.com/docs/editor/workflows/preview-and-photo-mode) — taking the captures
- [Cover art and screenshots](https://diceytable.com/docs/mods/files/media) — the `media/` folder the promote actions write to
- [Required and conventional files](https://diceytable.com/docs/mods/files/required-and-conventional) — where `screenshots/` sits in a mod
- [Where my files live](https://diceytable.com/docs/editor/workflows/where-my-files-live)
