How to vibe code a browser game with Phaser

Phaser is a good fit for building a browser game with an AI agent. The framework has been public for years, so coding assistants know its API well, and the project's own repository now ships a set of agent skill files for Phaser 4. The trouble is that Phaser 3 and Phaser 4 differ in places, and most tutorials and training data describe Phaser 3. This guide covers how to start, what to tell the agent, and the mistakes worth ruling out in advance.

Checked on 27 Oct 2026. The latest Phaser release is 4.2.1 (9 Jul 2026); Phaser 4.0 shipped in April 2026. Vite 8 and TypeScript are the tools assumed here.

Start with a small, boring setup

The setup that gives the agent the least room to go wrong is a Vite project in TypeScript with Phaser as a dependency. Ask the agent to scaffold it, then read what it created before you add anything. A layout that works for most small games:

src/
  main.ts          creates the Phaser.Game with one config
  config.ts        every tunable number: speed, gravity, spawn rate
  scenes/          BootScene, PreloadScene, MenuScene, GameScene, GameOverScene
  objects/         player, enemies, pickups
  logic/           scoring, damage, spawn tables: plain TypeScript, no Phaser
public/assets/     images, audio

Keeping game logic in plain functions with no Phaser imports lets you unit test it without a canvas. It also stops the agent from tangling rules and rendering together, which makes later changes safer.

Tell the agent which Phaser you have

Most tutorials and a lot of the agent's training data describe Phaser 3, and Phaser 4 changed several things. The project's migration guide lists the breaking changes: the renderer and tint system were rewritten, effects and masks are now filters, and some Phaser 3 classes were removed, including Point, Mesh and BitmapMask. A Phaser 3 snippet or plugin pasted into a Phaser 4 project may fail, or fail quietly. The repository also includes a skill file for migrating a Phaser 3 game to version 4.

The import line is a smaller issue than you might expect. Phaser's README shows import Phaser from 'phaser', and when I inspected the 4.2.1 package its ES module build exports both a default and the individual named parts, so either style resolves. If your bundler or TypeScript config complains, check the package's own types rather than guessing.

What does need a rule is making the agent look at the installed version before using an API from memory. This is the kind of line to add to your instruction file:

- Check package.json for the installed phaser version before using its API.
  Most tutorials describe Phaser 3. When unsure, read the installed
  package's types or the Phaser 4 migration guide.
- Never copy a Phaser 3 plugin or snippet without checking it supports
  the installed version.

You can also point the agent at the skills/ folder in the Phaser repository. It contains guidance for scenes, physics, input, animation, tilemaps, tweens, particles and cameras, written for AI agents.

Write the first prompt like a design note

"Make me a platformer" gives the agent hundreds of decisions to make. Describe one scene, one mechanic and one way to tell it works:

Create a GameScene with a player that moves left and right and jumps.
Use Arcade physics. Put speed, jump velocity and gravity in src/config.ts.
Use placeholder rectangles, not image files. Use delta for movement.
When done, run typecheck and build, and tell me what to press to test it.

Then add one thing at a time: enemies, a score, a game over screen, sound. Commit after each step that works. When something breaks, you only need to undo one step. If the agent starts looping on a bug, our guide to stopping an agent from breaking your code has a prompt for that.

Rules that prevent common game bugs

These are the ones worth writing down, because agents repeat them:

• Use delta for movement and timers. Never assume 60 frames per second. A game tied to frame rate runs too fast on a high-refresh screen.
• Keep update cheap. No creating objects, no console.log, no array filtering on every frame. Pool bullets and enemies with a group instead of creating and destroying them.
• Use Phaser's timers and tweens, not setTimeout. They pause with the scene.
• Remove event listeners when a scene shuts down. Listeners on global events that never get removed are a classic memory leak.
• Size hitboxes deliberately. Use body.setSize and setOffset rather than relying on the whole texture.
• Do not move physics bodies by setting x and y every frame. Use velocity.

Sound, phones and shipping

Browsers block audio until the player interacts with the page. Add a "click to start" screen and begin sound after the first click or key press, or your game will be silent and you will not see an error. Set the scale mode in the config (Phaser.Scale.FIT with centred layout) and test at phone and desktop sizes. If you want touch controls, say so in the first prompt.

Always run a production build and open the built output before you call the game finished. Dev and production can differ, particularly in asset paths. If you host on itch.io or under a sub-path, set base: './' in vite.config.ts so the built files use relative paths.

Keep secrets out of the game. Anything in the bundle can be read by players, so a leaderboard that trusts the score sent by the browser can be cheated. If scores matter, a server has to validate them. Also record where your art and audio came from, and the licence, in an ASSETS.md file. Agents will happily use placeholder assets you do not have rights to ship.

What the kit includes for Phaser

The Vibemast Ship-It Kit has a ready-to-copy Phaser folder with AGENTS.md, CLAUDE.md, Cursor rules and Copilot instructions. It covers the project layout, the Phaser 3 versus 4 differences, scene lifecycle, pooling, input, audio and delivery. It sits alongside the 25 build prompts, 8 rescue prompts and 20 security audit prompts for any stack. It will not design your game or make an agent good at game feel; you still need to play the thing. If you want to see how the files work before buying, the free mini pack includes the generator and a Vite and React rule set. For how the files differ between tools, see Cursor rules vs CLAUDE.md vs AGENTS.md.

Want to try the rules approach first? The free mini pack has the core rules and the generator, so you can see how the agent behaves with rules before you buy anything. The Phaser rule set itself is only in the kit.

Who the paid kit is for, and who it is not for

• Worth it if you build on one of its four stacks (Next.js with Supabase, Vite with React, FastAPI, Phaser) and want tested files and prompts today instead of writing and testing your own.
• Not worth it if you only need one rules file for one project. The free guides and the free mini pack are enough, and you can adapt them yourself.

Related guides

• 12 rules for AI coding agents
• Cursor rules template
• AGENTS.md example and template

FAQ

Can an AI agent build a whole Phaser game?

It can scaffold a playable prototype and add features from descriptions. Expect to guide it scene by scene, test by hand, and fix feel and balance yourself.

Should I use Phaser 3 or Phaser 4?

For a new project, Phaser 4 is the current release. Use Phaser 3 only if you depend on a plugin that has not moved. Whichever you choose, tell the agent the version.

Why does my Phaser build fail after the agent wrote it?

Look for Phaser 3 code first: a removed class such as Point or BitmapMask, an old FX or mask call, or a Phaser 3 plugin. Then read the first error rather than the last, and use the rescue prompt above if the agent starts looping.

Do I need to know TypeScript?

Not deeply, but TypeScript catches many mistakes at build time that an agent would otherwise leave for runtime, so it is worth keeping on.