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 が2つ目のキャンバスを作成して追加します。

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 経由で配信してください。ファイルを直接開いても、生成されたグルーコードが想定する取得処理やモジュールのセマンティクスは提供されません。

WebGL2 と WebGPU の比較

選択肢	Cargo の機能	選択する条件
WebGL2	プロファイルのデフォルト／webgl2	ブラウザーの対応範囲を重視し、コンピュートへの依存がない場合
WebGPU	webgpu を追加	テスト済みの対象ブラウザーが対応し、エフェクトでコンピュートが必要な場合

Bevy 0.19 では、webgpu が webgl2 を上書きします。1つのバイナリで両者を動的に切り替えることはできません。2つの成果物を作成するか、サポート対象ブラウザーの一覧に基づいてどちらかを選択してください。アプリケーションロジックにブラウザーのバージョンを固定して記述するのではなく、リリーステスト時に現在のブラウザー対応状況を確認してください。

注意点

• 3d_api は型を提供するだけで、レンダリングは行いません。3d を使うか、3d_bevy_render とアプリ／プラットフォームのコレクションを組み合わせてください。
• default-features = false は重要です。Cargo の機能は累積的に有効になります。デフォルト機能を無効にせずに 3d を追加すると、デフォルトの機能セット全体が有効なままになります。
• WebGL2 はコンピュートシェーダーに対応していません。Hanabi など、コンピュートを多用するプラグインには、WebGPU の成果物と、それぞれの現行 Bevy 対応リリースが必要です。
• ブラウザーのファイルシステムや子プロセスは、ネイティブ環境のようには利用できません。キャプチャ、保存、エクスポートのフローには、明示的な Web API／JS 相互運用が必要です。
• 通常、ユーザー操作によってブラウザーのオーディオコンテキストが再開されるまで、オーディオ再生はブロックされます。
• アセットの 404 はデプロイ時の配置エラーです。ブラウザーの開発者ツールでリクエストされた URL を確認し、配信する assets/ ツリーがその URL に一致するようにしてください。
• 設定した Window.canvas セレクターは起動前に解決される必要があり、後から変更できません。指定しない場合は、プレースホルダーのキャンバスを削除して、Bevy 自身が追加するようにしてください。
• 実際の対象ブラウザーと GPU でテストしてください。cargo check では、アダプターの制限、シェーダーの変換、テクスチャ形式、ブラウザーのセキュリティポリシーを検証できません。

関連項目

• bevy-cargo-features — プロファイルの構成。
• bevy-rendering — レンダラー拡張の選択肢。
• bevy-assets — 非同期アセット読み込み。
• bevy-vfx — コンピュートに依存するエフェクト。