Repository Guidelines
Project Structure & Module Organization
The Phaser game source lives in src/, organised by feature (e.g., core/ bootstraps the game, scenes/ drives flow, systems/ holds gameplay logic). Tests mirror the runtime folders under tests/, using matching filenames for unit, system, and integration coverage. Static assets ship from assets/ while public HTML scaffolding sits in public/; Vite build presets reside in vite/, and generated bundles land in dist/.
Build, Test & Development Commands
npm install: sync dependencies before your first run or when package updates land.npm run dev: start the Vite dev server with the logging overlay (log.js) for quick iteration.npm run build: produce a production bundle usingvite/config.prod.mjs.npm run test: open Vitest in watch mode with the Phaser mocks fromtests/setup.ts.npm run test:run: execute the full suite once, ideal for CI.npm run test:ui: launch the Vitest UI when you need to debug snapshots or flaky specs.
Coding Style & Naming Conventions
Target TypeScript 5.x with ES modules and Phaser 3 APIs. Use two-space indentation, trailing semicolons, and double quotes (existing files are consistent). Prefer descriptive class names (AsteroidSpawner, ShardManager) and align helper files under utils/. Import project modules via the @/ alias instead of relative paths when referencing src/.
Testing Guidelines
Vitest with a jsdom environment is mandatory for new code; include focused unit tests plus higher-level integrations when behavior spans systems. Name files *.test.ts alongside the feature (tests/systems/ShardManager.test.ts) and reset spies between cases. Run npm run test:run before pushing, and keep Phaser mocks in tests/setup.ts up to date when engine contracts change.
Commit & Pull Request Guidelines
Follow the conventional type(scope): summary pattern (feat(gameplay): add shard attraction); keep summaries under 72 characters and use scopes that map to repo folders. Commits should remain atomic: refactors separate from feature commits, tests updated with their code. Pull requests need a concise description of the change, screenshots or GIFs for visible updates, links to relevant issues, and a checklist of manual or automated tests you ran.
Assets & Configuration Tips
Place art and audio in assets/ and reference them via Phaser loaders; avoid committing generated textures. Update README.md and docs/ when gameplay rules shift. Adjust renderer, physics, or logging defaults through vite/config.dev.mjs and vite/config.prod.mjs rather than ad-hoc environment variables.