[Visual Test] PPM screenshot capture is unsupported

[MichaelFisher1997]

Workflow run

https://github.com/OpenStaticFish/ZigCraft/actions/runs/29143688205

Relevant error output

build-output.log was expected in the workspace root but was not present in this diagnosis workspace, so the exact game stdout/stderr lines could not be quoted from the run log.

The only local runtime log was weston.log, which shows the compositor started normally and was later stopped:

[06:59:01.523] weston 14.0.1
[06:59:01.523] Command line: weston --socket=headless --backend=headless-backend.so --width=1280 --height=720
[06:59:01.527] Output 'headless' enabled with head(s) headless
[06:59:03.056] caught signal 15

The deterministic error emitted by the screenshot implementation for the described command -Dscreenshot-path=screenshot.ppm is:

screenshot: unsupported image path 'screenshot.ppm' (use .png, .jpg, .jpeg, .gif, or .webp)
SCREENSHOT: Failed to capture screenshot

Diagnosis

The described visual test requests screenshot.ppm, but the Vulkan screenshot writer does not support PPM output. captureScreenshot reaches writeImage, which calls detectScreenshotFormat; that accepts .png, .jpg, .jpeg, .gif, and .webp, and only .png is implemented. A .ppm path returns null, logs the unsupported-path error, returns false, and leaves no screenshot.ppm for later conversion/checking.

There is also a repository mismatch to clean up: the current workflow uses screenshot.png in .github/workflows/visual-test.yml:81, while the diagnosis prompt still documents screenshot.ppm in .github/prompts/visual-test-diagnose.md:7 and .github/prompts/visual-test-diagnose.md:42.

Origin

• modules/engine-graphics/src/vulkan/screenshot.zig:183 — writeImage
• modules/engine-graphics/src/vulkan/screenshot.zig:200 — detectScreenshotFormat
• modules/engine-graphics/src/rhi_vulkan.zig:409 — captureFrame
• src/game/app.zig:512 — screenshot capture call site

The headless swapchain path itself looks compatible with readback: modules/engine-graphics/src/vulkan_swapchain.zig:119 creates one offscreen image and includes VK_IMAGE_USAGE_TRANSFER_SRC_BIT at modules/engine-graphics/src/vulkan_swapchain.zig:139.

Suggested fix

Prefer one format consistently. The simplest fix is to use PNG everywhere and update stale prompt/docs/scripts to match the current workflow:

command: nix develop .#ci-graphics --command zig build run -Dscreenshot-path=screenshot.png -Dskip-present=true

If PPM output is still desired, add real PPM support instead:

const ScreenshotFormat = enum {
    png,
    ppm,
    jpeg,
    gif,
    webp,
};

fn detectScreenshotFormat(path: []const u8) ?ScreenshotFormat {
    if (hasExtension(path, ".png")) return .png;
    if (hasExtension(path, ".ppm")) return .ppm;
    if (hasExtension(path, ".jpg") or hasExtension(path, ".jpeg")) return .jpeg;
    if (hasExtension(path, ".gif")) return .gif;
    if (hasExtension(path, ".webp")) return .webp;
    return null;
}

Then route .ppm to a writePPM implementation that writes a binary P6 header and RGB rows using the same BGRA/RGBA channel handling currently used by writePNG.

[github-actions]

Triage

Classification: Bug + documentation drift. Report is accurate and reproducible against dev.

Validation against the current tree

• modules/engine-graphics/src/vulkan/screenshot.zig:185 emits exactly the unsupported-path error quoted in the issue (use .png, .jpg, .jpeg, .gif, or .webp).
• modules/engine-graphics/src/vulkan/screenshot.zig:200 detectScreenshotFormat only branches on .png, .jpg/.jpeg, .gif, .webp. No .ppm arm.
• modules/engine-graphics/src/vulkan/screenshot.zig:189-192 writeImage switch also routes .jpeg, .gif, .webp through unsupportedEncoder — only .png is actually implemented today.
• .github/workflows/visual-test.yml:81 already runs -Dscreenshot-path=screenshot.png, and the downstream check_screenshot, golden_diff, and upload-artifact steps (lines 93, 103, 113) all assume .png. The workflow is internally consistent.
• .github/prompts/visual-test-diagnose.md:7 and :42 still reference screenshot.ppm and "PPM via Vulkan" — stale.
• .gitignore:17 still lists screenshot.ppm — also stale (no longer produced).
• modules/engine-graphics/src/vulkan_swapchain.zig:139 retains VK_IMAGE_USAGE_TRANSFER_SRC_BIT, so readback is genuinely the only thing missing on the headless path.

Duplicates / related PRs

• No open PR addresses this.
• Closest history is [Visual Test] Menu screenshot capture failed #341 (closed during the original feature/visual-test-screenshot work in PRs feat: add screenshot capture and visual regression test workflow #340 and fix: use nix run for imagemagick in visual-test workflow #342). Not a duplicate.
• No duplicate open issue.

Scope — recommend splitting into two independent items

These have different blast radii and shouldn't land together:

1. Sync the prompt + .gitignore to PNG (docs-only, low risk). Edits:

   • .github/prompts/visual-test-diagnose.md:7 and :42 — change .ppm to .png and drop the "PPM is then converted to PNG" sentence.
   • .gitignore:17 — remove screenshot.ppm (nothing emits it).
   • Keeps the visual-test CI on screenshot.png with no behaviour change.

2. Optional: real .ppm encoder (runtime change, gated). Only touches modules/engine-graphics/src/vulkan/screenshot.zig:

   • Add ScreenshotFormat.ppm and a .ppm arm in detectScreenshotFormat.
   • Implement writePPM reusing the BGRA/RGBA + sRGB channel handling already in writePNG (lines 232-249) — header P6\n{w} {h}\n255\n followed by RGB rows.
   • Should be a separate PR so the golden-diff CI keeps comparing screenshot.png without disruption.

Suggested next step

Open a small fix/visual-test-prompt-png-sync PR for item 1 (prompt + .gitignore cleanup, no runtime change). Item 2 can be filed as a follow-up enhancement if there's actual demand for .ppm output.

Proposed prompt diff for item 1:

- 2. Builds and runs the game with Lavapipe (software Vulkan): \`zig build run -Dscreenshot-path=screenshot.ppm -Dskip-present=true\`
- 3. The game should render the HomeScreen menu for 5 frames, capture a screenshot as PPM, and exit
- 4. The PPM is then converted to PNG
+ 2. Builds and runs the game with Lavapipe (software Vulkan): \`zig build run -Dscreenshot-path=screenshot.png -Dskip-present=true\`
+ 3. The game should render the HomeScreen menu for 5 frames, capture a screenshot as PNG, and exit
@@
- - The game uses \`-Dscreenshot-path=screenshot.ppm\` which sets \`build_options.screenshot_path\`
- - This enables screenshot mode: loads HomeScreen instead of WorldScreen, counts frames, captures PPM via Vulkan, then exits
+ - The game uses \`-Dscreenshot-path=screenshot.png\` which sets \`build_options.screenshot_path\`
+ - This enables screenshot mode: loads HomeScreen instead of WorldScreen, counts frames, captures PNG via Vulkan, then exits

[github-actions]

Comment posted on issue #913: #913 (comment)

Triage summary:

• Classification: Bug + documentation drift. Report validated against dev (all file/line refs in the issue match current code).
• No duplicate issue / no related open PR. Closest history is [Visual Test] Menu screenshot capture failed #341 (closed during PRs feat: add screenshot capture and visual regression test workflow #340/fix: use nix run for imagemagick in visual-test workflow #342).
• Scope: Recommended splitting into two independent PRs — (1) sync .github/prompts/visual-test-diagnose.md and .gitignore to PNG (docs-only, no CI behaviour change), and (2) optionally add a real writePPM encoder gated as a follow-up enhancement, since the workflow + golden diff are already consistent on .png.
• Provided a concrete prompt diff for the small sync fix.

opencode session  |  github run