verify-pixels

Original：🇺🇸 English

Translated

Use when changing PlayCanvas rendering code that must not change the rendered image — draw-call optimization, hardware instancing, shader or material refactors, or asset pipeline swaps — to prove the output unchanged before shipping.

4installs

Sourceplaycanvas/skills

Added on2026-08-26

NPX Install

npx skill4agent add playcanvas/skills verify-pixels

SKILL.md Content

View Translation Comparison →

Prove pixels unchanged

A rendering change that must not alter the image is not proven by eyeballing a screenshot at one pose. Build a deterministic capture, compare byte-exact counts across a pose × phase matrix, and prove the capture harness itself is trustworthy before trusting what it reports about the change.

Make the frame deterministic

Drive every animated shader or vertex effect from one app-owned time value, never
```
Date.now()
```
or
```
performance.now()
```
read inside the render path, so a captured phase is exactly reproducible.
Freeze the clock with
```
app.timeScale = 0
```
before capturing; nothing should advance between frames you did not explicitly step.
Step frames explicitly: set
```
app.autoRender = false
```
once, then set
```
app.renderNextFrame = true
```
before each frame you want rendered. The engine renders exactly that frame and clears the flag — do not rely on the free-running render loop plus a timed screenshot.
Read the rendered pixels with
```
await device.readPixelsAsync(x, y, w, h, pixels)
```
against the exact backbuffer, not a re-encoded screenshot (e.g.
```
canvas.toDataURL
```
) that can introduce compression or colour-management differences the eye won't catch. In the installed engine this method lives on
```
WebglGraphicsDevice
```
, not the base
```
GraphicsDevice
```
type, so narrow to it (or branch on
```
device.isWebGL2
```
) before calling; a WebGPU project needs its own equivalent readback. If the project already has a screenshot path, hold it to the same rule: fixed size, fixed pose, no lossy step before the byte comparison.

Build a pose × phase matrix

Single-pose, single-frame proof cannot see everything a rendering refactor can break. Choose at least two representative camera poses — angles that would expose a dropped instance, a wrong batch bound, or a seam differently — and at least two animation phases, including one mid-animation, not only frame zero. Capture every pose × phase pair for the build before the change and the build after it, with the same canvas size, camera, and lighting each time.

Run a same-build control first

Before trusting any diff between the old and new build, capture the same pose × phase matrix twice from the unmodified build. Two captures of identical, frozen state must be bit-identical. If they are not, the capture path itself is the source of noise — an unseeded animation, an asset still loading, a GPU timing race — and must be fixed before it can say anything about the real change.

Gate and report

Byte-compare each pose × phase pair between the two builds; do not diff by looking. Zero differing pixels passes outright. Any nonzero diff must be reviewed on-screen, and its cause and extent stated in the change description — never merged silently. Report the actual count every time, for example "0 of 65536 pixels differ" or "312 of 65536 pixels differ, confined to the object's silhouette edge". "Looks the same" or "no visible difference" is not a result.