Phaser 4 Starter Kit + Playwright QA Layer
A downloadable asset pack
WGS Basic Kit - Phaser 4 Starter Template
A small, opinionated Phaser 4 JavaScript starter built from patterns I use across my own game projects.
It gives you a clean starting point, two working demos, a basic swappable Input Provider system, and an optional QA layer for testing real canvas gameplay with Playwright.
The goal is simple: skip some of the repetitive setup and start building the actual game.
What's included
Two Phaser 4 demos
Platformer Demo
A minimal Arcade Physics platformer with:
- an AI-controlled actor
- keyboard control
- runtime input-provider swapping
- a hazard and an exit
- observable gameplay state for automated tests
The actor starts under AI control.
Press C and the same actor switches to keyboard control without restarting the scene or changing the movement logic.
Tic-Tac-Toe Demo
A simple turn-based canvas game used to demonstrate real Playwright interaction with Phaser-rendered UI.
Playwright locates canvas elements through lightweight DOM proxies, but the actual click still goes through Phaser's real pointerdown path.
No test-only gameplay shortcut.
Basic Input Provider
The included Input Provider pattern separates gameplay actions from the device or system producing them.
Included providers:
KeyboardInputProviderAIInputProviderTestInputProvider
The actor consumes actions such as move left, move right and jump.
It does not need to know whether those actions came from a keyboard, AI or automated test.
Providers can also be swapped at runtime.
QA Layer for canvas games
Canvas is largely opaque to browser automation.
There are no normal DOM buttons, attributes or inputs underneath whatever Phaser renders.
The included QA layer provides three small tools for different testing needs:
Clickable canvas elements
Transparent DOM proxies give Playwright stable locations for real canvas clicks while allowing Phaser's own pointer handlers to process the interaction.
Coarse scene state
Useful values such as the current scene, phase or active input source can be exposed as simple <body data-*> attributes.
Detailed runtime state
QASurface exposes selected game state on demand through:
window.__qa.getState()
This is useful for positions, entity state, counters and other values that tests need to observe but never click.
Tests included
The kit includes examples of:
- pure JavaScript unit tests
- state and AI logic tests
- presentation sync tests
- Playwright E2E tests
- canvas click-through testing
- keyboard input testing
- synthetic test input
- runtime state assertions
- basic gameplay lifecycle testing
The demos are intentionally small.
They're there to show the patterns, not to provide game content.
Test code stays test-only
The QA surface is gated behind development TEST_MODE.
Production builds do not expose window.__qa, Test Input hooks or the Test Shadow state, even if someone appends the test query parameter to the URL.
Tech
- Phaser 4
- JavaScript
- ESM
- Vite
- Phaser Arcade Physics
- Node test runner
- Playwright
Quick start
npm install npm run dev
Run unit tests:
npm run test
Run Playwright E2E:
npx playwright install chromium npm run test:e2e
The included README explains both demos, the Input Provider pattern, the QA layer and how to extend each piece.
Deliberately not included
The Basic Kit stays small on purpose.
It does not include:
- Sound Manager
- advanced input systems
- gamepad / joystick support
- touch controls
- LDtk integration
- procedural grid or arena generation
- networking
- game-specific systems
Those are outside the scope of this starter.
Use it, change it, break it
This is a starter template, not a framework.
Take the pieces that are useful for your game, change what you need, and remove what you don't.
Purchase
In order to download this asset pack you must purchase it at or above the minimum price of $15 USD. You will get access to the following files:
Development log
- I got tired of rebuilding the same Phaser setup13 hours ago
Leave a comment
Log in with itch.io to leave a comment.