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:

<!-- 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

control panel overview (real screenshot) 

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.

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.

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:

    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:

    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:

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.