phaser-arcade-physics

Phaser 4 Arcade Physics

使用轻量级 Arcade Physics 引擎（仅支持 AABB 矩形和圆形），为 Phaser 游戏添加移动和碰撞。新项目以 Phaser 4.2 为目标；编辑现有项目之前，先检查已安装的主版本。

适用场景

• 用于俯视角或平台游戏的移动、速度／加速度／重力、弹跳、世界边界，以及精灵、组和图块之间的碰撞／重叠处理。
• 场景启用了 physics: { default: 'arcade' }，且代码调用 this.physics.add.*、body.setVelocity 或 this.physics.add.collider 时使用。

不适用场景：Game 配置、场景结构、资源加载或摄像机 → 使用 phaser-core。铰链、弹簧、复杂多边形或堆叠刚体 → 使用 Matter physics（这是另一种引擎；Arcade 和 Matter 的物体不会相互作用）。如需与引擎无关的手感调优，请参阅 physics-tuning。

核心工作流

1. 启用物理世界。 在游戏或场景配置中设置 physics: { default: 'arcade', arcade: { gravity: {...}, debug: true } }。开发期间开启 debug，以查看物体轮廓和速度向量。
2. 为精灵添加物体。 使用 this.physics.add.sprite(...)（动态）或 this.physics.add.staticImage(...)（静态）创建精灵，或使用 this.physics.add.existing(obj) 为现有对象添加物体。
3. 通过物体驱动精灵，而不是设置 x／y。 使用 setVelocity、setAcceleration、重力、setBounce 和 setCollideWorldBounds。引擎会在每个步骤根据速度计算位置（已与帧率无关）。
4. 处理交互。 this.physics.add.collider(a, b) 会分离物体；this.physics.add.overlap(a, b, cb) 只检测而不分离（用于拾取物、触发器）。传入回调以作出响应。
5. 将多个对象分组。 使用 this.physics.add.group()（动态）或 staticGroup()（平台），这样一次碰撞器调用就能处理所有成员。
6. 跳跃前检查是否接触地面，使用 body.onFloor()／body.blocked.down。以 debug: true 运行，并确认物体、接触状态和边界。

常见模式

1. 启用 Arcade Physics（游戏配置）

const config = {
  type: Phaser.AUTO,
  width: 800, height: 600,
  physics: {
    default: 'arcade',
    arcade: {
      gravity: { x: 0, y: 600 },  // top-down? use { x: 0, y: 0 }
      debug: false                // true to draw bodies + velocity while building
    }
  },
  scene: [PlayScene]
};
new Phaser.Game(config);

2. 俯视角移动（根据输入设置速度）

create() {
  this.player = this.physics.add.sprite(400, 300, 'player');
  this.player.setCollideWorldBounds(true);
  this.cursors = this.input.keyboard.createCursorKeys();
}

update() {
  const speed = 220;
  const body = this.player.body;
  body.setVelocity(0);                              // reset each frame
  if (this.cursors.left.isDown)  body.setVelocityX(-speed);
  if (this.cursors.right.isDown) body.setVelocityX(speed);
  if (this.cursors.up.isDown)    body.setVelocityY(-speed);
  if (this.cursors.down.isDown)  body.setVelocityY(speed);
  body.velocity.normalize().scale(speed);           // keep diagonals same speed
}

3. 平台游戏跳跃（重力 + 地面检测）

create() {
  this.player = this.physics.add.sprite(100, 450, 'player');
  this.player.setCollideWorldBounds(true);

  // Static platforms: one body each, never moved by collisions.
  this.platforms = this.physics.add.staticGroup();
  this.platforms.create(400, 568, 'ground');
  this.physics.add.collider(this.player, this.platforms);

  this.cursors = this.input.keyboard.createCursorKeys();
}

update() {
  const onGround = this.player.body.blocked.down; // or this.player.body.onFloor()
  if (this.cursors.left.isDown)  this.player.setVelocityX(-160);
  else if (this.cursors.right.isDown) this.player.setVelocityX(160);
  else this.player.setVelocityX(0);

  if (this.cursors.up.isDown && onGround) this.player.setVelocityY(-450);
}

4. 碰撞器与重叠检测（分离与检测）

// Push apart and react: player vs enemies.
this.physics.add.collider(this.player, this.enemies, (player, enemy) => {
  this.handleHit(player, enemy);
});

// Detect without pushing: collect coins. The 4th arg is an optional
// process callback returning a boolean to filter pairs before the main callback.
this.physics.add.overlap(this.player, this.coins, (player, coin) => {
  coin.disableBody(true, true);              // deactivate + hide
  this.registry.inc('score', 10);
});

5. 一组移动对象

this.bullets = this.physics.add.group({
  defaultKey: 'bullet',
  maxSize: 30                  // pool size; reuse instead of allocating
});

fire(x, y) {
  const bullet = this.bullets.get(x, y);     // reuses a dead bullet if available
  if (!bullet) return;
  bullet.enableBody(true, x, y, true, true);
  bullet.setVelocityY(-500);
}

常见问题

• 精灵不受物理影响 → 它是通过 this.add.sprite 而不是 this.physics.add.sprite 添加的（或未调用 this.physics.add.existing(obj)），因此没有物体。
• 直接设置 sprite.x 会与引擎冲突 → 使用 setVelocity／setAcceleration 移动动态物体。直接写入位置可能导致物体穿过碰撞体。
• 斜向移动更快 → X 和 Y 方向的独立速度会叠加；应将速度向量归一化，再缩放到预期速度。
• 平台被玩家推着走 → 使用 staticGroup，或对动态平台调用 body.setImmovable(true)。
• onFloor() 始终为 false → 物体需要有可碰撞的对象；检查之前，先添加与地面／平台之间的 collider，并确保重力已启用。
• 移动静态物体后碰撞状态过期 → 静态物体不会自动同步；调用 body.updateFromGameObject()（或对游戏对象调用 refreshBody()）。
• 每帧都添加碰撞器 → 在 create 中注册一次 collider／overlap，不要在 update 中注册。

参考资料

• 有关物体结构和调优（阻力、弹跳、最大速度、自定义 setSize／setCircle／setOffset 碰撞箱、碰撞类别／掩码，以及 worldbounds 事件），请阅读 references/bodies-and-collision.md。

相关技能

• phaser-core — 游戏配置、场景、加载器、摄像机（必需的前置设置）。
• physics-tuning — 与引擎无关的手感调优（固定时间步长、穿透、抖动）。
• platformer／tower-defense — 使用此技能的游戏类型。
• level-design — 布置这些物体会与之碰撞的图块／平台几何结构。