游戏引擎 / 系统课时

配置画布尺寸与 WebGL 渲染

配置画布尺寸与 WebGL 渲染

为游戏首屏建立一块 960×540 的画布,指定使用 WebGL 渲染,并将画布挂载到页面中的固定容器。完成后,浏览器会显示一个可随容器宽度缩放的游戏画面,还能通过开发者工具确认画布尺寸、DOM 归属和实际渲染类型。

学习目标

  • 使用 type、parent 和 scale 配置 Phaser 4 游戏画布。
  • 区分游戏内部逻辑尺寸与浏览器中的 CSS 显示尺寸。
  • 在浏览器中验证 WebGL 渲染器、Canvas 元素和响应式缩放行为。

理解尺寸、渲染器与 DOM 容器

Phaser 使用传给 new Phaser.Game(config) 的配置对象决定画布如何创建。其中有三组必须明确的设置:

配置项 示例值 实际作用
type Phaser.WEBGL 指定 WebGL 渲染器
parent 'game-root' 将 Canvas 插入指定 DOM 容器
scale.width 960 游戏基础宽度为 960 游戏像素
scale.height 540 游戏基础高度为 540 游戏像素
scale.mode Phaser.Scale.FIT 在容器内保持比例缩放
scale.autoCenter Phaser.Scale.CENTER_BOTH 在父容器内水平和垂直居中

这里采用 16:9 的基础画面。游戏内部坐标仍然以 960×540 为基准,例如画面中心为 (480, 270)。当父容器宽度缩小到 480 CSS 像素时,FIT 模式会使显示区域缩小到约 480×270 CSS 像素,但游戏对象的逻辑坐标不会因此变成原来的一半。

parent 指向的是普通 HTML 容器,不需要预先创建 Canvas。Phaser 会自动创建 Canvas,并交给选定的渲染器使用。不要将这个设置与 dom.createContainer 混淆,后者用于支持 Phaser 的 DOM 游戏对象。

Phaser 4 画布配置、WebGL 渲染器与 DOM 容器关系

创建可运行的 WebGL 画布

下面使用 Phaser 4.2.1 的浏览器构建制作一个独立示例,不依赖游戏图片资源。将代码保存为 index.html,使用 Chrome 或 Edge 打开即可运行;页面需要联网加载 Phaser CDN 脚本。

html
<!doctype html>
<html lang='zh-CN'>
<head>
  <meta charset='utf-8'>
  <meta name='viewport' content='width=device-width, initial-scale=1'>
  <title>Phaser 4 画布检查</title>
  <style>
    body {
      margin: 0;
      background: #e8edf3;
    }
    #game-root {
      width: min(100%, 960px);
      aspect-ratio: 16 / 9;
      margin: 24px auto;
    }
  </style>
</head>
<body>
  <!-- Phaser 将自动创建 Canvas 并插入这个容器 -->
  <div id='game-root'></div>
  <script src='https://cdn.jsdelivr.net/npm/phaser@4.2.1/dist/phaser.min.js'></script>
  <script>
    const config = {
      type: Phaser.WEBGL,
      parent: 'game-root',
      backgroundColor: '#14223a',
      scale: {
        width: 960,
        height: 540,
        mode: Phaser.Scale.FIT,
        autoCenter: Phaser.Scale.CENTER_BOTH
      },
      scene: {
        create() {
          this.add.text(480, 270, 'Phaser 4 · WebGL', {
            fontFamily: 'Arial',
            fontSize: '38px',
            color: '#ffffff'
          }).setOrigin(0.5);

          // 场景启动后,检查实际创建的 Canvas 和渲染器。
          const canvas = this.game.canvas;
          console.log('容器匹配:', canvas.parentElement.id === 'game-root');
          console.log('画布像素:', `${canvas.width}x${canvas.height}`);
          console.log('渲染方式:',
            this.game.renderer.type === Phaser.WEBGL ? 'WebGL' : '非 WebGL');
        }
      }
    };

    new Phaser.Game(config);
  </script>
</body>
</html>

预期结果:页面出现一块深蓝色的 16:9 游戏画面,中央显示白色文字 Phaser 4 · WebGL。在浏览器开发者工具的 Console 中可以找到以下三行日志,Phaser 自身可能另外输出启动信息。

text
容器匹配: true
画布像素: 960x540
渲染方式: WebGL

示例特意使用 Phaser.WEBGL,目的是明确要求浏览器建立 WebGL 渲染环境。如果项目需要兼容不支持 WebGL 的设备,可以考虑 Phaser.AUTO,它会优先使用 WebGL,并在可用构建支持的情况下回退到 Canvas 渲染。不过 Phaser 4 的新渲染能力主要面向 WebGL,Canvas 回退不意味着所有视觉功能完全等价。

检查画布尺寸与缩放

Canvas 是否创建成功,不能只通过页面上有没有颜色判断,还需要查看浏览器实际生成的元素与渲染器。

  1. 按 F12 打开开发者工具,切换到 Elements 面板。
  2. 找到 div#game-root,展开后应当看到一个 canvas 子元素。
  3. 检查 Canvas 的 width 和 height 属性,当前示例应为 960 与 540。
  4. 切换到 Console 面板,确认 容器匹配: true 和 渲染方式: WebGL。
  5. 将浏览器视口宽度调整到约 480 CSS 像素。画面应等比例缩小,文字仍处于画面中央,没有被横向拉伸或裁切。

这里需要区别两种尺寸:Canvas 元素的 width、height 表示绘图缓冲区尺寸;在 FIT 模式下,浏览器计算的 CSS 宽高用于控制屏幕上显示多大。缩小容器后,Elements 面板中 Canvas 的原始宽高属性通常仍是 960×540,而其显示尺寸会随父容器改变。

本例的父容器设置了 aspect-ratio: 16 / 9,使容器本身也保持目标比例。实际项目如果采用其他页面布局,可以调整容器尺寸,但不要为了适配手机而同时随意修改 Canvas 的 HTML 宽高属性和 Phaser 的 scale 配置,否则容易出现坐标错位或画面变形。

排查空白画布与挂载异常

如果首屏没有出现预期内容,可以按以下顺序检查,每次只修正一个问题再刷新页面。

现象 优先检查 修正方法
页面没有 Canvas Console 中是否出现脚本加载错误 确认 Phaser CDN 请求成功,且脚本在游戏初始化前加载
Canvas 不在指定容器内 parent 与 HTML 元素 ID 是否一致 确保页面存在 id='game-root',并先于游戏初始化创建
强制 WebGL 后启动失败 浏览器是否支持或允许 WebGL 检查浏览器 GPU 支持及 Console 错误,必要时临时改用 Phaser.AUTO 定位问题
窗口变窄后画面不缩放 scale.mode 与父容器实际尺寸 使用 Phaser.Scale.FIT,确认父容器有可计算的宽高

还要注意:backgroundColor 只能说明游戏背景颜色已被设置,不能独立证明 WebGL 正在工作。验收时应同时满足三个条件:Canvas 位于正确的 DOM 容器中、画布基础尺寸与配置一致、实际渲染器类型为 WebGL。

这些设置属于 Phaser 游戏初始化配置。如果后续需要动态调整视口,应使用 Scale Manager 提供的能力,而不是直接修改已经解析的 game.config。配置字段与缩放规则可以对照 Phaser 游戏配置文档 和 Scale Manager 文档。

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

目录与阅读设置

阅读设置

17

记录一个想法

配置画布尺寸与 WebGL 渲染

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

登录哪都通