Back to Details

phaser-best-practices

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Building Phaser Games

构建Phaser游戏

When to use this skill

何时使用本技能

Use this skill when the user wants to:
  • create a new Phaser 3 game or prototype
  • add or refactor scenes, entities, UI, physics, tilemaps, input, audio, or cameras
  • debug Phaser-specific behavior such as scene restarts, blurry pixel art, collider bugs, asset loading problems, or animation issues
  • improve architecture, maintainability, or runtime performance in a Phaser project
Do not use this skill for non-Phaser engines unless the user explicitly wants Phaser-style patterns adapted elsewhere.
当用户有以下需求时使用本技能：
  • 创建新的Phaser 3游戏或原型
  • 添加或重构场景、实体、UI、物理系统、瓦片地图、输入、音频或相机
  • 调试Phaser特有问题，比如场景重启、像素 art 模糊、碰撞器bug、资源加载问题或动画异常
  • 提升Phaser项目的架构合理性、可维护性或运行时性能
请勿将本技能用于非Phaser引擎的项目，除非用户明确要求适配Phaser风格的设计模式到其他引擎。

How to operate

如何使用

1. Triage the request

1. 需求分类

Classify the task before writing code:
  • New project: scaffolding, folder layout, game config, first scenes
  • Feature work: add gameplay, UI, audio, transitions, tilemaps, enemies, pickups
  • Bug fix: isolate scene lifecycle, asset, physics, input, camera, or rendering failure
  • Optimization: profile bottlenecks, pooling, culling, throttling, asset strategy
  • Art / asset pipeline: spritesheet measurements, animation setup, nine-slice / three-slice UI, tilemap integration
编写代码前先对任务进行分类：
  • 新项目：脚手架搭建、目录结构设计、游戏配置、初始场景开发
  • 功能开发：添加玩法、UI、音频、转场效果、瓦片地图、敌人、收集物
  • bug修复：定位场景生命周期、资源、物理系统、输入、相机或渲染故障
  • 优化：分析性能瓶颈、对象池、视锥体剔除、节流控制、资源加载策略
  • 美术/资源管线：精灵表尺寸测量、动画配置、NineSlice/ThreeSlice UI、瓦片地图集成

2. Inspect first, then decide

2. 先调研现有代码，再做决策

When a repository already exists, inspect before proposing structure changes:
  • package.json, bundler config, tsconfig/jsconfig
  • Phaser version and whether the codebase is JS or TS
  • game bootstrap, scene list, physics config, scale config
  • asset folders and naming conventions
  • current state-sharing approach (scene data, registry, services, globals)
  • whether the project is pixel art, HD art, desktop-first, mobile-first, or mixed input
Prefer adapting to the existing codebase over replacing it with boilerplate.
如果已有代码仓库，在提议结构变更前先调研现有代码：
  • package.json、打包工具配置、tsconfig/jsconfig
  • Phaser版本，以及代码库是JS还是TS编写
  • 游戏启动逻辑、场景列表、物理系统配置、缩放配置
  • 资源目录和命名规范
  • 当前的状态共享方案（场景数据、registry、服务、全局变量）
  • 项目是像素art、HD美术、优先桌面端、优先移动端还是混合输入类型
优先适配现有代码库，而不是直接用模板代码替换原有实现。

3. Default technical choices

3. 默认技术选型

Use these defaults unless the task clearly calls for something else:
  • Prefer the official Vite + TypeScript style setup for new projects
  • Prefer Arcade Physics for platformers, shooters, top-down action, simple pickups, and lightweight collision logic
  • Use Matter Physics only when the game needs rotation-driven collisions, compound bodies, constraints, stacking stability, or more realistic simulation
  • Organize code around Scenes first, then entities / systems inside scenes
  • Keep input scene-owned; entities should consume input state, not attach their own listeners
  • Use global animations when multiple sprites share the same animation data
  • Preload startup-critical assets up front; load level-specific assets later when it improves startup time
  • Use built-in NineSlice / ThreeSlice for scalable UI art when the texture layout supports it; only fall back to custom compositing when transparent padding or discontinuous art breaks built-in slicing
  • Use FIT scaling for most games, RESIZE for editor-like or UI-heavy layouts, and NONE only when manually controlling canvas sizing
  • For pixel art, enable pixelArt mode, favor integer scaling where possible, and avoid sub-pixel camera movement
除非任务明确要求其他方案，否则使用以下默认选型：
  • 新项目优先使用官方推荐的Vite + TypeScript风格配置
  • 平台跳跃、射击、俯视角动作、简单收集物、轻量碰撞逻辑类游戏优先使用Arcade Physics
  • 仅当游戏需要基于旋转的碰撞、复合碰撞体、约束、堆叠稳定性或更真实的物理模拟时，才使用Matter Physics
  • 代码组织优先围绕场景展开，再在场景内拆分实体/系统
  • 输入逻辑由场景统一管理；实体只消费输入状态，不自行绑定输入监听器
  • 多个精灵共享同一套动画数据时使用全局动画
  • 启动关键资源提前预加载；如果能提升启动速度，关卡专属资源可以后续加载
  • 纹理布局支持时，使用内置的NineSlice/ThreeSlice实现可缩放UI美术；仅当透明内边距或不连续美术导致内置切片失效时，才 fallback 到自定义合成方案
  • 大多数游戏使用FIT缩放模式，编辑器类或UI密集型布局使用RESIZE，仅当手动控制canvas尺寸时使用NONE
  • 像素art项目启用pixelArt模式，尽可能使用整数倍缩放，避免相机亚像素移动

4. Output expectations

4. 输出要求

For new games, provide:
  • the recommended folder structure
  • a game config
  • scene list and responsibilities
  • starter code that runs
  • notes on why each architectural choice fits the requested genre
For feature work or bug fixes, provide:
  • minimal targeted edits
  • root cause explanation
  • the patch
  • validation steps the user can run immediately
For architecture advice, provide:
  • the smallest structure that solves the current problem
  • one recommended path, not a menu of equally-weighted options
  • explicit tradeoffs when the choice is important (for example Arcade vs Matter)
针对新游戏，需提供：
  • 推荐的目录结构
  • 游戏配置
  • 场景列表和各场景职责
  • 可运行的初始代码
  • 说明每个架构选型适配需求游戏类型的原因
针对功能开发或bug修复，需提供：
  • 最小范围的定向修改
  • 根因说明
  • 补丁代码
  • 用户可立即执行的验证步骤
针对架构建议，需提供：
  • 能解决当前问题的最简结构
  • 一条推荐路径，而非多个权重相同的可选方案
  • 选型有重要影响时明确说明取舍（比如Arcade和Matter的差异）

Non-negotiable implementation rules

不可违背的实现规则

  • Respect the project's existing JS vs TS choice unless the user asks to migrate
  • Centralize scene keys, asset keys, collision categories, and balance constants
  • Keep 
    update()
    orchestration-focused; push detailed logic into entities or systems
  • Register cleanup for scene shutdown / destroy when you attach listeners, timers, tweens, or long-lived references
  • Avoid creating new objects inside hot 
    update()
    loops unless profiling proves it is harmless
  • Do not make every object interactive or physics-enabled by default
  • Do not assume spritesheet frame dimensions; inspect and verify them
  • Do not tell the user to use Matter when Arcade already solves the problem cleanly
  • Do not preload the entire game into one Boot scene just because it is convenient
  • 尊重项目现有JS/TS选型，除非用户要求迁移
  • 统一管理场景key、资源key、碰撞分类和数值平衡常量
  • update()
    方法只做编排逻辑；把具体逻辑下沉到实体或系统中
  • 绑定监听器、定时器、补间动画或长生命周期引用时，要注册场景关闭/销毁时的清理逻辑
  • 不要在热点
    update()
    循环中创建新对象，除非性能分析证明这样做没有影响
  • 不要默认给所有对象开启交互或物理特性
  • 不要假设精灵表的帧尺寸；要检查并确认实际尺寸
  • 当Arcade已经可以干净地解决问题时，不要让用户使用Matter
  • 不要为了方便就把整个游戏的资源都放在同一个Boot场景预加载

Recommended delivery workflow

推荐交付流程

New Phaser project

新Phaser项目

  1. Pick the architecture size:
    • Small / jam game: 2-4 scenes, lightweight service modules
    • Mid-size game: scenes + entities + systems + constants
    • Large content-heavy game: data-driven content, scene services, dedicated state layer
  2. Define the base config: renderer, scale mode, physics, pixel-art settings
  3. Create startup scenes first: Boot, Menu, Game, UI; add Pause / GameOver only if required
  4. Add one vertical slice that proves the core loop works
  5. Add reference-driven systems next: audio, saveable state, enemy spawning, tilemaps, UI polish
  1. 确定架构规模：
    • 小型/游戏 jam 项目：2-4个场景，轻量服务模块
    • 中等规模游戏：场景 + 实体 + 系统 + 常量
    • 大型重内容游戏：数据驱动内容、场景服务、独立状态层
  2. 定义基础配置：渲染器、缩放模式、物理系统、像素art设置
  3. 先创建启动相关场景：Boot、Menu、Game、UI；仅当需要时添加Pause/GameOver场景
  4. 实现一个垂直切片验证核心玩法循环可行
  5. 接下来添加依赖引用的系统：音频、可存档状态、敌人生成、瓦片地图、UI打磨

Adding or refactoring a feature

添加或重构功能

  1. Locate the owning scene and affected systems
  2. Identify the smallest correct insertion point
  3. Reuse existing helpers, constants, managers, and pools
  4. Add cleanup and validation steps with the change
  5. Preserve scene restart safety
  1. 找到所属场景和受影响的系统
  2. 确定最小范围的正确插入点
  3. 复用现有工具函数、常量、管理器和对象池
  4. 随变更添加清理和验证步骤
  5. 保证场景重启安全

Debugging

调试

  1. Reproduce the issue from the code and config
  2. Identify whether the fault is:
    • lifecycle / restart
    • asset dimensions or loader config
    • physics body setup or collider order
    • scale / camera / pixel rounding
    • stale listeners, timers, or pooled object state
  3. Patch the root cause, not just the symptom
  4. Provide a quick repro or verification checklist
  1. 通过代码和配置复现问题
  2. 定位故障类型：
    • 生命周期/重启问题
    • 资源尺寸或加载器配置问题
    • 物理体配置或碰撞器顺序问题
    • 缩放/相机/像素取整问题
    • 过期监听器、定时器或对象池状态问题
  3. 修复根因，而非只解决表面症状
  4. 提供快速复现或验证清单

Reference map

参考文档映射

Read only the files relevant to the task:
  • Setup / bootstrap / config: references/setup-and-build.md
  • Scenes / shared state / architecture: references/scenes-state-architecture.md
  • Physics / entities / pooling: references/physics-and-entities.md
  • Assets / animations / UI panels: references/assets-animation-ui.md
  • Tilemaps / camera / input / audio: references/tilemaps-camera-input-audio.md
  • Performance / debugging / cleanup: references/performance-debugging.md
  • Code review / architecture checklist: references/review-checklist.md
仅阅读和任务相关的文件：
  • 配置/启动/构建：references/setup-and-build.md
  • 场景/共享状态/架构：references/scenes-state-architecture.md
  • 物理系统/实体/对象池：references/physics-and-entities.md
  • 资源/动画/UI面板：references/assets-animation-ui.md
  • 瓦片地图/相机/输入/音频：references/tilemaps-camera-input-audio.md
  • 性能/调试/清理：references/performance-debugging.md
  • 代码评审/架构检查清单：references/review-checklist.md

Concrete examples

具体示例

Example: "Create a Phaser top-down shooter"

示例："创建一个Phaser俯视角射击游戏"

Use this skill. Default to:
  • Vite + TypeScript structure
  • Arcade Physics
  • Boot, Menu, Game, UI scenes
  • scene-owned input mapping
  • pooled bullets
  • global animations
  • camera follow and world bounds
  • asset keys / scene keys in constants
Then deliver runnable starter code plus the first playable loop.
使用本技能。默认选型：
  • Vite + TypeScript结构
  • Arcade Physics
  • Boot、Menu、Game、UI场景
  • 场景统一管理的输入映射
  • 子弹对象池
  • 全局动画
  • 相机跟随和世界边界
  • 常量中统一管理资源key/场景key
然后交付可运行的初始代码和第一个可玩的玩法循环。

Example: "My pixel art looks blurry on mobile"

示例："我的像素art在移动端看起来模糊"

Use this skill. Inspect:
  • pixelArt
    and 
    roundPixels
    settings
  • camera follow rounding
  • scale mode and zoom strategy
  • CSS around the canvas container
  • whether art is being scaled non-integer
Then patch the smallest set of config and camera settings required.
使用本技能。检查：
  • pixelArt
    和
    roundPixels
    配置
  • 相机跟随取整逻辑
  • 缩放模式和缩放策略
  • canvas容器的CSS配置
  • 美术是否被非整数倍缩放
然后修复所需的最少配置和相机设置即可。

Example: "Paper UI panels show weird side bars"

示例："纸张UI面板显示奇怪的侧边栏"

Use this skill. Inspect the source texture first. Then:
  • try built-in ThreeSlice / NineSlice if the art is a true 3-slice or 9-slice layout
  • if frames contain large transparent padding or discontinuous art, use trimmed or composited fallback slices
  • document the measured frame sizes, spacing, margins, and any overlap used
使用本技能。首先检查源纹理，然后：
  • 如果美术确实符合3切片或9切片布局，尝试内置的ThreeSlice/NineSlice
  • 如果帧包含大量透明内边距或不连续美术，使用裁剪或合成的 fallback 切片方案
  • 记录测量的帧尺寸、间距、边距和使用的任何重叠参数

Common traps

常见陷阱

Avoid these unless the user explicitly wants them:
  • one giant 
    GameScene
    that owns menus, HUD, gameplay, pause, and transitions
  • state stored on 
    window
    , random module globals, or ad hoc singleton soup
  • entity-owned keyboard listeners
  • scene restart bugs caused by forgotten shutdown cleanup
  • loading every future asset in the first scene
  • manual nine-slice composition when built-in NineSlice already fits the asset
  • over-engineering with ECS for tiny games that only need a few entity classes
除非用户明确要求，否则避免以下做法：
  • 一个巨型
    GameScene
    同时管理菜单、HUD、玩法、暂停和转场
  • 状态存储在
    window
    、随机的模块全局变量或临时的单例堆中
  • 实体自行绑定键盘监听器
  • 忘记关闭清理逻辑导致的场景重启bug
  • 第一个场景就加载所有未来会用到的资源
  • 内置NineSlice已经适配资源时，还手动实现9切片合成
  • 仅需要少量实体类的小型游戏过度使用ECS做工程设计

Final check before responding

响应前最终检查

Make sure the answer:
  • matches the user's genre, platform, and art style
  • uses Phaser 3 APIs, not Phaser 4 RC APIs
  • chooses a physics system deliberately
  • keeps SKILL.md-level advice concise and moves detail into references
  • includes validation steps when code is produced
确保回答：
  • 匹配用户的游戏类型、平台和美术风格
  • 使用Phaser 3 API，而非Phaser 4 RC API
  • 有意识地选择物理系统
  • 保持SKILL.md级别的建议简洁，详细内容放到参考文档中
  • 提供代码时包含验证步骤