Phaser 4 vs Phaser 3 for AI-assisted game jams

Updated 2026-10-17

As of October 2026, npm i phaser installs Phaser 4 (the npm latest tag is 4.2.1), and 3.90.0 is the last Phaser 3 release. That matters when an AI agent writes your code: it may write v3 examples into a v4 project, or the other way round.

Which one should you jam with?

	Phaser 3.90	Phaser 4.x
Status	Final 3.x release, stable	Current major, actively developed
Examples and tutorials	Years of community examples, tutorials and forum answers	Newer, fewer third-party examples so far
Renderer	Original WebGL/Canvas renderer	New renderer, some APIs changed
Install	`npm i phaser@^3.90`	`npm i phaser`

Our take: for a 48-hour jam with an AI agent, pin Phaser 3.90 unless you already know v4. Code an agent writes from older examples is more likely to match v3, and a jam is no time to debug version mismatches. If you pick v4, use v4 docs and examples only, and put that in your rules file.

Pin it and tell the agent

npm i phaser@^3.90
# rules file:
# "This project uses Phaser 3.90 (package.json). Do not use Phaser 4 APIs or examples.
#  If package.json says phaser@4, stop and ask."

The Vite setting that breaks itch.io

itch.io serves HTML games from a sub-path. Vite's default base: '/' builds absolute URLs like /assets/index.js, and you get a black screen. Set it to relative:

// vite.config.ts
import { defineConfig } from 'vite';
export default defineConfig({ base: './' });

Check with grep -r '"/assets' dist; it should find nothing. Put assets in public/assets/ and load them as 'assets/x.png' (no leading slash).

Agent rules worth adding for either version

Use this.time.delayedCall and tweens, not setTimeout; timers should respect pause and scene shutdown.
Remove global listeners on scene SHUTDOWN, or scene.restart() duplicates them.
Create sprites with this.physics.add.sprite (or physics.add.existing) if they need velocity.
Show a "click to start" screen; browsers block audio until the first click or key press.
npm run build (with tsc) must pass after every change.

The demo on this site is the kit's Phaser 3.90 + Vite starter, built with exactly these settings.

Get the rules

The Godot rules in this guide are free on GitHub. The full kit adds Phaser and Roblox packs, six roles and the 48h playbook.