# AGENTS.md - this project

Instructions for AI coding agents working in this repository.

## Project

A Phaser (TypeScript web games) + Vitest project.

Stack: Phaser (TypeScript web games), Vitest.

## Commands

- Dev server: `npm run dev`
- Build: `npm run build`
- Unit tests: `npx vitest run`

## Project structure

- One class per scene in `src/scenes/`, game objects in `src/objects/`, static assets in `public/assets/`.

## How to work in this repo

- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.

## Phaser (TypeScript web games)

- Check the Phaser major version in `package.json` and use APIs from that version only.
- Each scene is a class extending `Phaser.Scene` with `preload`, `create` and `update`.
- Load assets in `preload` (or a dedicated Boot/Preload scene), never in `update`.
- Movement uses the `delta` argument of `update(time, delta)` so speed is frame-rate independent.
- Pool bullets, particles and enemies with `Phaser.GameObjects.Group` instead of creating and destroying each frame.
- Keep game state in scene or registry data, not in DOM elements.
- Remove event listeners and timers on scene `shutdown` to avoid leaks.

## Vitest

- Co-locate tests next to the code as `*.test.ts(x)`.
- Test behaviour through public APIs; for components use Testing Library queries by role/label.
- Mock network calls at the boundary (e.g. MSW) rather than mocking internal modules.
- Every bug fix adds a test that fails without the fix.

## Reference docs

- [Phaser docs](https://docs.phaser.io)
- [Vitest docs](https://vitest.dev)