Back to Details

phaser-gamedev

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Phaser Game Development

Phaser游戏开发

Build fast, polished 2D browser games using Phaser 3’s scene-based architecture and physics systems.
使用Phaser 3的场景化架构和物理系统，构建流畅、精致的2D浏览器游戏。

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.
游戏并非静态UI——它们是动态系统，其中实体相互作用、状态不断演变，玩家输入驱动一切。
开发前需明确：
  • 这款游戏需要哪些场景？（启动、菜单、游戏、暂停、游戏结束、UI浮层）
  • 核心实体有哪些，它们如何交互？
  • 哪些状态需要在场景间持久化（哪些不需要）？
  • 适合采用哪种物理模型？（Arcade追求速度，Matter追求真实感）
  • 玩家将使用哪些输入方式？（键盘/游戏手柄/触控）
核心原则：
  1. 以场景为核心的架构：围绕场景生命周期与切换组织代码。
  2. 组合优于继承：通过精灵/刚体/控制器构建实体，而非深层类继承结构。
  3. 物理感知设计：尽早选定碰撞模型；避免后期再补加物理系统。
  4. 规范资源管线：预加载所有资源；通过键名引用；确保加载过程可预测。
  5. 帧率无关性：使用
    delta
    处理运动与计时器；避免依赖帧数计数。

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.
  • 在添加内容/打磨细节前，先定义最小可玩循环（移动+胜负判定+重启）。
  • 确定场景图与切换逻辑（如需UI浮层场景也需明确）。
  • 尽早选定物理系统：
    • Arcade：适用于大多数游戏（平台跳跃/俯视角/射击类）。
    • Matter：适用于需要真实碰撞/约束/布娃娃效果的场景。
    • 无物理系统：适用于非物理类场景（菜单、视觉小说、卡牌游戏）。
  • 实现可靠的资源加载流程（启动场景），再逐步扩展内容。
  • 尽早添加调试开关/性能分析功能，避免后期出现性能问题。

Use 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/core-patterns.md
    ：配置、场景生命周期、对象、输入、动画、资源加载、项目结构。
  • references/arcade-physics.md
    ：Arcade物理系统深度解析（包含对象池模式）。
  • references/tilemaps.md
    ：Tiled瓦片地图工作流、碰撞设置、对象层。
  • references/performance.md
    ：优化策略（对象池、批处理、裁剪、相机、纹理图集）。
  • references/spritesheets-nineslice.md
    ：精灵表加载（间距/边距）、九宫格UI面板、资源检查规范。

Anti-Patterns to Avoid

需避免的反模式

❌ Global state soup: Storing game state on 
window
or module globals
Why bad: scene transitions become fragile; debugging becomes chaotic
Better: scene data, registries, or a dedicated state manager
❌ Loading in 
create()
: Loading assets in 
create()
instead of 
preload()

Why bad: assets may not be ready when referenced
Better: load in 
preload()
; use a Boot scene for all assets
❌ Frame-dependent logic: Using frame count instead of 
delta

Why bad: game speed varies with frame rate
Better: scale by 
(delta / 1000)
for consistent movement/timers
❌ Physics overkill: Using Matter for simple platformer collisions
Why bad: unnecessary complexity + perf cost
Better: Arcade covers most 2D collision needs
❌ Monolithic scenes: One giant scene with all game logic
Why bad: hard to extend; UI/menus/pause become hacks
Better: separate gameplay vs UI overlay vs menus
❌ Magic numbers everywhere: Hardcoded tuning values scattered in code
Why bad: balancing becomes painful; changes cause regressions
Better: config objects/constants and centralized tuning
❌ No pooling for spammy objects: Creating/destroying bullets/particles constantly Why bad: GC spikes → stutters Better: object pooling with groups + 
setActive(false)
/ 
setVisible(false)
❌ Assuming spritesheet frame dimensions: Using guessed frame sizes without verifying source asset Why bad: wrong dimensions cause silent frame corruption; off-by-pixels compounds into broken visuals Better: open asset file, measure frames, calculate with spacing/margin, verify math adds up
❌ Ignoring spritesheet spacing: Not specifying 
spacing
for gapped spritesheets Why bad: frames shift progressively; later frames read wrong pixel regions Better: check source asset for gaps between frames; use 
spacing: N
in loader config
❌ Hardcoding nine-slice colors: Using single background color for all UI panel variants Why bad: transparent frame edges reveal wrong color for different asset color schemes Better: per-asset background color config; sample from center frame (frame 4)
❌ Nine-slice with padded frames: Treating the full frame as the slice region when the art is centered/padded inside each tile Why bad: edge tiles contribute interior fill, showing up as opaque “side bars” inside the panel Better: trim tiles to their effective content bounds (alpha bbox) and composite/cache a texture; add ~1px overlap + disable smoothing to avoid seams
❌ Scaling discontinuous UI art: Scaling a cropped banner/ribbon row that contains internal transparent gaps Why bad: the transparent gutters scale too, making the UI look “broken” or segmented Better: slice into left/center/right (or similar), stretch only the center, and stitch into a cached texture at the target size
❌ 全局状态混乱：将游戏状态存储在
window
或模块全局变量中
弊端：场景切换变得脆弱；调试难度大幅提升
优化方案：使用场景数据、注册表或专用状态管理器
❌ 在
create()
中加载资源：在
create()
而非
preload()
中加载资源
弊端：资源可能在引用时未加载完成
优化方案：在
preload()
中加载；使用启动场景处理所有资源加载
❌ 依赖帧数的逻辑：使用帧数计数而非
delta

弊端：游戏速度会随帧率变化
优化方案：使用
(delta / 1000)
进行缩放，确保运动/计时器的一致性
❌ 物理系统过度使用：为简单平台跳跃游戏使用Matter物理
弊端：增加不必要的复杂度与性能开销
优化方案：Arcade物理足以满足大多数2D碰撞需求
❌ 单体式场景：将所有游戏逻辑放在一个庞大的场景中
弊端：难以扩展；UI/菜单/暂停功能会变成临时补丁
优化方案：将游戏玩法、UI浮层、菜单分离为不同场景
❌ 到处使用魔法数字：在代码中分散使用硬编码的调优数值
弊端：平衡调整变得繁琐；修改容易引发回归问题
优化方案：使用配置对象/常量，集中管理调优数值
❌ 未对高频对象做对象池：频繁创建/销毁子弹/粒子等对象
弊端：垃圾回收峰值导致游戏卡顿
优化方案：使用对象组实现对象池，通过
setActive(false)
/ 
setVisible(false)
复用对象
❌ 假设精灵表帧尺寸：未验证源资源就猜测帧尺寸
弊端：错误的尺寸会导致帧无声损坏；像素偏差会累积成视觉故障
优化方案：打开资源文件，测量帧尺寸，结合间距/边距计算，验证计算结果
❌ 忽略精灵表间距：对带间隙的精灵表未指定
spacing
参数
弊端：帧会逐渐偏移；后续帧会读取错误的像素区域
优化方案：检查源资源的帧间隙；在加载器配置中设置
spacing: N
❌ 硬编码九宫格颜色：为所有UI面板变体使用单一背景色
弊端：透明帧边缘会因不同资源配色方案显示错误颜色
优化方案：为每个资源配置单独的背景色；从中心帧（第4帧）采样颜色
❌ 带内边距帧的九宫格：当艺术内容在每个 tile 中居中/带内边距时，将整个帧视为切片区域
弊端：边缘tile会填充内部区域，在面板内显示不透明的“侧边栏”
优化方案：将tile裁剪至有效内容边界（alpha包围盒），合成并缓存纹理；添加约1px重叠并禁用平滑以避免接缝
❌ 缩放不连续的UI素材：缩放包含内部透明间隙的裁剪横幅/带状素材
弊端：透明间隙也会被缩放，导致UI看起来“破损”或分段
优化方案：将素材切割为左/中/右（或类似结构），仅拉伸中间部分，然后拼接成目标尺寸的缓存纹理

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 and scale mode
  • Always defaulting to Arcade (or always defaulting to Matter)
  • Copy-pasting boilerplate without adapting to the game’s needs
输出内容需根据以下因素调整：
  • 游戏类型（平台跳跃、俯视角、射击类会改变物理/输入/相机逻辑）
  • 目标平台（移动端触控、桌面端键盘、游戏手柄支持）
  • 美术风格（像素艺术缩放 vs 高清平滑；纹理图集的使用）
  • 性能阈值（大量精灵→对象池/裁剪；少量精灵→更简洁的代码）
  • 团队规模/复杂度（原型 vs 生产级架构）
避免陷入固化思维：
  • 不要固定使用某一种“默认”分辨率和缩放模式
  • 不要总是默认使用Arcade（或总是默认使用Matter）
  • 不要不加适配就复制粘贴模板代码，需根据游戏需求调整

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.
Codex is capable of building complete, polished Phaser games. These guidelines illuminate the path—they don't fence it.
Phaser提供了强大的基础组件——场景、精灵、物理、输入，但架构设计由你负责。
用系统思维思考：定义场景、定义实体、定义它们的交互——然后再实现。
Codex能够构建完整、精致的Phaser游戏。这些指南是为你指明方向，而非限制你的创意。