phaser-core

Phaser 4 核心

搭建 Phaser 游戏的基础：Game 配置、Scene 生命周期、资源加载、摄像机，以及场景间的数据传递。新项目以 Phaser 4.2 为目标；现有 Phaser 3.90 项目应保持原有主版本，除非用户明确要求迁移。

适用场景

• 用于启动 Phaser 游戏、配置 Phaser.Game、组织 Scene、在 preload 中加载资源，或修复场景切换和共享状态。
• 用于项目的 package.json 中包含 phaser 或代码中包含 import Phaser from 'phaser'，且代码使用 preload()/create()/update()。

不适用场景： 移动、速度、碰撞器、重力或重叠检测 → 使用 phaser-arcade-physics。复杂的刚体模拟使用 Matter 物理（属于另一个范畴）。跨引擎的存档/加载模式请使用 save-systems。

核心工作流

1. 先检测已安装的主版本。 阅读 package.json 和锁文件。新项目使用 Phaser 4.2；不要在未告知的情况下将 Phaser 3 项目改写为 Phaser 4。
2. 根据配置创建游戏。 使用 new Phaser.Game(config)，其中包含 type: Phaser.AUTO（WebGL，Canvas 作为回退）、width/height 和 scene 数组。第一个场景（以及任何设置了 active: true 的场景）会自动启动。
3. 将每个屏幕建模为一个 Scene。 继承 Phaser.Scene，向 super 传入唯一的 key，并实现生命周期：init(data) → preload() → create(data) → update(time, delta)。
4. 在 preload 中加载资源，在 create 中使用。 排队加载的资源要等到 create 才可用。加载器是每个场景独有的；它填充的缓存则是全局的。
5. 在 init() 中重置每次运行的状态，而不是在构造函数中。 场景实例会在重启时复用，因此在构造函数中设置的字段会保留过期值。
6. 使用 this.scene.start/launch/switch/sleep/wake 切换屏幕。 通过 this.registry（全局）或兄弟场景的事件发射器共享数据。
7. 运行并观察。 启动页面并打开它，确认资源已加载（查看 Network 面板和控制台），且场景按预期切换，然后再判断是否成功。

模式

1. 游戏配置 + 启动（ES 模块）

// main.js — one Game owns the renderer, loop, cache, and Scene Manager.
import Phaser from 'phaser';
import BootScene from './scenes/BootScene.js';
import PlayScene from './scenes/PlayScene.js';

const config = {
  type: Phaser.AUTO,            // WebGL if available, else Canvas
  width: 800,
  height: 600,
  backgroundColor: '#1d1d28',
  scale: { mode: Phaser.Scale.FIT, autoCenter: Phaser.Scale.CENTER_BOTH },
  scene: [BootScene, PlayScene] // BootScene starts first
};

new Phaser.Game(config);

2. 完整生命周期的 Scene

// scenes/PlayScene.js
import Phaser from 'phaser';

export default class PlayScene extends Phaser.Scene {
  constructor() {
    super('play');                  // unique scene key
  }

  init(data) {
    // Reset run-specific state HERE so restarts start clean.
    this.score = 0;
    this.level = data.level ?? 1;
  }

  preload() {
    // Queue downloads. Not usable until create().
    this.load.image('player', 'assets/player.png');
    this.load.spritesheet('coin', 'assets/coin.png', { frameWidth: 16, frameHeight: 16 });
  }

  create() {
    this.player = this.add.sprite(400, 300, 'player');
    this.scoreText = this.add.text(10, 10, 'Score: 0', { fontSize: '20px', color: '#fff' });
    this.cursors = this.input.keyboard.createCursorKeys();
  }

  update(time, delta) {
    // delta is milliseconds since last frame; divide by 1000 for seconds.
    const speed = 200 * (delta / 1000);
    if (this.cursors.left.isDown)  this.player.x -= speed;
    if (this.cursors.right.isDown) this.player.x += speed;
  }
}

3. 跨场景数据 + 事件

// The registry is a global DataManager shared by every scene.
this.registry.set('coins', 0);                 // in any scene
const coins = this.registry.get('coins');      // read anywhere

// React to registry changes (e.g. a HUD scene listening to gameplay):
this.registry.events.on('changedata-coins', (parent, value) => {
  this.coinText.setText(`Coins: ${value}`);
});

// Talk directly to another running scene via its event emitter:
const ui = this.scene.get('hud');
ui.events.emit('show-message', 'Level cleared!');

4. 场景切换（选择正确的方法）

this.scene.start('gameover', { score: this.score }); // stop this scene, start target
this.scene.launch('hud');        // run a second scene in parallel (overlay HUD)
this.scene.switch('menu');       // sleep this scene, start/wake target
this.scene.pause();              // freeze updates but keep rendering (modal)
this.scene.sleep();              // stop updating AND rendering, keep state for wake

5. 跟随玩家的摄像机

this.cameras.main.setBounds(0, 0, 1600, 1200);  // world size
this.cameras.main.startFollow(this.player, true, 0.1, 0.1); // smooth lerp follow
this.cameras.main.setZoom(1.5);

常见问题

• 资源在 create/update 中是 undefined → 忘记在 preload 中将它们加入加载队列，或使用了错误的键。加载器在 preload 和 create 之间运行。
• 重启后状态残留 → 你在构造函数中设置了字段。Scene 实例会被复用；请在 init() 中重置每次运行的状态，并在 shutdown 时清空数组。
• this.scene.start 与 this.scene.launch 的区别 → start 会停止调用它的场景； launch 会让目标场景与当前场景同时运行。对 HUD 使用 start 会隐藏游戏。
• 回调中的 this 不正确 → 箭头函数会保留 Scene 的 this；普通的 function 回调需要传入上下文参数或使用 .bind(this)。
• Phaser 2 教程无法使用 → 在 Phaser 3 中，“States” 被重命名为 “Scenes”， 并且每个 Scene 都拥有自己的系统（输入、摄像机、补间动画），而不是使用全局 Game World。
• Phaser 3 自定义管线在 Phaser 4 中失效 → Phaser 4 重建了渲染器，并 替换了旧的 FX/管线扩展点。请根据 Phaser 4 指南迁移自定义着色器和渲染器插件；不要机械照搬渲染器内部代码。
• 没有渲染内容 / 黑屏 → 确认 canvas 已挂载、已设置 width/height， 且确实有场景启动（检查 game.scene.dump() 输出）。

参考资料

• 如需了解完整的场景状态机（暂停/恢复与休眠/唤醒及停止/启动的区别、重启状态错误，以及移除/替换场景），请阅读 references/scene-flow.md。

相关技能

• phaser-arcade-physics — 速度、重力、碰撞器、重叠检测和组。
• input-systems — 可重新绑定、多设备的输入架构（与引擎无关）。
• pixijs-rendering / threejs-scene-setup — 其他浏览器渲染技术栈。
• platformer / puzzle — 组合 Phaser 技能的游戏类型模板。