Implement the minimum gameplay loop before any polish. The order is: input -> movement -> fail condition -> scoring -> restart. Only after the core loop works should you add visuals, audio, or juice. Keep initial scope small: 1 scene/level, 1 mechanic, 1 fail condition.
Event-Driven Communication
Modules never import each other for communication. All cross-module messaging goes through a singleton EventBus with predefined event constants.
Centralized State
A single GameState singleton holds all game state. Systems read state directly and modify it through events. No scattered state across modules.
Configuration Centralization
Every magic number, balance value, asset path, spawn point, and timing value goes in
Constants.js
. Game logic files contain zero hardcoded values.
Orchestrator Pattern
One
Game.js
class initializes all systems, manages game flow (boot -> gameplay -> death/win -> restart), and runs the main loop. Systems don't self-initialize.
No title screen by default
— boot directly into gameplay. Only add a title/menu scene if the user explicitly asks for one.
Restart-Safe and Deterministic
Gameplay must survive full restart cycles cleanly.
GameState.reset()
restores a complete clean slate. All event listeners are removed in cleanup/shutdown. No stale references, lingering timers, leaked tweens, or orphaned physics bodies survive across restarts. Test by restarting 3x in a row — the third run must behave identically to the first.
Clear Separation of Concerns
Code is organized into functional layers:
core/
- Foundation (Game, EventBus, GameState, Constants)
systems/
- Engine-level systems (input, physics, audio, particles)
gameplay/
- Game mechanics (player, enemies, weapons, scoring)
level/
- World building (level construction, asset loading)
ui/
- Interface (menus, HUD, overlays)
Event System Design
Event Naming Convention
Use
domain:action
format grouped by feature area:
export
const
Events
=
{
// Player
PLAYER_DAMAGED
:
'player:damaged'
,
PLAYER_HEALED
:
'player:healed'
,
PLAYER_DIED
:
'player:died'
,
// Enemy
ENEMY_SPAWNED
:
'enemy:spawned'
,
ENEMY_KILLED
:
'enemy:killed'
,
// Game flow
GAME_STARTED
:
'game:started'
,
GAME_PAUSED
:
'game:paused'
,
GAME_OVER
:
'game:over'
,
// System
ASSETS_LOADED
:
'assets:loaded'
,
LOADING_PROGRESS
:
'loading:progress'
}
;
Event Data Contracts
Always pass structured data objects, never primitives:
// Good
eventBus
.
emit
(
Events
.
PLAYER_DAMAGED
,
{
amount
:
10
,
source
:
'enemy'
,
damageType
:
'melee'
}
)
;
// Bad
eventBus
.
emit
(
Events
.
PLAYER_DAMAGED
,
10
)
;
State Management
GameState Structure
Organize state into clear domains:
class
GameState
{
constructor
(
)
{
this
.
player
=
{
health
,
maxHealth
,
speed
,
inventory
,
buffs
}
;
this
.
combat
=
{
killCount
,
waveNumber
,
score
}
;
this
.
game
=
{
started
,
paused
,
isPlaying
}
;
}
}
Game Flow
Standard flow for both 2D and 3D games:
Boot/Load -> Gameplay <-> Pause Menu (if requested)
-> Game Over -> Gameplay (restart)
No title screen by default.
Games boot directly into gameplay. The Play.fun widget handles score display, leaderboards, and wallet connect in a deadzone at the top of the game, so no in-game score HUD is needed. Only add a title/menu scene if the user explicitly requests one.
Common Architecture Pitfalls
Unwired physics bodies
— Creating a static physics body (e.g., ground, wall) without wiring it to other bodies via
physics.add.collider()
or
physics.add.overlap()
has no gameplay effect. Every boundary or obstacle needs explicit collision wiring to the entities it should interact with. After creating any static body, immediately add the collider call.
Interactive elements blocked by overlapping display objects
— When building UI (buttons, menus), the topmost display object in the scene list receives pointer events. Never hide the interactive element behind a decorative layer. Either make the visual element itself interactive, or ensure nothing is rendered on top of the hit area.
Polish before gameplay
— Adding particles, screen shake, and transitions before the core loop works is a common time sink. Get input -> action -> fail condition -> scoring -> restart working first. Everything else is polish.
No cleanup on restart
— Forgetting to remove event listeners, destroy timers, and dispose resources in
shutdown()
causes ghost behavior, double-firing events, and memory leaks after restart.
Pre-Ship Validation Checklist
Before considering a game complete, verify all items:
Core loop
— Player can start, play, lose/win, and see the result
Restart
— Works cleanly 3x in a row with identical behavior
Mobile input
— Touch/tap/swipe/gyro works; 44px minimum tap targets
Desktop input
— Keyboard + mouse works
Responsive
— Canvas resizes correctly on window resize
Constants
— Zero hardcoded magic numbers in game logic
EventBus
— No direct cross-module imports for communication
Cleanup
— All listeners removed in shutdown, resources disposed
Mute toggle
— See
mute-button
rule
Delta-based
— All movement uses delta time, not frame count
Build
—
npm run build
succeeds with no errors
No errors
— No uncaught exceptions or console errors at runtime