Add browser (WASM) build target with GitHub Pages demo

- build_web.sh: wasm32-unknown-unknown release build, version-matched
  wasm-bindgen-cli auto-install, packages target/web_dist static site
- web/index.html: canvas host page (game name templated via {{GAME_NAME}})
- Cargo.toml: webgl2 bevy feature; getrandom wasm_js feature for the
  ahash-pulled getrandom 0.3 (plus RUSTFLAGS cfg in script and CI)
- lib.rs: bind window to #game-canvas, fit_canvas_to_parent (wasm only)
- CI: web job builds + zips the site into the release and deploys it to
  GitHub Pages as a live demo; setup_env.sh checks the wasm toolchain
- README: demo link, web row/scripts/quick-start, load-bearing wasm notes

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: maxfridbe

.github/workflows/release.yml

@@ -80,6 +80,62 @@ jobs:
           name: windows
           path: "*.zip"
 
+  web:
+    needs: meta
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: wasm32-unknown-unknown
+      - uses: Swatinem/rust-cache@v2
+      - name: Build
+        env:
+          RUSTFLAGS: --cfg getrandom_backend="wasm_js"
+        run: cargo build --release --target wasm32-unknown-unknown
+      - name: Install wasm-bindgen-cli (prebuilt, version-matched to Cargo.lock)
+        run: |
+          WBV=$(grep -A1 '^name = "wasm-bindgen"$' Cargo.lock | grep '^version' | cut -d'"' -f2)
+          echo "wasm-bindgen crate version: $WBV"
+          curl -sL "https://github.com/rustwasm/wasm-bindgen/releases/download/$WBV/wasm-bindgen-$WBV-x86_64-unknown-linux-musl.tar.gz" | tar xz
+          sudo mv "wasm-bindgen-$WBV-x86_64-unknown-linux-musl/wasm-bindgen" /usr/local/bin/
+          wasm-bindgen --version
+      - name: Package
+        run: |
+          GAME='${{ needs.meta.outputs.game }}'
+          V='${{ needs.meta.outputs.version }}'
+          mkdir -p dist
+          wasm-bindgen --no-typescript --target web \
+            --out-dir dist --out-name "$GAME" \
+            "target/wasm32-unknown-unknown/release/$GAME.wasm"
+          sed "s/{{GAME_NAME}}/$GAME/g" web/index.html > dist/index.html
+          (cd dist && zip -r "../$GAME-web-v$V.zip" .)
+      - uses: actions/upload-artifact@v4
+        with:
+          name: web
+          path: "*.zip"
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist
+
+  # Publishes the web build as a live demo at https://<user>.github.io/<repo>/
+  pages:
+    needs: web
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Enable GitHub Pages (first run only)
+        uses: actions/configure-pages@v5
+        with:
+          enablement: true
+      - id: deployment
+        uses: actions/deploy-pages@v4
+
   android:
     needs: meta
     runs-on: ubuntu-latest
@@ -154,7 +210,7 @@ jobs:
           path: "*.apk"
 
   release:
-    needs: [meta, linux, windows, android]
+    needs: [meta, linux, windows, android, web]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/download-artifact@v4

Cargo.toml

@@ -9,6 +9,7 @@ edition = "2024"
 #   android-native-activity -> required for the cargo-apk Android path
 #   x11                     -> required for native Linux windowing
 #   multi_threaded          -> desktop performance (ignored on wasm)
+#   webgl2                  -> required for the browser/WASM build
 bevy = { version = "0.15.2", default-features = false, features = [
     "android-native-activity",
     "bevy_asset",
@@ -31,6 +32,7 @@ bevy = { version = "0.15.2", default-features = false, features = [
     "png",
     "smaa_luts",
     "tonemapping_luts",
+    "webgl2",
     "x11"
 ] }
 # Embeds the assets/ folder into the binary/APK so no runtime file IO is
@@ -40,6 +42,13 @@ bevy_embedded_assets = "0.12"
 # Bevy's audio backend on Android (links against libc++_shared.so).
 cpal = { version = "0.15", features = ["oboe-shared-stdcxx"] }
 
+# Browser build: ahash (via bevy) pulls getrandom 0.3, which refuses to
+# compile for wasm32-unknown-unknown unless the JS backend is enabled —
+# this feature plus RUSTFLAGS --cfg getrandom_backend="wasm_js" (set by
+# build_web.sh and the CI web job).
+[target.'cfg(target_arch = "wasm32")'.dependencies]
+getrandom = { version = "0.3", features = ["wasm_js"] }
+
 # The library build is what Android consumes (cdylib for cargo-apk /
 # NativeActivity, staticlib for other embedding scenarios). The rlib lets
 # the desktop binary below reuse the same code.

README.md

@@ -1,6 +1,8 @@
 # GameBase
 
-A minimal Bevy (Rust) starter game that already ships to **Linux**, **Windows**, and **Android (APK)** from a single Linux dev machine. The build methodology was extracted from the Julian2 train game project.
+A minimal Bevy (Rust) starter game that already ships to **Linux**, **Windows**, **Android (APK)**, and the **browser (WASM)** from a single Linux dev machine. The build methodology was extracted from the Julian2 train game project.
+
+**[▶ Play the demo in your browser](https://maxfridbe.github.io/GameBase/)** — deployed automatically to GitHub Pages by the release workflow.
 
 The base game is a sphere you drive around a 3D plane:
 
@@ -28,6 +30,7 @@ src/main.rs  -> tiny desktop wrapper: fn main() { game_base::run_game() }
 | Windows | cross-compile from Linux with MinGW (`x86_64-pc-windows-gnu`) | `target/windows_dist/` (exe + assets, zip and ship) |
 | Android A (**primary**) | `cargo apk` builds the **cdylib** into an APK per ABI; NativeActivity, no Java code at all | `target/{debug,release}/apk/*.apk` |
 | Android B (alternative) | `cargo ndk` drops the cdylib into `app/src/main/jniLibs/`, then Gradle wraps it with a Java `GameActivity` into one universal APK | `app/build/outputs/apk/debug/app-debug.apk` |
+| Browser (WASM) | compile the bin to `wasm32-unknown-unknown` (webgl2 feature), `wasm-bindgen` generates the JS glue, `web/index.html` hosts the canvas | `target/web_dist/` (static site — serve anywhere) |
 
 Key load-bearing details (easy to lose, hard to rediscover):
 
@@ -37,6 +40,7 @@ Key load-bearing details (easy to lose, hard to rediscover):
 - Two APKs are built on purpose in Path A: **x86_64** for the desktop emulator, **arm64-v8a** for real phones. Path B builds one fat APK containing both.
 - Emulator GPU emulation matters for wgpu/Vulkan: `swangle_indirect` (run_emulator.sh) is the most stable; `start_new_emulator.sh` is the SwiftShader/CPU fallback for hosts whose GPU driver crashes the emulator.
 - `game.env` centralizes the game identity + Android SDK paths; every script sources it.
+- Browser build details: `bevy_embedded_assets` means the `.wasm` is fully self-contained (no asset fetch issues on static hosts); `wasm-bindgen-cli` must exactly match the `wasm-bindgen` crate version in `Cargo.lock` (`build_web.sh` auto-installs the right one); `getrandom` 0.3 (pulled via ahash/bevy) needs the `wasm_js` feature **and** `RUSTFLAGS=--cfg getrandom_backend="wasm_js"` — both are wired in already; the window is bound to the `#game-canvas` element in `web/index.html`.
 
 ## Scripts
 
@@ -46,6 +50,7 @@ Key load-bearing details (easy to lose, hard to rediscover):
 | `setup_env.sh` | Check, then install only what's missing: system packages (apt or dnf detected automatically), Rust + cross targets, MinGW-w64, cargo-apk/cargo-ndk, Android SDK/NDK 26, debug keystore |
 | `run_linux.sh [debug]` | Build + run natively on Linux |
 | `build_windows.sh` | Cross-compile Windows release, package exe + assets into `target/windows_dist/` |
+| `build_web.sh` | Build the browser version into `target/web_dist/` (compile to wasm, run wasm-bindgen, add `web/index.html`) |
 | `build_cargo_apk.sh` / `_debug.sh` | Path A: build emulator (x86_64) + phone (ARM64) APKs |
 | `deploy_cargo_apk.sh` | Install Path A APK to running emulator, launch, follow logcat |
 | `deploy_phone.sh` | Install Path A ARM64 APK to USB phone, launch, follow logcat |
@@ -67,6 +72,7 @@ Key load-bearing details (easy to lose, hard to rediscover):
    - `<game>-linux-x86_64-v<version>.tar.gz` (binary + assets)
    - `<game>-windows-x86_64-v<version>.zip` (exe + assets, MinGW cross-compiled)
    - `<game>-android-arm64-v<version>.apk` (phones) and `<game>-android-x86_64-v<version>.apk` (emulator)
+   - `<game>-web-v<version>.zip` (static site) — the same build is also deployed to **GitHub Pages** as the live demo (first run: if the `pages` job fails, enable Pages once under repo Settings → Pages → Source: GitHub Actions)
 
 Pushing again without bumping the version updates the existing release for that tag rather than creating a new one. CI signs APKs with a freshly generated debug keystore — replace that step with a real keystore (repo secret) before shipping to a store.
 
@@ -77,6 +83,8 @@ Pushing again without bumping the version updates the existing release for that
 ./setup_env.sh          # once per machine; installs only the missing pieces (apt or dnf)
 ./run_linux.sh          # play on Linux
 ./build_windows.sh      # produce target/windows_dist/ for Windows
+./build_web.sh          # produce target/web_dist/ for the browser
+python3 -m http.server -d target/web_dist 8080   # ...then play at localhost:8080
 ./run_emulator.sh       # boot the Android emulator...
 ./build_cargo_apk_debug.sh && ./deploy_cargo_apk.sh   # ...and play in it
 ./build_cargo_apk.sh && ./deploy_phone.sh             # play on a USB phone
@@ -114,6 +122,8 @@ GRADLE_PACKAGE="org.yourstudio.my_game"   # = app/build.gradle applicationId
 
 **3. App icon** — replace `assets/android-res/mipmap-mdpi/ic_launcher.png` (used by both Android paths).
 
+**3b. Demo link** — the browser demo deploys to `https://<your-user>.github.io/<your-repo>/`; update the link at the top of this README. (`web/index.html` needs no changes — `build_web.sh` fills in the game name.)
+
 **4. Only if you use Path B (Gradle):**
 
 - `app/build.gradle` — `namespace` and `applicationId`
@@ -142,4 +152,5 @@ sed -i "s/Game Base/$NEWLABEL/g" Cargo.toml src/lib.rs
 | Android NDK | 26.1.10909125 | referenced by every script + setup |
 | AGP / Gradle | 8.4.0 / 8.6 | Path B only |
 | games-activity | 4.4.0 | must stay compatible with bevy's `android-activity` crate |
+| wasm-bindgen-cli | = `wasm-bindgen` in Cargo.lock | hard requirement; `build_web.sh`/CI resolve it automatically |
 | minSdk / target/compileSdk | 30 / 33 / 34 | Path B only; cargo-apk defaults handle Path A |

build_web.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+# Build the browser (WASM) version: compile to wasm32-unknown-unknown, run
+# wasm-bindgen to generate the JS glue, and package a static site folder.
+# Assets are embedded in the .wasm via bevy_embedded_assets, so the output
+# is fully self-contained and works from any static file host.
+cd "$(dirname "$0")"
+source ./game.env
+set -e
+
+echo "=== Preparing WASM Build Environment ==="
+rustup target add wasm32-unknown-unknown
+
+echo "=== Building for wasm32-unknown-unknown (Release) ==="
+# getrandom needs to be told to use the browser's crypto API (see Cargo.toml)
+export RUSTFLAGS="${RUSTFLAGS:+$RUSTFLAGS }--cfg getrandom_backend=\"wasm_js\""
+cargo build --release --target wasm32-unknown-unknown
+
+# wasm-bindgen-cli MUST match the wasm-bindgen crate version in Cargo.lock.
+WBV=$(grep -A1 '^name = "wasm-bindgen"$' Cargo.lock | grep '^version' | cut -d'"' -f2)
+if ! command -v wasm-bindgen &>/dev/null || [ "$(wasm-bindgen --version | awk '{print $2}')" != "$WBV" ]; then
+    echo "Installing wasm-bindgen-cli $WBV (must match the wasm-bindgen crate)..."
+    cargo install wasm-bindgen-cli --version "$WBV" --locked --force
+fi
+
+DIST_DIR="target/web_dist"
+echo "Packaging into $DIST_DIR..."
+rm -rf "$DIST_DIR"
+mkdir -p "$DIST_DIR"
+
+wasm-bindgen --no-typescript --target web \
+    --out-dir "$DIST_DIR" --out-name "$GAME_NAME" \
+    "target/wasm32-unknown-unknown/release/$GAME_NAME.wasm"
+
+sed "s/{{GAME_NAME}}/$GAME_NAME/g" web/index.html > "$DIST_DIR/index.html"
+
+echo ""
+echo "Done! The web build is ready in $DIST_DIR"
+echo "  Size: $(ls -lh "$DIST_DIR/${GAME_NAME}_bg.wasm" | awk '{print $5}') (wasm)"
+echo "Try it locally:  python3 -m http.server -d $DIST_DIR 8080"
+echo "Then open:       http://localhost:8080"

setup_env.sh

@@ -61,7 +61,15 @@ else
     bad "rust target x86_64-pc-windows-gnu"
 fi
 
-echo "=== 4. Android APK builds (build_cargo_apk*.sh / buildanddeploy.sh) ==="
+echo "=== 4. Browser/WASM build (build_web.sh) ==="
+if have rustup && rustup target list --installed 2>/dev/null | grep -q wasm32-unknown-unknown; then
+    ok "rust target wasm32-unknown-unknown"
+else
+    bad "rust target wasm32-unknown-unknown"
+fi
+have wasm-bindgen && ok "wasm-bindgen-cli" || bad "wasm-bindgen-cli (build_web.sh auto-installs the version matching Cargo.lock)"
+
+echo "=== 5. Android APK builds (build_cargo_apk*.sh / buildanddeploy.sh) ==="
 for t in aarch64-linux-android x86_64-linux-android; do
     if have rustup && rustup target list --installed 2>/dev/null | grep -q "$t"; then
         ok "rust target $t"
@@ -122,10 +130,13 @@ fi
 
 echo "Adding cross-compile targets to Rust..."
 rustup target add x86_64-pc-windows-gnu
+rustup target add wasm32-unknown-unknown
 rustup target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android i686-linux-android
 
 have cargo-apk || cargo install cargo-apk
 have cargo-ndk || cargo install cargo-ndk
+# build_web.sh re-installs the exact version matching Cargo.lock if needed
+have wasm-bindgen || cargo install wasm-bindgen-cli
 
 # Android SDK/NDK Setup
 if [ ! -d "$ANDROID_HOME/ndk/$NDK_VERSION" ] || [ ! -x "$ANDROID_HOME/platform-tools/adb" ]; then

src/lib.rs

@@ -44,6 +44,10 @@ pub fn run_game() {
         .add_plugins(DefaultPlugins.set(WindowPlugin {
             primary_window: Some(Window {
                 title: "Game Base".into(),
+                // Browser build: render into the canvas provided by
+                // web/index.html and track its CSS size. Ignored on native.
+                canvas: Some("#game-canvas".into()),
+                fit_canvas_to_parent: true,
                 ..default()
             }),
             ..default()

web/index.html

@@ -0,0 +1,32 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>{{GAME_NAME}}</title>
+    <style>
+        html, body { margin: 0; padding: 0; height: 100%; background: #0a0d17; overflow: hidden; }
+        canvas { display: block; width: 100%; height: 100%; outline: none; }
+        #loading {
+            position: absolute; inset: 0; display: flex; align-items: center; justify-content: center;
+            color: #cbd3e8; font: 16px system-ui, sans-serif; pointer-events: none;
+        }
+    </style>
+</head>
+<body>
+    <div id="loading">Loading&hellip;</div>
+    <canvas id="game-canvas"></canvas>
+    <script type="module">
+        import init from './{{GAME_NAME}}.js';
+        init()
+            .catch((error) => {
+                // Bevy uses an exception to hand control to the browser's
+                // event loop on startup; it is not a real error.
+                if (!error.message.startsWith("Using exceptions for control flow,")) {
+                    throw error;
+                }
+            })
+            .finally(() => document.getElementById('loading').remove());
+    </script>
+</body>
+</html>