phaser-gamedev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Phaser Game Development

Phaser 游戏开发

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

使用Phaser 3的基于场景的架构和物理系统构建2D浏览器游戏。

STOP: Before Loading Any Spritesheet

注意：加载任何精灵表之前

Read spritesheets-nineslice.md FIRST.

Spritesheet loading is fragile—a few pixels off causes silent corruption that compounds into broken visuals. The reference file contains the mandatory inspection protocol.

Quick rules (details in reference):

Measure the asset before writing loader code—never guess frame dimensions
Character sprites use SQUARE frames: If you calculate frameWidth=56, try 56 for height first
Different animations have different frame sizes: A run cycle needs wider frames than idle; an attack needs extra width for weapon swing. Measure EACH spritesheet independently
Check for spacing: Gaps between frames require
```
spacing: N
```
in loader config

Verify the math:

imageWidth = (frameWidth × cols) + (spacing × (cols - 1))

请先阅读spritesheets-nineslice.md。

精灵表加载过程很敏感，哪怕差几个像素也会导致隐性损坏，最终引发视觉显示问题。参考文件中包含了必须遵循的检查流程。

快速规则（详情见参考文件）：

测量资源尺寸：编写加载器代码前务必测量资源，绝不要猜测帧的尺寸
角色精灵使用正方形帧：如果计算得出frameWidth=56，优先尝试将高度也设为56
不同动画对应不同帧尺寸：奔跑动画的帧比待机状态的帧更宽；攻击动画需要额外宽度来展示武器挥动。请独立测量每个精灵表的尺寸
检查间距：帧之间存在间隙时，需要在加载器配置中设置
```
spacing: N
```

验证计算公式：

imageWidth = (frameWidth × cols) + (spacing × (cols - 1))

Reference Files

参考文件

Read these BEFORE working on the relevant feature:

When working on...	Read first
Loading ANY spritesheet	spritesheets-nineslice.md
Nine-slice UI panels	spritesheets-nineslice.md
Config, scenes, objects, input, animations	core-patterns.md
Tiled tilemaps, collision layers	tilemaps.md
Physics tuning, groups, pooling	arcade-physics.md
Performance issues, object pooling	performance.md

在开发相关功能前，请先阅读以下文件：

开发以下功能时...	先阅读
加载任何精灵表	spritesheets-nineslice.md
九切片UI面板	spritesheets-nineslice.md
配置、场景、对象、输入、动画	core-patterns.md
Tiled瓦片地图、碰撞层	tilemaps.md
物理系统调优、组、对象池	arcade-physics.md
性能问题、对象池	performance.md

Architecture Decisions (Make Early)

架构决策（尽早确定）

Before building, decide:

What scenes does this game need? (Boot, Menu, Game, UI overlay, GameOver)
What are the core entities and how do they interact?
What physics model fits? (Arcade for speed, Matter for realism, None for menus)
What input methods? (keyboard/gamepad/touch)

开始开发前，请确定以下内容：

游戏需要哪些场景？（启动场景、菜单场景、游戏场景、UI覆盖层、游戏结束场景）
核心实体有哪些？它们之间如何交互？
适合使用哪种物理模型？（Arcade追求速度，Matter追求真实感，菜单场景无需物理系统）
支持哪些输入方式？（键盘/游戏手柄/触摸）

Physics System Choice

物理系统选择

System	Use When
Arcade	Platformers, shooters, most 2D games. Fast AABB collisions
Matter	Physics puzzles, ragdolls, realistic collisions. Slower, more accurate
None	Menu scenes, visual novels, card games

系统	适用场景
Arcade	平台跳跃类、射击类及大多数2D游戏。AABB碰撞检测速度快
Matter	物理解谜类、布娃娃效果、真实碰撞场景。速度较慢，但精度更高
无	菜单场景、视觉小说、卡牌游戏

Core Principles

核心原则

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

场景优先架构：围绕场景的生命周期与转场来组织代码
组合优于继承：通过精灵/刚体/控制器来构建实体，而非使用深层类继承结构
物理感知设计：尽早确定碰撞模型，不要在后期再补加物理系统
资源流程规范：预加载所有资源；通过键名引用资源；确保加载过程可预测
帧率无关性：使用
```
delta
```
处理运动和计时器；避免通过计数帧数来实现逻辑

Anti-Patterns

反模式

Anti-Pattern	Problem	Solution
Global state on `window`	Scene transitions break state	Use scene data, registries
Loading in `create()`	Assets not ready when referenced	Load in `preload()` , use Boot scene
Frame counting	Game speed varies with FPS	Use `delta / 1000`
Matter for simple collisions	Unnecessary complexity	Arcade handles most 2D games
One giant scene	Hard to extend	Separate gameplay/UI/menus
Magic numbers	Impossible to balance	Config objects, constants
No object pooling	GC stutters	Groups with `setActive(false)`

反模式	问题	解决方案
在 `window` 上存储全局状态	场景转场会破坏状态	使用场景数据、注册中心
在 `create()` 中加载资源	引用资源时可能尚未加载完成	在 `preload()` 中加载，使用启动场景
计数帧数	游戏速度会随FPS变化	使用 `delta / 1000`
用Matter处理简单碰撞	引入不必要的复杂度	大多数2D游戏使用Arcade即可
单个超大场景	难以扩展	将游戏玩法、UI、菜单分离为不同场景
魔法数字	无法平衡调整	使用配置对象、常量
不使用对象池	垃圾回收导致卡顿	使用带有 `setActive(false)` 的组

Variation Guidance

变体开发指南

Outputs should vary based on:

Genre (platformer vs top-down vs shmup)
Target platform (mobile touch, desktop keyboard, gamepad)
Art style (pixel art scaling vs HD smoothing)
Performance envelope (many sprites → pooling; few sprites → simpler code)

输出内容应根据以下因素调整：

游戏类型（平台跳跃类、俯视角类、弹幕射击类）
目标平台（移动端触摸、桌面端键盘、游戏手柄）
美术风格（像素艺术缩放、高清平滑渲染）
性能范围（精灵数量多→使用对象池；精灵数量少→使用更简洁的代码）

Remember

注意事项

Phaser provides 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.

Codex can build complete, polished Phaser games. These guidelines illuminate the path—they don't fence it.

Phaser提供了强大的基础组件：场景、精灵、物理系统、输入，但架构设计由你负责。

以系统思维思考：先定义场景、定义实体、定义它们的交互方式，再进行实现。

Codex可以构建完整、精致的Phaser游戏。这些指南为你指明方向，而非限制你的思路。