Phaser 4 web game

# AGENTS.md: Phaser 4 web game

Browser game with Phaser 4, TypeScript and Vite. Check the Phaser version in `package.json`; v3 code and tutorials
often do not work in v4.

## Commands
- Dev server: `npm run dev`. Production build: `npm run build`. Type-check: `npx tsc --noEmit`.
- Done means: type-check and build pass, and you ran the game and played the changed part.

## Phaser docs that match the installed version
- Phaser ships agent skills inside the package: `node_modules/phaser/skills/<topic>/SKILL.md` (scenes, loading-assets,
  physics-arcade, input-keyboard-mouse-touch, tweens, filters-and-postfx, v3-to-v4-migration and more).
  Read the relevant one before using an API you have not used in this project. Prefer it over memory and old tutorials.
- Porting v3 code or a v3 example: read `node_modules/phaser/skills/v3-to-v4-migration/SKILL.md` first. FX and masks
  are filters in v4, pipelines are render nodes, and the tint API changed.

## Game code rules
- One scene per screen or mode (Boot, Preload, Menu, Game, GameOver). Scenes talk through events or the registry,
  not by reaching into each other's fields.
- Load assets in `preload()` with stable keys; files live in `public/assets/`. Never load in `update()`.
- Movement and timers use `delta` or Phaser timers, never frame counts, so speed does not depend on frame rate.
- Reuse objects: physics groups with `maxSize` and `get()` / `disableBody` for bullets, particles and enemies.
  No `new` or `destroy` per frame.
- Keep `update()` cheap: no allocations, DOM access or `console.log` in hot paths.
- Game constants (speeds, sizes, timings) in one config module so tuning does not mean hunting through scenes.
- Input: support keyboard and pointer or touch for anything the player must do. Guard `this.input.keyboard` (it can be
  null when disabled).
- Clean up: remove listeners and timers in the scene's `shutdown` event.

## Scope
- Protect the core loop first. New features only after it plays well; one feature per change, playable after each.
- Use the `phaser-feature` skill for every gameplay change.

# CLAUDE.md

@AGENTS.md

## Claude Code notes
- Skills from this loadout live in `.claude/skills/`: `phaser-feature`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Phaser 4 web game" v1.0.0 — https://loadout.jnw-it.com/loadouts/phaser-web-game/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes
- Skills from this loadout live in `.agents/skills/`: `phaser-feature`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Phaser 4 web game" v1.0.0 — https://loadout.jnw-it.com/loadouts/phaser-web-game/ -->

---
name: phaser-feature
description: Add a gameplay feature to a Phaser 4 game using the version-matched Phaser skills in node_modules, pooled objects, delta-based movement, and a type-check, build and play test. Use for any gameplay change.
---

# Phaser feature

1. Name the feature in one sentence and the scene it lives in. If it needs a new scene, say so.
2. Read the matching Phaser skill from `node_modules/phaser/skills/` for every subsystem it touches (for example
   `physics-arcade`, `groups-and-containers`, `tweens`). Use the API as written there for the installed version.
3. Implement it like `references/GameScene.ts`: assets in `preload()`, pooled groups, delta-based movement, constants in
   one place, listeners removed on shutdown.
4. Run `npx tsc --noEmit` and `npm run build`.
5. Run `npm run dev`, open the game and play the feature. If you can drive a browser (Playwright MCP or similar), take a
   screenshot of it working; otherwise tell the human exactly what to try.
6. Check the frame rate did not drop (the Phaser debug or browser performance panel) if you added many objects.
7. Report: what changed, how you tested it, any tuning values worth adjusting.

// Example Phaser 4 scene: assets in preload, pooled bullets, delta-based movement, keyboard and pointer input,
// constants in one place and listeners removed on shutdown.
import Phaser from "phaser";

export const TUNING = {
  playerSpeed: 300, // pixels per second
  bulletSpeed: 600,
  fireCooldownMs: 200,
  maxBullets: 30,
} as const;

export class GameScene extends Phaser.Scene {
  private player!: Phaser.Physics.Arcade.Sprite;
  private bullets!: Phaser.Physics.Arcade.Group;
  private cursors?: Phaser.Types.Input.Keyboard.CursorKeys;
  private lastFired = 0;

  constructor() {
    super("Game");
  }

  preload(): void {
    this.load.image("player", "assets/player.png");
    this.load.image("bullet", "assets/bullet.png");
  }

  create(): void {
    const { width, height } = this.scale;
    this.player = this.physics.add.sprite(width / 2, height - 60, "player");
    this.player.setCollideWorldBounds(true);

    this.bullets = this.physics.add.group({ defaultKey: "bullet", maxSize: TUNING.maxBullets });
    this.cursors = this.input.keyboard?.createCursorKeys();

    this.input.on(Phaser.Input.Events.POINTER_DOWN, this.fire, this);
    this.events.once(Phaser.Scenes.Events.SHUTDOWN, () => {
      this.input.off(Phaser.Input.Events.POINTER_DOWN, this.fire, this);
    });
  }

  update(time: number, delta: number): void {
    const dx = (this.cursors?.left.isDown ? -1 : 0) + (this.cursors?.right.isDown ? 1 : 0);
    this.player.x += dx * TUNING.playerSpeed * (delta / 1000);

    if (this.cursors?.space.isDown && time > this.lastFired + TUNING.fireCooldownMs) {
      this.fire();
      this.lastFired = time;
    }

    // Return off-screen bullets to the pool instead of destroying them.
    for (const child of this.bullets.getChildren()) {
      const b = child as Phaser.Physics.Arcade.Image;
      if (b.active && b.y < -20) this.bullets.killAndHide(b);
    }
  }

  private fire(): void {
    const b = this.bullets.get(this.player.x, this.player.y - 20) as Phaser.Physics.Arcade.Image | null;
    if (!b) return; // pool exhausted: skip this shot rather than allocate
    b.setActive(true).setVisible(true);
    b.enableBody(true, this.player.x, this.player.y - 20, true, true);
    b.setVelocityY(-TUNING.bulletSpeed);
  }
}