Debugging

PixiJS draws to a canvas, so AI agents and automated tooling can’t see the reels. pixi-reels ships three utilities that solve this: debugSnapshot, debugGrid, and enableDebug.

One-liner: attach to window

import { enableDebug } from 'pixi-reels';
enableDebug(reelSet);
// → window.__PIXI_REELS_DEBUG is now live

In the browser devtools console:

__PIXI_REELS_DEBUG.log();
// [pixi-reels debug] spinning=false speed=normal
// ┌────────┬────────┬────────┬────────┬────────┐
// │ cherry │ lemon  │ bar    │ seven  │ cherry │
// │ plum   │ cherry │ wild   │ lemon  │ orange │
// │ orange │ bell   │ cherry │ plum   │ bell   │
// └────────┴────────┴────────┴────────┴────────┘

__PIXI_REELS_DEBUG.trace();  // logs every domain event from now on

Programmatic snapshot

import { debugSnapshot, debugGrid } from 'pixi-reels';

const snap = debugSnapshot(reelSet);
// snap: { isSpinning, currentSpeed, spotlightActive, reelCount, visibleRows, reels: [...], grid: [[...], ...] }

console.log(debugGrid(reelSet));   // ASCII table

Using snapshots in tests

The test harness pipes snapshots into readable error messages automatically when expectGrid() fails:

Grid mismatch:
  reel 0 row 1: expected "seven" got "cherry"

Current grid:
┌────────┬────────┬────────┬────────┬────────┐
│ cherry │ bar    │ wild   │ plum   │ seven  │
│ cherry │ lemon  │ orange │ bell   │ seven  │
│ bar    │ bell   │ wild   │ bar    │ cherry │
└────────┴────────┴────────┴────────┴────────┘

The snapshot shapes are typed as DebugSnapshot and DebugReelSnapshot. they’re plain data so they survive structuredClone / postMessage / JSON.stringify without losing fidelity.

Recording sessions

When a bug only reproduces over many frames, recording the engine’s per-frame state lets you replay it offline. startRecording wires a recorder into the ticker; stopRecording releases it. getFrames returns the array of RecordedFrame entries between the two; clearFrames resets the buffer for the next take.

import { startRecording, stopRecording, getFrames, clearFrames, type StartRecordingOptions } from 'pixi-reels';

const opts: StartRecordingOptions = { reelSet, sampleEveryNFrames: 1 };
startRecording(opts);
await reelSet.spin();
reelSet.setResult([/* ... */]);
await /* the spin */;
stopRecording();

const frames = getFrames(); // RecordedFrame[]
console.log(`captured ${frames.length} frames`);
clearFrames(); // ready for the next round

Each RecordedFrame carries a DebugSnapshot, the timestamp, and the elapsed ms since the first frame. Pipe it into a tracing UI or feed it to a comparison test.

Gotchas

• debugGrid returns plain text. safe to log, assert against, or paste anywhere.
• enableDebug is a no-op in Node (it checks typeof window).
• Snapshots contain no PixiJS objects, so JSON.stringify() will always work.
• The DEFAULTS constant (exported from pixi-reels) holds every default value the builder applies. read it when you want to set a value relative to the engine’s default (e.g. builder.bufferSymbols(DEFAULTS.bufferSymbols + 2)).