Guide: AI-Assisted Debugging for Phaser.js Games

guideai-game-devdebuggingphaser

AI writes good Phaser code about 80% of the time when prompts are structured right. The other 20% — and some of the 80% — breaks at runtime. The browser console fills with red, the canvas stays blank, and the game doesn’t load.

This guide covers the systematic debug loop we use on this site: how to feed errors back to AI, which error patterns models actually fix well, and when you’re better off reading the Phaser docs yourself.

Prerequisites

  • A browser with DevTools (F12 / Ctrl+Shift+I)
  • Access to an AI model with code understanding (this guide uses DeepSeek V4 Flash via OpenRouter)
  • A Phaser.js game that doesn’t work (you probably have one)
  • 15 minutes

The Debug Loop

Four steps, same order every time:

  1. Capture the full error — Console output, stack trace, line number. Not “it doesn’t work.” The actual error message.
  2. Isolate the context — Which file, which function, which line caused it. What was the code doing.
  3. Prompt the AI — Error + isolated code + your game’s Phaser version.
  4. Verify the fix — Does it actually run or did the AI introduce a new bug.

Step 4 is the one beginners skip. Don’t.

Step 1: Capture Everything

Open DevTools (F12) and switch to the Console tab. Reload the page. You’ll see something like this:

phaser.min.js:1 Uncaught TypeError: this.add is not a function
    at GameScene.create (game.js:45)

Copy the complete error — not just the message. The line number and file tell you where the error happened. The traceback tells you the call order.

If the canvas is blank but there’s no console error, check the Network tab. Did Phaser’s CDN URL load? If it returned a 404, the model guessed a wrong URL.

curl -sI "https://cdn.jsdelivr.net/npm/[email protected]/dist/phaser.min.js" | head -1
# Expect: HTTP/2 200

Step 2: Isolate the Failing Code

Open the Sources tab in DevTools. Navigate to the file and line the error points to. Select the function or block around the error.

You need three things before you prompt the AI:

  • The error message verbatim
  • The surrounding code (10 lines around the failure point)
  • The Phaser version you’re using

The version matters because Phaser 3.60 removed Phaser.Class and changed several APIs. An AI trained on data up to early 2025 might suggest 3.50-era syntax that doesn’t exist in 3.60.

Step 3: Structure the Debug Prompt

Bad prompt:

My Phaser game doesn’t work. Can you help?

The model has no idea what “doesn’t work” means. The response will be generic — check CDN URLs, check for typos — and waste your time.

Good prompt:

I’m using Phaser 3.60.0 from CDN (https://cdn.jsdelivr.net/npm/[email protected]/dist/phaser.min.js).

Error in the console:

phaser.min.js:1 Uncaught TypeError: this.add is not a function
    at GameScene.create (game.js:45)

The create() method where the error occurs:

function create() {
  this.add.text(16, 16, 'Score: 0', { fontSize: '32px', fill: '#fff' });
}

Why is this.add undefined inside create()?

The AI can now match the error (this.add is not a function) against the code (this.add.text) and the Phaser version. The answer will be specific: you’re using a plain function instead of a Phaser Scene class method. create() needs to be a method of a Scene subclass.

What to Include in Every Debug Prompt

Element Why
Phaser version (exact) Prevents version-mismatch suggestions
CDN URL in use Lets AI verify it’s loading the right library
Full error message + line Gives the AI the exact exception and location
10 lines of surrounding code Provides enough context to understand intent
What you expected to happen Narrows the search space — “Score text should appear top-left”

Leave out: your whole game file, unrelated screenshots, speculation about the cause. The AI will hallucinate less when fed only relevant context.

Step 4: Verify the Fix

The AI will return a code change. Apply it, reload the browser, and check two things:

  1. Is the original error gone? Check the Console tab.
  2. Did anything new break? Check for new errors, unexpected behavior, or a blank canvas.

If the AI’s fix works but feels wrong — it uses a method you don’t recognize, or it restructured your scene in a confusing way — ask why. A good follow-up prompt:

Why did you suggest using scene.add.text instead of this.add.text? I want to understand when to use each pattern.

This builds your own understanding instead of creating dependency on the AI.

Common Phaser Errors AI Fixes Well

1. Scene Not in Array Format

Error: No console error, but the canvas stays blank.

Cause: Passing a single scene reference instead of an array.

// Broken
scene: GameScene

// Fixed
scene: [GameScene]

AI success rate: Near 100%. This is a well-known Phaser 3 quirk and models catch it immediately when you show the config object.

2. physics.add.circle() Instead of generateTexture()

Error: Cannot read properties of undefined (reading 'body') on collision.

Cause: physics.add.circle() creates a static Image, not a physics Sprite. It has no body property.

// Goes through preload(), create textures as graphics
this.load.image('player', someTexture);

// Instead of physics.add.circle() which doesn't produce a physics-enabled sprite

AI success rate: High, if you show the collision code and the texture creation. Without showing both, the AI may suggest the same broken pattern again.

3. Keyboard Keys Bound in update()

Error: Game gets progressively slower over time.

Cause: this.input.keyboard.createCursorKeys() inside update(), creating new key objects every frame.

// Broken — in update():
this.cursors = this.input.keyboard.createCursorKeys();

// Fixed — in create():
this.cursors = this.input.keyboard.createCursorKeys();
// In update(): reference this.cursors, don't re-create them

AI success rate: High. The frame-by-frame accumulation is a common Phaser pitfall and models recognize the pattern.

4. Missing Parent Container

Error: Game canvas renders at (0,0) with wrong dimensions, or Phaser fails to attach to the DOM.

Cause: The parent: 'game' config option has no matching <div id="game"> in the HTML body.

AI success rate: Very high. Show the Phaser config object and the HTML body, the AI spots the missing div immediately.

5. Wrong CDN URL

Error: Network tab shows a failed request for the Phaser CDN. Console shows Phaser is not defined.

Cause: The AI hallucinated a CDN URL that doesn’t exist.

Common wrong URLs models generate:

  • [email protected]/phaser.min.js (missing /dist/)
  • phaser@3/dist/phaser.min.js (no patch version)
  • [email protected]/build/three.min.js (r128 instead of 0.128.0)
  • cdnjs.cloudflare.com/... (redirects, doesn’t serve phaser directly)

AI success rate: High. Ask the model to verify the CDN URL is valid, or hardcode the known-good URL yourself:

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/phaser.min.js"></script>

Errors AI Struggles With

These are the cases where debugging time is better spent reading docs or tracing the code yourself:

Error Type Why AI Fails What to Do Instead
Off-by-one in game logic (score not incrementing, enemy spawning one pixel outside bounds) No single error message. The bug is in behavior, not syntax. AI can’t run the code to observe the wrong output. Add console.log at key points. Log the player position, the enemy position, the collision boundary. Trace the actual values.
Race conditions (sprite positions update before physics body is ready, event handlers fire in wrong order) The fix depends on execution order that AI can’t predict without running the game. scene.events.on('postupdate', ...) or use this.time.delayedCall to sequence operations.
Custom physics configuration (gravity only on certain objects, restitution values causing bounce loops) Physics tuning is iterative. The AI suggests one value, you test it, it’s wrong, repeat. Hardcode the physics values yourself. Change one variable at a time and test.
Rendering artifacts (sprites flickering, wrong layer order, text rendering with wrong font) AI can’t see the rendered output. Depth sorting, blend modes, and z-index are visual feedback loops. Tweak setDepth(), render order in create(), and CSS properties on the canvas manually.

The rule of thumb: AI excels at syntax and API errors. You handle logic and tuning.

Putting It Together — A Real Debug Session

Let’s trace a real case from this site’s benchmark pipeline. The game loaded but the player couldn’t move.

Console: No errors. Keyboard input was set up correctly in create().

Observation: The player sprite rendered but never responded to arrow keys.

Debug prompt:

Phaser 3.60 game. Player sprite renders on screen but doesn’t move with arrow keys. Here’s the player setup in create():

this.player = this.physics.add.sprite(100, 100, 'player');

And the update() method:

update() {
  this.player.body.setVelocity(0, 0);
  if (this.cursors.left.isDown) this.player.body.setVelocityX(-200);
  if (this.cursors.right.isDown) this.player.body.setVelocityX(200);
}

Cursors are bound in create(). What’s wrong?

AI response: The issue is that this.player.body.setVelocity(0, 0) at the start of update() resets velocity before the keyboard check can apply movement. The player’s velocity gets zeroed out every frame before input is processed.

Fix applied: Remove the setVelocity(0, 0) line. The physics body already stops when no force is applied.

Verification: Reloaded the page. Player moved with arrow keys. No new errors.

This was a 30-second debug cycle. Without the AI, you’d stare at the code, add console.log statements for velocity, and eventually notice the reset line. With the AI, the pattern was recognized instantly because the model has seen this exact mistake hundreds of times in training data.

When to Give Up and Read the Docs

Three situations where the AI will waste your time:

  1. The error involves a Phaser feature the model hasn’t seen in training. Phaser 3.70 added new particle emitter APIs. If you’re using a bleeding-edge version, the AI will suggest APIs that don’t exist yet. Check the Phaser Changelog first.

  2. The error comes from a third-party Phaser plugin. Models know Phaser core well but rarely have deep training data for plugins like phaser-matter-collision-plugin or community tilemap extensions.

  3. You’ve gone three debug cycles without a fix. If the AI has suggested three different approaches and none worked, you’re probably hitting a combination of bugs. Start fresh — rebuild the feature from scratch with explicit step-by-step prompts instead of debugging the broken version.

What You Learned

  • The Observe → Isolate → Prompt → Verify loop turns AI from a code generator into a debugging assistant
  • Include version, error message, surrounding code, and expected behavior in every debug prompt
  • AI fixes syntax and API errors well — it handles logic bugs, physics tuning, and rendering artifacts poorly
  • After three failed debug cycles, stop prompting and restart — incremental prompting on a broken base compounds errors
  • The verify step catches the 20% of AI-generated fixes that introduce new bugs

The same debug loop applies across game engines — Three.js, PixiJS, Godot, Unity. The pattern is universal: give the model enough context to reproduce the error in its training, and let it match against patterns it has seen before.

Resources

Built by DeepSeek V4 Flash — debug patterns gathered across 20+ Phaser game builds on this site