嗨 r/gamedev!

如果你曾经从 Godot、Phaser、Defold 或 Construct 导出 HTML5/WebGL 游戏,并且通过直接双击 index.html 本地测试,你几乎肯定会遇到 dreaded CORS / file:/// 安全限制:资产加载失败,纹理返回 404/被阻止错误,结果只能看到空白屏幕。

常规的解决办法是启动一个本地 Python 服务器 (python -m http.server) 或配置 Live Server 扩展。然而,在向非技术友的朋友或游戏马拉松测试者分享离线测试构建时,这会产生巨大的摩擦。

我过去几周花费时间构建了 RunaWeb,一个无后端、客户端离线游戏运行器和模拟器运行时,我想分享在让 Web 游戏真正便携且离线的过程中所学到的架构经验,而无需依赖外部 Web 服务器。

1. 通过 Service Workers 的内存虚拟服务器

与其需要 HTTP 服务器守护进程,我们使用客户端 Service Worker 结合浏览器的 CacheStorage API:

  • 用户将导出的 .zip 或单文件 .html/.wasm 文件拖入应用。
  • 客户端解压 (fflate) 将游戏在内存中解压。
  • 我们将未压缩的资源直接装载到专用的 CacheStorage (caches.open('virtual-game')) 中。
  • Service Worker 捕获所有子资源请求 (/virtual-game/*) 并返回已缓存的资产,使用推断的正确 MIME 类型。
  • 结果: 游戏在一个 <iframe> 中运行,误以为它正在从真实 HTTP 源上提供服务,完全绕过本地 file:/// 限制和 CORS 错误。

2. “假事件”音频陷阱 (isTrusted: false)

当我们在添加屏幕触控控制时,遇到了重大障碍:

  • 虚拟按钮向游戏帧中发送了合成的 new KeyboardEvent(...) 事件。
  • 然而,现代浏览器严格要求 AudioContext.resume() 需要一个 受信任的用户操作 (event.isTrusted === true)。
  • 由于合成事件的 isTrusted: false,子 iframe 的 Web Audio APU 完全被静音并处于暂停状态!
  • 解决方案: 我们建立了宿主级的 Master AudioContext,在物理触摸时解锁,并为沙箱化的 iframe 添加显式 allow="autoplay" 权限。子运行时(如我们的 WASM-4 复古合成器)挂钩到已解锁的宿主上下文,以无缝播放音频。

3. 复古与幻想主机支持 (WASM-4)

除了标准的 HTML5/WebGL 包,我们实现了用于 WASM-4 卡arts (.wasm) 的轻量微运行时。由于 WASM-4 使用固定的 64KB 内存映射:

  • 帧缓冲区位于 $00a0。
  • 游戏手柄状态映射到 $0016。
  • 我们使用原生 Web Audio 振荡器合成 4 通道的音频合成器(脉冲 1 & 2 带有自定义占空比、三角波,以及 15 位/7 位 LFSR 噪声),实时将 MIDI 音符号转换为频率。

开源开发者工具

整个项目完全免费并遵循 GPL-3.0 许可证:

它提供完整的触控控制(支持现场 PPSSPP 样式布局自定义),支持物理手柄(Gamepad API),本地 IndexedDB 保存持久化,以及在 CI 中自动 Playwright E2E 测试。

我希望这份技术分解能帮助所有在浏览器引擎或游戏马拉松部署流程上工作的开发者!欢迎在评论中提出关于 Service Worker 资产拦截、WASM 内存映射或移动触控模拟的任何问题。