用途:把 Bevy 0.19 客户端编译到 wasm32-unknown-unknown 并在浏览器运行,涵盖 WebGL2 与 WebGPU 两条渲染路径的选择、JS 绑定生成、资源托管与体积优化,以及常见故障排查。
主要能力:给出 Cargo 清单示例,使用 bevy 0.19 并设置 default-features = false,按需启用 3d、ui、touch 等特性;提供 wasm-release profile(opt-level = "z"、lto = "fat"、codegen-units = 1、strip = "debuginfo")。说明 3d 特性提供渲染器、Winit 与默认 WebGL2 路径;音频需用户交互后才能播放。
使用方式:先执行 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 生成绑定;可选安装 Binaryen 后用 wasm-opt -Oz 压缩并验证是否真正减小体积;用 python3 -m http.server --directory public 8080 本地服务,并把项目 assets/ 复制或链接到 public/assets/。HTML 中提供 canvas#bevy 并以模块方式 import init 后 await init();Rust 侧需在 WindowPlugin 的 primary_window 中设置 canvas: Some("#bevy".into()) 与 fit_canvas_to_parent: true,否则 Bevy 会另建画布。必须通过 HTTP 访问,直接打开文件不满足 fetch 与模块语义。
WebGL2 与 WebGPU:WebGL2 兼容面广、无计算着色器依赖;WebGPU 需在 Cargo 特性中加 webgpu,适用于目标浏览器已支持且效果需要计算着色器的场景。Bevy 0.19 中 webgpu 覆盖 webgl2,单个二进制无法动态回退,需按浏览器支持矩阵产出两个产物或择一。
限制与注意:3d_api 只提供类型不负责渲染;Cargo 特性是叠加的,启用 3d 时须关闭默认特性;WebGL2 无计算着色器,Hanabi 等计算密集型插件需 WebGPU 产物及其兼容版本;浏览器无原生文件系统与子进程,捕获、保存、导出需显式 Web API/JS 互操作;资源 404 属部署布局问题,需在开发者工具中核对请求 URL;canvas 选择器须在启动前可解析且之后不可更改;cargo check 无法验证适配器限制、着色器翻译、纹理格式与浏览器安全策略,需在真实目标浏览器与 GPU 上测试。相关技能包括 bevy-cargo-features、bevy-rendering、bevy-assets、bevy-vfx。