/phaser

name: phaser
description: >
  Build 2D browser games with Phaser 3 using scene-based architecture and centralized state.
  Use when creating a new 2D game, adding 2D game features, working with Phaser, or building
  sprite-based web games.
argument-hint: [topic or question]
license: MIT
metadata:
  author: OpusGameLabs
  version: 1.3.0
  tags: [game, 2d, phaser, scenes, sprites, arcade-physics]

Phaser 3 Game Development

You are an expert Phaser game developer building games with the game-creator plugin. Follow these patterns to produce well-structured, visually polished, and maintainable 2D browser games.

Core Principles

1. **Core loop first** — Implement the minimum gameplay loop before any polish: boot → preload → create → update. Add the win/lose condition and scoring **before** visuals, audio, or juice. Keep initial scope small: 1 scene, 1 mechanic, 1 fail condition. Wire spectacle EventBus hooks (`SPECTACLE_*` events) alongside the core loop — they are part of scaffolding, not deferred polish. 2. **TypeScript-first** — Always use TypeScript for type safety and IDE support 3. **Scene-based architecture** — Each game screen is a Scene; keep them focused 4. **Vite bundling** — Use the official `phaserjs/template-vite-ts` template 5. **Composition over inheritance** — Prefer composing behaviors over deep class hierarchies 6. **Data-driven design** — Define levels, enemies, and configs in JSON/data files 7. **Event-driven communication** — All cross-scene/system communication via EventBus 8. **Restart-safe** — Gameplay must be fully restart-safe and deterministic. `GameState.reset()` must restore a clean slate. No stale references, lingering timers, or leaked event listeners across restarts.

Spectacle Events

Every player action and game event must emit at least one spectacle event. These hooks exist in the template EventBus — the design pass attaches visual effects to them.

| Event | Constant | When to Emit | |-------|----------|--------------| | `spectacle:entrance` | `SPECTACLE_ENTRANCE` | In `create()` when the player/entities first appear on screen | | `spectacle:action` | `SPECTACLE_ACTION` | On every player input (tap, jump, shoot, swipe) | | `spectacle:hit` | `SPECTACLE_HIT` | When player hits/destroys an enemy, collects an item, or scores | | `spectacle:combo` | `SPECTACLE_COMBO` | When consecutive hits/scores happen without a miss. Pass `{ combo: n }` | | `spectacle:streak` | `SPECTACLE_STREAK` | When combo reaches milestones (5, 10, 25, 50). Pass `{ streak: n }` | | `spectacle:near_miss` | `SPECTACLE_NEAR_MISS` | When player narrowly avoids danger (within ~20% of collision radius) |

**Rule**: If a gameplay moment has no spectacle event, add one. The design pass cannot polish what it cannot hook into.

Mandatory Conventions

All games MUST follow the [game-creator conventions](conventions.md):

• **`core/` directory** with EventBus, GameState, and Constants
• **EventBus singleton** — `domain:action` event naming, no direct scene references
• **GameState singleton** — Centralized state with `reset()` for clean restarts
• **Constants file** — Every magic number, color, speed, and config value — zero hardcoded values
• **Scene cleanup** — Remove EventBus listeners in `shutdown()`

See [conventions.md](conventions.md) for full details and code examples.

Project Setup

Use the official Vite + TypeScript template as your starting point:

npx degit phaserjs/template-vite-ts my-game
cd my-game && npm install

Required Directory Structure

src/
├── core/
│   ├── EventBus.ts        # Singleton event bus + event constants
│   ├── GameState.ts       # Centralized state with reset()
│   └── Constants.ts       # ALL config values
├── scenes/
│   ├── Boot.ts            # Minimal setup, start Game scene
│   ├── Preloader.ts       # Load all assets, show progress bar
│   ├── Game.ts            # Main gameplay (starts immediately, no title screen)
│   └── GameOver.ts        # End screen with restart
├── objects/               # Game entities (Player, Enemy, etc.)
├── systems/               # Managers and subsystems
├── ui/                    # UI components (buttons, bars, dialogs)
├── audio/                 # Audio manager, music, SFX
├── config.ts              # Phaser.Types.Core.GameConfig
└── main.ts                # Entry point

See [project-setup.md](project-setup.md) for full config and tooling details.

Scene Architecture

• **Lifecycle**: `init()` → `preload()` → `create()` → `update(time, delta)`
• Use `init()` for receiving data from scene transitions
• Load assets in a dedicated `Preloader` scene, not in every scene
• Keep `update()` lean — delegate to subsystems and game objects
• **No title screen by default** — boot directly into gameplay. Only add a title/menu scene if the user explicitly asks for one
• **No in-game score HUD** — the Play.fun widget displays score in a deadzone at the top of the game. Do not create a separate UIScene or HUD overlay for score display
• Use parallel scenes for UI overlays (pause menu) only when requested

Play.fun Safe Zone

When games run inside the Play.fun dashboard on mobile Safari, the SDK sets CSS custom properties on the game iframe's `document.documentElement`:

• `--ogp-safe-top-inset` — space below the Play.fun header bubbles (~68px on mobile)
• `--ogp-safe-bottom-inset` — space above Safari bottom controls (~148px on mobile)

Both default to `0px` when not running inside the dashboard (desktop, standalone).

The template's `Constants.js` reads these at boot and exposes `SAFE_ZONE.TOP` and `SAFE_ZONE.BOTTOM` in canvas pixels (CSS value × DPR). A static fallback (`GAME.HEIGHT * 0.08`) ensures the top safe zone works even without the SDK.

**Rules:**

• All UI text, buttons, and HUD elements must be positioned below `SAFE_ZONE.TOP` and above `GAME.HEIGHT - SAFE_ZONE.BOTTOM`
• Gameplay entities should not spawn in the safe zone areas
• The game-over screen, score panels, and restart