game-architecture

$27

-

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