游戏引擎 / 系统课时

给互动对象绑定 Pointer 事件

给互动对象绑定 Pointer 事件

用 Phaser 4.2.1 做一个鼠标和触屏通用的「开始游戏」按钮:显式设置可点击范围,响应移入、按下和抬起,并在拖出或离开画布时取消触发。完成后可以直接用浏览器和手机检验按钮是否误触或卡在按下状态。

学习目标

  • 给游戏对象设置 260×84 像素的交互命中区域。
  • 绑定 pointerover、pointerdown、pointerup、pointerout 处理反馈。
  • 验证触屏点击、拖出取消和画布外释放的行为。

命中区域与事件范围

Phaser 将鼠标和触摸统一封装为 Pointer。只有对游戏对象调用 setInteractive(),对象自身的 on('pointerdown', ...) 等监听器才会接收指针事件。单击画布任意位置的监听器则写在 this.input 上,两者的触发范围不同。

本例使用一个中心位于 (400, 270)、宽 260、高 84 的 Rectangle 作为按钮底板,并显式传入 new Phaser.Geom.Rectangle(0, 0, 260, 84) 和 Phaser.Geom.Rectangle.Contains。这里的 (0, 0) 是对象局部命中区域的左上角,不是世界坐标;旁边叠放的文字只负责显示,不需要开启交互。

按下、释放和取消

按钮至少有常态、悬停态、按下态。鼠标进入时变亮,按下时变深;只有同一个 Pointer 先在按钮内按下、再在按钮内抬起,才执行一次按钮动作。触屏通常没有预先悬停阶段,应从常态直接进入按下态。

按钮的指针事件与取消路径状态图

pointerup 只说明指针在对象上释放,并不保证它之前在这个对象上按下。因此用 pressedBy 记住按下者;用对象级 pointerout、场景级 pointerup、pointerupoutside 和 gameout 清除未完成的按压。离开整个画布时不能只依赖对象的 pointerout。

创建可运行按钮

在已安装 Node.js 和 npm 的环境中创建 Vite 原生 JavaScript 工程,安装固定版本 Phaser:

bash
npm create vite@latest pointer-demo -- --template vanilla
cd pointer-demo
npm install
npm install phaser@4.2.1
npm run dev

预期结果:终端显示 Vite 开发地址,例如 http://localhost:<PORT>/,具体端口以实际输出为准;首次访问仍是 Vite 初始页面。保持开发服务器运行。

将默认 src/main.js 完整替换为以下代码;Vite 模板的 index.html 已提供 #app 容器,无需下载图片素材。

js
import Phaser from 'phaser';

document.querySelector('#app').innerHTML = '<div id="game"></div>';

class MenuScene extends Phaser.Scene {
  constructor() {
    super('Menu');
  }

  create() {
    const normal = 0x176e75;
    const hover = 0x229a9d;
    const pressed = 0x0b5056;
    const button = this.add.rectangle(400, 270, 260, 84, normal)
      .setStrokeStyle(2, 0x0f3942);

    this.add.text(400, 270, '开始游戏', {
      fontFamily: 'sans-serif',
      fontSize: '30px',
      color: '#ffffff'
    }).setOrigin(0.5);

    const feedback = this.add.text(400, 395, '等待点击', {
      fontFamily: 'sans-serif',
      fontSize: '22px',
      color: '#263746'
    }).setOrigin(0.5);

    // 命中区域使用对象局部坐标,不是画布坐标。
    button.setInteractive(
      new Phaser.Geom.Rectangle(0, 0, 260, 84),
      Phaser.Geom.Rectangle.Contains
    );
    button.input.cursor = 'pointer';

    let pressedBy = null;
    let count = 0;
    const cancelPress = () => {
      if (pressedBy === null) return;
      pressedBy = null;
      button.setFillStyle(normal);
      feedback.setText('已取消');
    };

    button.on('pointerover', () => {
      if (pressedBy === null) button.setFillStyle(hover);
    });
    button.on('pointerout', (pointer) => {
      if (pointer === pressedBy) cancelPress();
      else if (pressedBy === null) button.setFillStyle(normal);
    });
    button.on('pointerdown', (pointer) => {
      if (pointer.button !== 0 || pressedBy !== null) return;
      pressedBy = pointer;
      button.setFillStyle(pressed);
      feedback.setText('正在按下');
    });
    button.on('pointerup', (pointer) => {
      if (pointer !== pressedBy) return;
      if (pointer.wasCanceled || pointer.button !== 0) {
        cancelPress();
        return;
      }

      // 只在同一个指针于命中区内完成释放时触发。
      pressedBy = null;
      count += 1;
      button.setFillStyle(pointer.wasTouch ? normal : hover);
      feedback.setText(`已触发 ${count} 次`);
    });

    // 对象外释放和离开画布都要撤销待完成的点击。
    this.input.on('pointerup', (pointer) => {
      if (pointer === pressedBy) cancelPress();
    });
    this.input.on('pointerupoutside', (pointer) => {
      if (pointer === pressedBy) cancelPress();
    });
    this.input.on('gameout', () => {
      cancelPress();
      button.setFillStyle(normal);
    });
  }
}

new Phaser.Game({
  type: Phaser.AUTO,
  parent: 'game',
  width: 800,
  height: 600,
  backgroundColor: '#f5f8fa',
  scene: MenuScene
});

预期结果:保存后页面热更新,显示青绿色「开始游戏」按钮和「等待点击」文字。鼠标移入按钮变亮,按下变深,在按钮内部抬起后文字变为「已触发 1 次」;继续点击时计数逐次加一。手机触摸按下也会变深,松开后恢复常态。

验收与常见误触

按下列顺序测试,不需要打开浏览器控制台:

操作 应看到的结果
鼠标在按钮内按下并抬起 计数只增加 1
在按钮内按下,拖到按钮外再松开 出现「已取消」,计数不变
按住后将鼠标拖出画布 按钮恢复常态,计数不变
仅在按钮外按下,移入按钮后抬起 不执行按钮动作
手机手指在按钮内按下并抬起 正常增加 1 次,无需悬停

若点击完全无效,先检查对象是否调用 setInteractive(),再检查命中区域尺寸和是否有上层互动对象遮挡。若按钮按下后不能复位,检查场景级释放监听器是否注册。本例的事件与参数可对照 Phaser 输入系统文档 核实。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

给互动对象绑定 Pointer 事件

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通