Skip to main content

Auto-generated screenshots

The screenshots in these docs are not hand-captured — they are generated from Lua scripts so they stay in sync with the app as it changes. Each screenshot is a small, deterministic scene scripted with the same declarative and bearcad.ui.* API you'd use anywhere else, ending in a bearcad.ui.screenshot(...) capture.

How it works​

  • The scripts live in docs-site/screenshots/*.lua. Each builds a representative scene, sets a fixed camera (bearcad.ui.view(...)) so the output is reproducible, and captures a PNG.
  • Each script writes to the directory named by the BEARCAD_SCREENSHOT_OUT environment variable (falling back to the current directory), so the same script works both in the harness and when run by hand.
  • scripts/gen-doc-screenshots.sh builds the app, runs every script into docs-site/static/img/screenshots/, and fails if any expected PNG is missing or empty. Docusaurus serves that folder as /img/screenshots/<name>.png.
  • The generated PNGs are build artifacts — they are git-ignored, regenerated on demand locally, and regenerated by CI before the site is built and deployed.

Regenerating locally​

# Build the app and (re)generate every screenshot.
scripts/gen-doc-screenshots.sh

# Reuse an already-built binary (faster iteration):
BEARCAD_SKIP_BUILD=1 scripts/gen-doc-screenshots.sh

Capturing a screenshot needs a real rendered GPU frame. This works on a normal desktop (a machine with a working display/GPU) and on CI Linux runners that provide a software Vulkan driver under xvfb (mesa-vulkan-drivers + xvfb). In a fully headless environment with none of that, the capture never resolves and the per-script timeout force-exits with no PNG — so run the generator somewhere that can actually render.

Adding a new screenshot​

  1. Add docs-site/screenshots/<name>.lua. Build the scene, pick a fixed view, then bearcad.ui.screenshot((os.getenv("BEARCAD_SCREENSHOT_OUT") or ".") .. "/<name>.png").
  2. Run scripts/gen-doc-screenshots.sh to produce <name>.png.
  3. Reference it from a docs page with ![alt](/img/screenshots/<name>.png).