Physics Debug Validator — Hitbox Alignment

The single most invisible class of AI-generated game bugs: physics bodies that are offset, undersized, or oversized relative to their visual sprites. The player gets hit by an attack that visually missed, or falls through a platform that looks solid. This validator catches all of it.

When to use

In parallel with dynamic_check.mjs and run_qa.mjs during the parallel-qa-orchestra pass. Also run standalone when the user reports "hitboxes feel wrong" or "invisible collision."

Method

1. Boot the game in Playwright with a JS init script that enables physics.arcade.debug = true on the live Phaser game object (no source-file modification needed).
2. Wait for window.__gameReady.
3. Capture a canvas screenshot — physics debug mode draws colored rectangles around every body.
4. Also capture body metadata via page.evaluate() reading window.__game.physics.world.bodies.entries.
5. Emit a JSON report with body positions, sizes, and their paired sprite positions.
6. The host agent (or Claude vision) reviews the screenshot to flag misaligned bodies.

Output contract

{
  "ok": true,
  "screenshotPath": "qa/physics-debug.png",
  "bodies": [
    {
      "label": "KNIGHT",
      "bodyX": 160, "bodyY": 288, "bodyW": 22, "bodyH": 27,
      "spriteX": 160, "spriteY": 288, "spriteW": 32, "spriteH": 32,
      "offsetX": 0, "offsetY": 0,
      "aligned": true
    },
    {
      "label": "SLIME",
      "bodyX": 480, "bodyY": 144, "bodyW": 32, "bodyH": 32,
      "spriteX": 480, "spriteY": 132, "spriteW": 32, "spriteH": 32,
      "offsetY": 12,
      "aligned": false,
      "issue": "body Y offset 12px below sprite top — may clip floor tile"
    }
  ],
  "misalignedCount": 1
}

ok = true means the script ran successfully (not necessarily zero issues — the host agent reviews body data to determine severity).

Physics debug injection (no source modification)

The script uses page.addInitScript() to patch the Phaser Game constructor before it runs:

await page.addInitScript(() => {
  const _Game = window.Phaser?.Game;
  // Patch applied after Phaser loads via window.__patchPhysicsDebug flag
  window.__patchPhysicsDebug = true;
});
// After gameReady, toggle debug on live game:
await page.evaluate(() => {
  if (window.__game?.physics?.world) {
    window.__game.physics.world.drawDebug = true;
    window.__game.physics.world.debugGraphic?.clear?.();
  }
});

Known limitations

• Debug rectangles are rendered on a graphics layer; they may not perfectly align with the Phaser camera if the camera is scrolled. The script waits for the player to settle at spawn before screenshotting.
• Kinematic bodies (sensors, fixed) show in a different color (typically cyan vs green for dynamic).
• The host agent should look for bodies where the colored rectangle is significantly (> 20%) outside the visible sprite boundary.

Process

1. Run scripts/validate_physics.mjs <project-dir> [--port N]
2. Script starts vite dev server on the given port (default: auto-find free port).
3. Playwright boots game, injects debug, screenshots.
4. Script writes qa/physics-debug.png + qa/physics-bodies.json.
5. Host agent reviews both artifacts. Misaligned bodies are fed to refiner as hitbox-misaligned failures.

Scripts

• scripts/validate_physics.mjs <project-dir> [--port N] — boots, injects debug, screenshots, emits body report.