AgentSkillsCN

phaser-gamedev

适用于使用Phaser 3（JS/TS）开发2D浏览器游戏的场景，可实现基于场景的架构设计、物理系统、瓦片地图、精灵动画，或通过池化与剔除技术优化游戏性能。

SKILL.md
--- frontmatter
name: phaser-gamedev
description: "Use when building 2D browser games with Phaser 3 (JS/TS), implementing scene-based architecture, physics systems, tilemaps, sprite animations, or optimizing game performance with pooling and culling."
allowed-tools: Read, Bash, Grep, Glob

Phaser Game Development

Build fast, polished 2D browser games using Phaser 3's scene-based architecture and physics systems.

Philosophy: Games as Living Systems

Games are not static UIs—they are dynamic systems where entities interact, state evolves, and player input drives everything.

Before building, ask:

  • •What scenes does this game need? (Boot, Menu, Game, Pause, GameOver, UI overlay)
  • •What are the core entities and how do they interact?
  • •What state must persist across scenes (and what must not)?
  • •What physics model fits? (Arcade for speed, Matter for realism)
  • •What input methods will players use? (keyboard/gamepad/touch)

Core principles:

  1. •Scene-first architecture: Organize code around scene lifecycle and transitions.
  2. •Composition over inheritance: Build entities from sprite/body/controllers, not deep class trees.
  3. •Physics-aware design: Choose collision model early; don't retrofit physics late.
  4. •Asset pipeline discipline: Preload everything; reference by keys; keep loading deterministic.
  5. •Frame-rate independence: Use delta for motion and timers; avoid frame counting.

Workflow: Build the Spine First

  • •Define the minimal playable loop (movement + win/lose + restart) before content/polish.
  • •Decide scene graph and transitions (including UI overlay scene if needed).
  • •Choose physics system early:
    • •Arcade for most games (platformers/top-down/shooters).
    • •Matter for realistic collision/constraints/ragdolls.
    • •None for non-physics scenes (menus, VN, card games).
  • •Implement a reliable asset-loading path (Boot scene), then scale out content.
  • •Add debug toggles/profiling early so performance doesn't become a late surprise.

References (Progressive Disclosure)

  • •references/core-patterns.md: config, scene lifecycle, objects, input, animations, asset loading, project structure.
  • •references/arcade-physics.md: Arcade physics deep dive (including pooling patterns).
  • •references/tilemaps.md: Tiled tilemap workflows, collision setup, object layers.
  • •references/performance.md: optimization strategies (pooling, batching, culling, camera, texture atlases).
  • •references/spritesheets-nineslice.md: spritesheet loading (spacing/margin), nine-slice UI panels, asset inspection protocol.
  • •references/version-gotchas.md: v3.86–v3.90 breaking changes, camera system, audio gotchas, scene transitions.

Quick Reference: Version Awareness

Current stable: Phaser 3.90 "Tsugumi" (May 2025)

Critical gotchas agents must know:

  • •DynamicTexture/RenderTexture default to forceEven: true since v3.88 — odd sizes round up silently
  • •Arcade Physics circle separation was broken before v3.88 — old workarounds are now unnecessary
  • •iOS 17.5+ audio stops on tab focus changes — handled automatically since v3.88
  • •scrollFactor values other than 1 are NOT used in physics collision calculations
  • •Hex tilemap pixel dimensions were miscalculated before v3.88

See references/version-gotchas.md for the full list.

Anti-Patterns to Avoid

Anti-PatternWhy BadBetter
Global state soup (window.* / module globals)Scene transitions become fragile; debugging chaoticScene data, registries, or a dedicated state manager
Loading in create()Assets may not be ready when referencedLoad in preload(); use a Boot scene
Frame-dependent logic (frame count)Game speed varies with frame rateScale by (delta / 1000)
Physics overkill (Matter for simple collisions)Unnecessary complexity + perf costArcade covers most 2D needs
Monolithic scenesHard to extend; UI/menus/pause become hacksSeparate gameplay vs UI overlay vs menus
Magic numbers everywhereBalancing painful; changes cause regressionsConfig objects/constants
No pooling for spammy objectsGC spikes cause stuttersObject pooling with groups
Assuming spritesheet frame dimensionsWrong dims cause silent corruptionOpen asset, measure, calculate with spacing/margin
Ignoring spritesheet spacingFrames shift progressivelyCheck source for gaps; use spacing: N
Scaling discontinuous UI artTransparent gutters scale tooSlice and stitch cached textures

Variation Guidance

Outputs should vary based on:

  • •Genre (platformer vs top-down vs shmup changes physics/input/camera)
  • •Target platform (mobile touch, desktop keyboard, gamepad support)
  • •Art style (pixel art scaling vs HD smoothing; atlas usage)
  • •Performance envelope (many sprites -> pooling/culling; few sprites -> simpler code)
  • •Team size / complexity (prototype vs production architecture)

Avoid converging on one "default" resolution, always defaulting to Arcade, or copy-pasting boilerplate without adapting.

Remember

Phaser gives powerful primitives—scenes, sprites, physics, input—but architecture is your responsibility.

Think in systems: define the scenes, define the entities, define their interactions—then implement.

AI agents are capable of building complete, polished Phaser games. These guidelines illuminate the path—they don't fence it.