# Screenshots: status and how to add real ones

This documentation ships with **placeholder mockups** for every screenshot it
needs. Each mockup is a labeled SVG showing rough layout and what to
capture. A **sync script** owns every screenshot slot and regenerates it from
the files in `_static/screenshots/`: you never hand-edit the `.md` files.

## How a screenshot slot is written

Every screenshot lives inside a marked block in its page's source:

```text
<!-- shot:control-panel-overview -->
```{image} ../_static/screenshots/shot-control-panel-overview-mockup.svg
:alt: control panel overview (placeholder mockup)
:width: 100%
```

Save the real screenshot as: `shot-control-panel-overview.png`

```{image} ../_static/screenshots/shot-control-panel-overview.png
:alt: control panel overview (real screenshot)
:width: 100%
```
<!-- /shot -->
```

The `sync_screenshots.py` script owns everything between `<!-- shot:NAME -->` and
`<!-- /shot -->` and rewrites it every run based on what exists in
`_static/screenshots/`. Between runs, source control should hold only the two
markers. The content inside is always regenerated, so it is
safe to run the script as many times as you like.

## Naming convention

```text
_static/screenshots/shot-<name>-mockup.svg   ← generated placeholder (always present)
_static/screenshots/shot-<name>.<ext>        ← your capture (drop in to replace)
_static/screenshots/shot-<name>-real.<ext>   ← same thing, "-real" suffix also accepted
```

`<ext>` is any of `png`, `jpg`, `jpeg`, `webp`, `gif`.

## Two modes

### Dev mode (default)

Meant for **while you're still working on captures**: trying a few candidates,
comparing against the brief, deciding if a shot needs a retake:

- The mockup SVG is **always shown**, even after a real screenshot exists, so the
  capture instructions never disappear.
- If a real screenshot also exists, it's shown right below the mockup, so you can
  compare the two directly.
- The exact filename to save the screenshot as is printed as **plain, copyable
  text** (`` Save the real screenshot as: `shot-<name>.png` ``) not locked inside
  the SVG, so you can select and paste it into a "Save As" dialog.

```bash
cd Docs/sphinx
python sync_screenshots.py
```

### Final mode (`--final`)

Meant for a **release build**: only real screenshots ship, nothing that says
"SCREENSHOT NEEDED":

- Only the real screenshot is kept, full width, no mockup, no filename hint.
- A slot with no real screenshot yet is left **empty** (nothing renders), so a
  release build never ships a mockup or a "needed" banner.

```bash
cd Docs/sphinx
python sync_screenshots.py --final
```

Switching back and forth between the two modes is lossless: the block markers
don't go anywhere, so running the script without `--final` again restores the
mockup and filename hint for anything still missing a real capture.

## Adding a real screenshot

1. Take the screenshot per the mockup's on-image instructions (crop to the
   relevant panel/viewport, no OS chrome).
2. Save it into `_static/screenshots/` using the exact filename printed under the
   mockup in dev mode (`shot-<name>.png` by default): **same folder**.
3. Rebuild with the single entry point, which runs the sync step automatically:

   ```bash
   cd Docs/sphinx
   python build_docs.py
   ```

   This always runs `sync_screenshots.py` first, then regenerates the Doxygen XML,
   then builds the HTML: one command, nothing to forget. Pass `--final` for a
   release build, `--skip-doxygen` to skip the slower C++ re-scan when only
   screenshots or prose changed, and `--open` to open the result when it's done.

   Or run only the sync step (and its automatic rebuild) without the Doxygen pass:

   ```bash
   python sync_screenshots.py
   ```

Run `python sync_screenshots.py --dry-run` first if you want to preview the
changes without writing anything, or `--no-rebuild` to apply without triggering
the Sphinx build.

## Removing a real screenshot

Delete the file from `_static/screenshots/` and re-run `python sync_screenshots.py`
(or `build_docs.py`). In dev mode the mockup and filename hint come back
automatically. In final mode the slot goes back to empty.

## Regenerating the mockups themselves

The mockups are generated by a separate script, not hand-drawn, so the whole set
can be regenerated or extended in seconds:

```bash
cd Docs/sphinx
python gen_placeholders.py
```

Edit the `placeholders` list in `gen_placeholders.py` to add a new shot: give it a
name, a title, the page/feature tag, a one-paragraph capture instruction, and
(optionally) rough mockup geometry. Then embed it in a page with a
`<!-- shot:<name> --><!-- /shot -->` block and run `python sync_screenshots.py`:
the script fills the block in from there.

## Automatic capture via Unreal MCP (optional, faster)

Unreal Engine **5.8** ships Epic's own **experimental MCP server plugin**,
embedded in the editor process, exposing editor control (spawning actors, PIE,
screenshot capture, Slate widget inspection) to MCP-compatible tools over local
HTTP.

```{note}
A stdio-only MCP client cannot talk to it directly: Epic's plugin serves over
**HTTP**. Two ways around that:
```

- **Use a stdio-bridge plugin** that wraps Unreal's editor API as a
  stdio MCP server, ex: `UnrealMCPToolkit` (GitHub) or
  `unreal-engine-mcp-server` (npm), both built on top of Epic's plugin/API.
  Install one of these instead of/alongside Epic's plugin, and a client can
  drive the editor, take real screenshots, save each file with the printed
  filename, then run `python build_docs.py`.
- **Enable Epic's plugin and expose its HTTP endpoint**, then drive it with raw
  HTTP calls, if the plugin's REST surface is documented and stable enough to
  script against.

Until one of those is wired up, the fastest path is: you take the real
screenshots by hand from the mockup instructions and the copy-pasteable filename,
drop them in, and run `python build_docs.py`.

## Current status

Real screenshots captured so far: `debug-overlay-tags-gates`. Everything else is
still mockup-only. Run `python sync_screenshots.py --dry-run` for the current
per-slot status, or search this doc site for "SCREENSHOT NEEDED" to find every
remaining one in dev mode.