unity-video-playtest

name

unity-video-playtest

description

Record Unity Editor playtests as video and review behavior that depends on motion, timing, sequencing, or intermittent visual state. Use when working in Unity and validating animation, camera movement, scene transitions, particles, combat resolution, input response, or UI timing; select native MP4 review for video-capable hosts and the extracted-frame review path for Claude-family or other frame-only hosts.

Unity Video Playtest

Use video as the primary evidence for time-dependent behavior. Do not call an animation smooth because its first and last screenshots look correct.

Choose the review adapter

1. Determine whether the current host can actually inspect a local MP4. Do not infer this from the model name alone.
2. If it can, use the native-video path: inspect the MP4, then use the generated contact sheet and dense frames to navigate suspicious moments.
3. If it cannot, use the frame-review path: run scripts/inspect_video.sh, inspect the contact sheet, then extract a tight time range at 12–30 fps around a suspected issue. If a compatible watch skill is installed, use it for video ingestion, targeted frame selection, and optional transcription.
4. State which adapter was used in the report. Frame review is strong evidence for ordering, frozen frames, snaps, and missing transitions; it is weaker evidence for perceived smoothness than native playback.

Read references/review-backends.md before selecting a capture or review backend.

Capture

1. Read the project's existing playtest instructions. Compile, open the intended scene, and clear or preserve console output according to project convention.
2. Create a gitignored timestamped output folder outside Assets/, for example .agent-scratch/playtests/.
3. Prefer a project-owned Unity Recorder integration or Unity Recorder configured for a fixed output frame rate. Start recording before Play mode when startup behavior matters.
4. Exercise only the interactions supported by the available Unity or desktop-control tools. Record 10–30 seconds or the whole relevant flow.
5. Stop recording and Play mode unless the user asks otherwise. Retain console errors and warnings that overlap the recording.
6. When no Unity-owned recorder is available on macOS, use the display fallback after focusing the Game view:

scripts/record_macos.sh --duration 20 --output .agent-scratch/playtests/playtest.mp4

This fallback records the display, not a pristine Game View. Never replace video with sparse screenshots when the question is about smoothness.

Prepare evidence

Run an overview pass for every capture:

scripts/inspect_video.sh .agent-scratch/playtests/playtest.mp4

For a rapid or ambiguous event, make a dense targeted frame sequence. --start and --duration are seconds:

scripts/inspect_video.sh .agent-scratch/playtests/playtest.mp4 \
  --output .agent-scratch/playtests/walk-window \
  --start 4.0 --duration 2.0 --fps 12

The script writes metadata.json, contact-sheet.jpg, frames/, and frame-times.csv. Inspect a frame before, during, and after the event. Re-run at 24–30 fps for sprite animation or one-frame glitches when needed.

Review checklist

• Confirm the MP4 exists, has non-zero duration, and has a video stream.
• Look for frozen or duplicate-looking frames, snapping, jumps, missing/late transitions, incorrect draw order, camera discontinuities, UI lag, and phase-order mistakes.
• Correlate visual timestamps with Unity console errors and warnings.
• Distinguish a stale or unfocused Game View from a genuinely frozen game; re-record if uncertain.
• Say exactly what input and time interval were exercised.

Report

Return the scene and tested flow, capture path and duration, selected review adapter, PASS/WARNINGS/FAIL, timestamped observations, matching console output, evidence paths, and limitations. Never summarize a motion-sensitive test from a single still image.