bevy-wasm-webgpu

Bevy 0.19 — 浏览器 WASM

何时使用此技能

• 为 wasm32-unknown-unknown 构建 Bevy 客户端。
• 选择兼容性广的 WebGL2 路径或 WebGPU 路径。
• 生成 JS 绑定、提供资源并缩减构建产物大小。
• 排查画布缺失、不安全上下文、编解码器或资源路径故障。

规范清单

[package]
name = "myclient"
version = "0.1.0"
edition = "2024"

[dependencies]
bevy = { version = "0.19", default-features = false, features = [
    "3d",
    "ui",
    "touch",
] }

[profile.wasm-release]
inherits = "release"
opt-level = "z"
lto = "fat"
codegen-units = 1
strip = "debuginfo"

3d 配置集提供 Bevy 的渲染器、Winit 和默认的 WebGL2 路径。 仅在需要时添加 audio；浏览器音频必须在用户交互后才能启动。

构建并提供服务

rustup target add wasm32-unknown-unknown
cargo install wasm-bindgen-cli

cargo build --profile wasm-release --target wasm32-unknown-unknown
wasm-bindgen --target web --out-name myclient --out-dir public \
  target/wasm32-unknown-unknown/wasm-release/myclient.wasm

# Optional: install Binaryen first, then verify this actually reduces size.
wasm-opt -Oz public/myclient_bg.wasm -o public/myclient_bg.opt.wasm
mv public/myclient_bg.opt.wasm public/myclient_bg.wasm

python3 -m http.server --directory public 8080

将项目的 assets/ 目录复制或链接到 public/assets/；Bevy 会根据所提供页面／资源根目录，通过 HTTP 获取资源。

最简 HTML

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width,initial-scale=1">
    <title>My Bevy game</title>
    <style>html,body,#bevy{width:100%;height:100%;margin:0;background:#000}</style>
  </head>
  <body>
    <canvas id="bevy"></canvas>
    <script type="module">
      import init from "./myclient.js";
      await init();
    </script>
  </body>
</html>

将主窗口绑定到现有画布。否则，Window::default() 的 canvas: None 会导致 Bevy/Winit 创建并附加第二个画布：

use bevy::{prelude::*, window::WindowPlugin};

fn main() {
    App::new()
        .add_plugins(DefaultPlugins.set(WindowPlugin {
            primary_window: Some(Window {
                canvas: Some("#bevy".into()),
                fit_canvas_to_parent: true,
                ..default()
            }),
            ..default()
        }))
        .run();
}

通过 HTTP 提供服务；直接打开文件无法提供生成的 glue 所需的 fetch 和模块语义。

WebGL2 与 WebGPU

选择	Cargo 功能	适用情况
WebGL2	配置集默认功能／webgl2	需要兼顾浏览器覆盖面，且不依赖计算功能
WebGPU	添加 webgpu	经过测试的目标浏览器支持它，且效果需要计算功能

在 Bevy 0.19 中，webgpu 会覆盖 webgl2。单个二进制无法在两者之间动态回退。应生成两种构建产物，或根据支持的浏览器矩阵选择一种。发布测试时检查当前浏览器支持情况，不要在应用逻辑中硬编码浏览器版本相关说法。

注意事项

• 3d_api 只提供类型，不会进行渲染。请使用 3d，或将 3d_bevy_render 与应用／平台功能集组合使用。
• default-features = false 很重要。Cargo 功能是累加的；如果不禁用默认功能就添加 3d，完整的默认功能集仍会保留。
• WebGL2 不支持计算着色器。Hanabi 和其他计算密集型插件需要 WebGPU 构建产物，以及其自身当前兼容 Bevy 的版本。
• 浏览器文件系统和子进程并非原生功能。捕获、保存和导出流程需要明确使用 Web API／JS 互操作。
• 通常需要用户手势来恢复浏览器音频上下文，之后才能播放音频。
• 资源 404 属于部署布局错误：在浏览器开发者工具中检查请求的 URL，并确保所提供的 assets/ 目录树与之匹配。
• 配置的 Window.canvas 选择器必须在启动前匹配到元素，之后无法更改。如果省略该配置，请移除任何占位画布，让 Bevy 附加自己的画布。
• 在实际目标浏览器和 GPU 上进行测试。cargo check 无法验证适配器限制、着色器转换、纹理格式或浏览器安全策略。

另请参阅

• bevy-cargo-features — 配置集组合。
• bevy-rendering — 渲染器扩展选择。
• bevy-assets — 异步资源加载。
• bevy-vfx — 依赖计算功能的效果。