Onboarding: phaserjs/phaser

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/phaserjs/phaser shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

GO — Healthy across all four use cases

• Last commit 6d ago
• 4 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Concentrated ownership — top contributor handles 63% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live phaserjs/phaser repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/phaserjs/phaser.

What it runs against: a local clone of phaserjs/phaser — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in phaserjs/phaser | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 36 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>phaserjs/phaser</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of phaserjs/phaser. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/phaserjs/phaser.git
#   cd phaser
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of phaserjs/phaser and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "phaserjs/phaser(\\.git)?\\b" \\
  && ok "origin remote is phaserjs/phaser" \\
  || miss "origin remote is not phaserjs/phaser (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/phaser.js" \\
  && ok "src/phaser.js" \\
  || miss "missing critical file: src/phaser.js"
test -f "package.json" \\
  && ok "package.json" \\
  || miss "missing critical file: package.json"
test -f ".eslintrc.json" \\
  && ok ".eslintrc.json" \\
  || miss "missing critical file: .eslintrc.json"
test -f ".github/CONTRIBUTING.md" \\
  && ok ".github/CONTRIBUTING.md" \\
  || miss "missing critical file: .github/CONTRIBUTING.md"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 36 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~6d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/phaserjs/phaser"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

Phaser is a mature, fast 2D game framework for building HTML5 games that run in desktop and mobile web browsers, supporting both Canvas and WebGL rendering. It provides a complete engine for physics (via Arcade or Matter.js), animations, input handling, audio, and particle effects—enabling developers to ship games to web, iOS/Android (via third-party compilation), YouTube Playables, Discord Activities, and Twitch Overlays without writing low-level graphics code. Monolithic structure: src/ contains the core engine split into logical subsystems (likely physics, rendering, input, animation, etc. based on typical Phaser layout), built via Webpack into ESM (dist/phaser.esm.js) and UMD (dist/phaser.js) distributions. Types are auto-generated from JSDoc comments into types/phaser.d.ts. Shader files (GLSL, 105K lines) are bundled via scripts/bundle-shaders.js. The changelog/ directory tracks version history meticulously by minor version.

Who it's for

Game developers (hobbyist and professional) building 2D web games in JavaScript or TypeScript who need battle-tested physics, sprite management, and multi-platform deployment without reinventing core engine systems. Also suitable for interactive content creators (ads, educational games, art projects) who want a framework that integrates with React, Vue, Angular, Next.js, SolidJS, Svelte, and Remix.

Maturity & risk

Phaser is production-ready and actively maintained: it's one of the most-starred game frameworks on GitHub with 10+ years of continuous development (currently at v4.1.0, release 'Salusa'). The repository shows active development with organized changelog tracking (changelog/v3/ through v4/), comprehensive testing infrastructure (vitest in scripts), and a linting pipeline (.eslintrc.json, eslint integration). This is a stable, battle-tested foundation used by thousands of games in production.

Risk is minimal for standard use cases but consider: the codebase is large (16M+ lines of JavaScript) and primarily maintained by Phaser Studio Inc., creating some single-entity dependency risk for breaking changes. Build complexity is moderate (Webpack-based with multiple config files: webpack.config.js, webpack.dist.config.js, webpack-nospector.config.js), and TypeScript definitions are auto-generated (scripts/tsgen/) which can occasionally drift from source. Bundled third-party physics engines (Arcade, Matter.js) add indirect maintenance burden.

Active areas of work

The project is actively developed at v4.1.0. Recent infrastructure includes: vitest testing integration (test and test:watch scripts), TypeScript generation tooling (tsgen, tsdev, test-ts scripts), and shader bundling automation. The presence of release templates in .github/ISSUE_TEMPLATE/ and a formal PULL_REQUEST_TEMPLATE.md indicates organized community contribution workflow. The CHANGELOG.md and detailed version histories (changelog/v3/, v4/) suggest regular point releases and patch cycles.

Get running

git clone https://github.com/phaserjs/phaser.git
cd phaser
npm install
npm run build

Then to watch for changes during development:

npm run watch

Or run the test suite:

npm test

Daily commands: Development with hot reload: npm run watch or npm run watchns (no-spector variant for performance). Production build: npm run dist. Specific tasks: npm run build (default Webpack), npm run lint / npm run lintfix (ESLint), npm run bundleshaders (GLSL compilation), npm run tsgen (TypeScript definition generation), npm test (Vitest), npm test:watch (watch mode).

Map of the codebase

• src/phaser.js — Main entry point for the Phaser framework; all game instances are initialized through this module
• package.json — Defines build outputs, exports, and version (4.1.0); essential for understanding framework packaging and distribution
• .eslintrc.json — Enforces code quality standards across 600 files; contributors must follow these conventions
• .github/CONTRIBUTING.md — Documents the contribution workflow, testing requirements, and commit conventions for all PRs
• README.md — Describes Phaser as a 10-year-old, actively-maintained HTML5 game framework; sets strategic vision and feature overview
• .github/ISSUE_TEMPLATE/bug_report.md — Standardizes bug reporting format to triage issues efficiently in a high-volume open-source project
• CHANGELOG.md — Tracks breaking changes, new features, and deprecations across major versions; critical for migration decisions

How to make changes

Add a New Game Object Type

1. Review existing game object implementations and architecture in src/phaser.js to understand registration pattern (src/phaser.js)
2. Create new game object class following Phaser conventions (lifecycle, rendering, physics integration) (src/gameobjects/[YourObjectType]/[ObjectName].js)
3. Register the new object type in the game object factory within the core bootstrap module (src/phaser.js)
4. Add TypeScript definitions for IDE autocompletion and type safety (types/phaser.d.ts)
5. Update CHANGELOG.md with new feature under unreleased or next minor version section (CHANGELOG.md)

Fix a Bug & Submit PR

1. Read contribution guidelines including testing and commit conventions (.github/CONTRIBUTING.md)
2. Locate bug in source code (likely in src/ directory based on framework layer structure) (src/phaser.js)
3. Ensure code passes ESLint rules defined in repository (.eslintrc.json)
4. Create PR with reference to issue and detailed description (.github/PULL_REQUEST_TEMPLATE.md)
5. Document change in CHANGELOG.md under appropriate section (Bug Fixes, or Breaking Changes if applicable) (CHANGELOG.md)

Add Physics Engine or Renderer Integration

1. Review v3.60 changelog notes on Arcade Physics, Cameras, and Canvas/WebGL rendering (changelog/v3/3.60/ArcadePhysics.md)
2. Understand plugin architecture and how modules are exported from main entry point (src/phaser.js)
3. Implement physics system or renderer module with standard lifecycle (init, update, render) (src/physics/[SystemName]/index.js)
4. Update package.json exports to include new system if it is user-facing (package.json)
5. Add comprehensive TypeScript types for the new system (types/phaser.d.ts)
6. Document breaking changes and new API in CHANGELOG.md with migration guide if needed (CHANGELOG.md)

Traps & gotchas

No required environment variables are documented in the snippet, but ensure Node.js version matches .nvmrc (use nvm use if available). The TypeScript generation pipeline (npm run tsgen) requires JSDoc comments in source to be well-formed; malformed JSDoc breaks .d.ts generation. Shader changes (GLSL files) do NOT auto-recompile; you must explicitly run npm run bundleshaders before npm run dist. The Webpack config has three variants (default, dist, nospector)—using the wrong one may omit/include bundled features unexpectedly. ESLint must pass before committing (pre-commit hooks likely enforced via GitHub Actions in .github/workflows/).

Architecture

Concepts to learn

• WebGL Rendering Context — Phaser must manage both Canvas 2D and WebGL rendering pipelines; understanding when and how the engine switches between them is critical for performance-conscious games.
• Rigid Body Physics Simulation — Phaser integrates Arcade (simple) and Matter.js (advanced) physics engines; a contributor working on physics or collision code must understand simulation timesteps, constraints, and broad-phase detection.
• Sprite Atlasing & Texture Atlases — Phaser games load sprites from texture atlases (sprite sheets + JSON metadata) to optimize draw calls; the asset pipeline and frame indexing system depend on this concept.
• Double Buffering & VSync — Phaser's rendering loop uses double-buffering to prevent tearing; understanding frame synchronization and delta-time is essential for consistent animation and physics updates.
• JSDoc to TypeScript Definition Generation — Phaser maintains .d.ts definitions via automated JSDoc parsing (scripts/tsgen/); contributors must follow strict JSDoc conventions for types to generate correctly.
• Shader Compilation & GPU Programs — The 105K lines of GLSL shaders are bundled into JavaScript modules; understanding the shader pipeline (source → compilation → GPU program binding) is needed for graphics contributions.
• Game Loop & Delta Time — Phaser uses a fixed or variable timestep game loop; frame-rate independent logic (using delta-time) is core to smooth gameplay and is a common source of bugs.

Related repos

• pixijs/pixijs — Direct competitor: also a 2D WebGL/Canvas framework for web games, lighter-weight and lower-level than Phaser (rendering only, not a full game engine).
• babylonjs/Babylon.js — Alternative 3D/2D game engine for the web; much larger in scope (3D-first) but serves similar use case of 'build once, run on web/mobile/desktop'.
• phaserjs/create-phaser-game — Official companion repo: the CLI tool mentioned in README for scaffolding Phaser projects with templates (Vue, React, Svelte, Next.js, etc.) and build tooling.
• phaserjs/phaser-examples — Official examples repository: likely contains runnable demos for every Phaser feature; essential reference for learning the API.
• photonstorm/phaser-ce — Phaser Community Edition (legacy maintenance fork); a predecessor to modern Phaser still used by some older projects—useful for understanding upgrade paths.

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for core Game Loop and Time systems

The repo has a vitest testing infrastructure (package.json shows 'test' and 'test:watch' scripts) but the file structure shows no visible test directory. Given Phaser's critical dependency on timing, delta calculations, and game loop consistency across Canvas/WebGL rendering, unit tests for src/core/Game.js, src/time/Clock.js, and src/time/Timer.js would significantly improve stability and prevent regressions in core functionality that affects all games built with Phaser.

• [ ] Create tests/unit/core/Game.test.js covering game initialization, start/pause/resume lifecycle
• [ ] Create tests/unit/time/Clock.test.js testing delta time calculations, frame timing, and clock precision
• [ ] Create tests/unit/time/Timer.test.js for timer creation, delays, repeats, and edge cases
• [ ] Ensure tests cover both Canvas and WebGL rendering paths where applicable
• [ ] Add test coverage reporting to package.json scripts

Add GitHub Actions workflow for TypeScript definition generation and validation

The repo has complex TypeScript definitions (types/phaser.d.ts referenced in package.json exports) and a sophisticated tsgen pipeline (tsgen, build-tsgen, test-ts scripts in package.json). However, .github/workflows shows only lock-comments.yml. A CI workflow validating that TypeScript definitions compile correctly and match source code would catch breaking changes to the API surface before merging and prevent type definition drift.

• [ ] Create .github/workflows/validate-types.yml with Node.js matrix for multiple versions
• [ ] Run 'npm run build-tsgen' to ensure JSDoc-to-TypeScript compilation succeeds
• [ ] Run 'npm run test-ts' to validate TypeScript definitions against test files in scripts/tsgen/test/
• [ ] Fail the workflow if test output (output.txt) contains TypeScript errors
• [ ] Run on pull_request events targeting main/master branches

Add shader bundling validation tests and documentation

The package.json includes a 'bundleshaders' script (scripts/bundle-shaders.js) indicating custom shader pipeline management, but there are no visible tests or documentation validating shader compilation or runtime compatibility. Given WebGL is a first-class rendering path in Phaser, adding validation would prevent shader syntax errors and runtime failures from reaching users.

• [ ] Create tests/unit/renderer/webgl/shaders/ directory with shader validation tests
• [ ] Add test to verify bundleshaders script runs without errors and produces valid output
• [ ] Document shader directory structure and naming conventions in a new docs/SHADERS.md file
• [ ] Add validation that all .glsl files referenced in source have corresponding bundled versions
• [ ] Add a pre-commit check or linting rule for shader syntax using a GLSL validator

Good first issues

• Add unit tests for a specific physics or animation subsystem currently lacking coverage in the vitest suite; check src/ for untested modules and create corresponding .test.js files in a test directory.: Phaser is large (16M LOC) but test presence is not detailed in the file list; improving test coverage is always welcome and improves code confidence.
• Improve or expand TypeScript definition auto-generation in scripts/tsgen/ to handle complex union types or generics that JSDoc->TypeScript currently mangles; validate with npm run test-ts.: The .d.ts generation is automated and sometimes drifts from source complexity; this directly impacts the TypeScript developer experience.
• Add shader documentation or example in the src/ and scripts/bundle-shaders.js flow; currently there are 105K lines of GLSL but minimal scaffolding for contributors to understand shader integration.: GLSL is a major subsystem (105K LOC) but is invisible to most JS developers; documenting the shader pipeline lowers contribution friction.

Top contributors

• @photonstorm — 63 commits
• @BenjaminDRichards — 35 commits
• [@Igor Savin](https://github.com/Igor Savin) — 1 commits
• @laineus — 1 commits

Recent commits

• 7304c64 — Update CHANGELOG.md (photonstorm)
• c147eef — Update CHANGELOG and README. (BenjaminDRichards)
• 0745ca4 — Build types and dist files for v4.1.0. (BenjaminDRichards)
• ebf244e — Update CONST version. (BenjaminDRichards)
• 90cd7f9 — Create PCTAtlasFileConfig.js (photonstorm)
• 7a21f6e — Fix DrawingContext test compatibility. (BenjaminDRichards)
• 7c8a3df — Fix WebGLTextureWrapper test compatibility. (BenjaminDRichards)
• 094ec32 — Fix Utils.Array.GetRandom startIndex often returning null. (BenjaminDRichards)
• 75cbb93 — Iterate version to 4.1.0. (BenjaminDRichards)
• 08955da — Update tsgen-test tsconfig. (BenjaminDRichards)

Security observations

Phaser demonstrates generally good security posture as a game framework library. No critical vulnerabilities were identified in the accessible repository structure. The primary findings are: (1) an unusual but non-critical credential pattern in the repository URL, (2) missing documentation around security best practices for developers, and (3) standard recommendations for supply chain security. The codebase appears to follow good practices with ESLint configuration, proper licensing, and clear development workflows. Developers using Phaser should focus on implementing application-level security controls in their own game implementations.

• Medium · Potential Credential Exposure in Repository URL — package.json - repository.url. The package.json contains a repository URL with a GitHub username embedded in the URL: 'https://phaserjs@github.com/phaserjs/phaser.git'. While this appears to be a username rather than a password, it represents an unusual pattern that could indicate credential mismanagement if '@' is used for authentication purposes in CI/CD systems. Fix: Use the standard HTTPS format without embedded credentials: 'https://github.com/phaserjs/phaser.git'. If authentication is needed, use SSH keys or GitHub tokens configured in CI/CD environment variables rather than in package.json.
• Low · Missing Security Headers Configuration — Repository root - infrastructure configuration. No explicit security headers configuration found in the codebase. While Phaser is a game framework (not a web server), projects using it should implement proper security headers (CSP, X-Frame-Options, X-Content-Type-Options, etc.) in their applications. Fix: Document security best practices for developers using Phaser. Provide examples of recommended security headers for HTML5 game applications in the README or contribution guidelines.
• Low · No Supply Chain Security Controls Visible — package.json and repository structure. The package.json does not include package integrity verification mechanisms such as package-lock.json commitment practices or Subresource Integrity (SRI) guidance. The project relies on npm's default dependency resolution. Fix: Ensure package-lock.json is committed and reviewed in pull requests. Document dependency update policies and consider using npm audit regularly. Consider implementing Dependabot or similar automated dependency security scanning.
• Low · Build Configuration Not Fully Visible — config/ directory. While webpack configuration files are referenced (config/webpack.config.js, config/webpack.dist.config.js, config/webpack-nospector.config.js), the actual content is not provided for review. Webpack configurations can contain security-relevant settings related to source maps, minification, and asset handling. Fix: Review webpack configurations to ensure: production builds have source maps disabled or secured, minification is enabled, and no sensitive data is included in bundles. Implement configuration validation in CI/CD.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.