Add Emscripten/WebAssembly web port

.github/workflows/build-web.yaml

@@ -0,0 +1,114 @@
+name: Build Web (Emscripten) & Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [ main, feature/emscripten-web-port ]
+  workflow_dispatch:
+
+# Allow only one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build-stable:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout stable branch
+        uses: actions/checkout@v4
+        with:
+          ref: feature/emscripten-web-port
+          submodules: recursive
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y build-essential git python3 libglew-dev libsdl2-dev libz-dev zip
+
+      - name: Setup Emscripten
+        uses: mymindstorm/setup-emsdk@v14
+        with:
+          version: 3.1.64
+
+      - name: Cache Emscripten system libs
+        uses: actions/cache@v4
+        with:
+          path: ~/.emscripten_cache
+          key: emsdk-3.1.64-${{ runner.os }}
+
+      - name: Cache stable build objects
+        uses: actions/cache@v4
+        with:
+          path: build/us_pc
+          key: build-web-stable-${{ runner.os }}-${{ hashFiles('src/**', 'include/**', 'lib/**', 'Makefile', 'sound/**', 'levels/**', 'actors/**', 'assets/**') }}
+
+      - name: Verify Emscripten
+        run: emcc --version
+
+      - name: Clean stale build objects
+        run: |
+          find build/us_pc -name '*.o' -delete 2>/dev/null || true
+          find build/us_pc -name '*.d' -delete 2>/dev/null || true
+
+      - name: Build stable for web
+        run: |
+          emmake make TARGET_WEB=1 VERSION=us -j$(nproc)
+
+      - name: Prepare stable artifact
+        run: |
+          mkdir -p _stable/proxy _stable/icons
+          cp build/us_pc/sm64coopdx.html _stable/
+          cp build/us_pc/sm64coopdx.js _stable/
+          cp build/us_pc/sm64coopdx.wasm _stable/
+          cp build/us_pc/sm64coopdx.data _stable/ 2>/dev/null || true
+          cp build/us_pc/manifest.json _stable/ 2>/dev/null || true
+          cp build/us_pc/sw.js _stable/ 2>/dev/null || true
+          cp build/us_pc/icons/*.png _stable/icons/ 2>/dev/null || true
+          cp src/pc/web/proxy/proxy.js _stable/proxy/ 2>/dev/null || true
+          cp src/pc/web/proxy/package.json _stable/proxy/ 2>/dev/null || true
+          cp src/pc/web/proxy/README.md _stable/proxy/ 2>/dev/null || true
+
+      - name: Upload stable build
+        uses: actions/upload-artifact@v4
+        with:
+          name: stable-build
+          path: _stable/
+
+  deploy:
+    needs: [build-stable]
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Download stable build
+        uses: actions/download-artifact@v4
+        with:
+          name: stable-build
+          path: artifacts/stable
+
+      - name: Assemble Pages site
+        run: |
+          mkdir -p _site/proxy _site/icons
+
+          # Build at root
+          cp artifacts/stable/sm64coopdx.html _site/index.html
+          cp artifacts/stable/sm64coopdx.js _site/
+          cp artifacts/stable/sm64coopdx.wasm _site/
+          cp artifacts/stable/sm64coopdx.data _site/ 2>/dev/null || true
+          cp artifacts/stable/manifest.json _site/ 2>/dev/null || true
+          cp artifacts/stable/sw.js _site/ 2>/dev/null || true
+          cp -r artifacts/stable/icons/* _site/icons/ 2>/dev/null || true
+          cp -r artifacts/stable/proxy/* _site/proxy/ 2>/dev/null || true
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "lib/lua/lua-5.3.6"]
+	path = lib/lua/lua-5.3.6
+	url = https://github.com/lua/lua.git

CLAUDE.md

@@ -0,0 +1,149 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+SM64CoopDX is an online multiplayer mod for Super Mario 64, originally a native C application. The `feature/emscripten-web-port` branch adds a browser-based version using Emscripten/WebAssembly with PeerJS (WebRTC) for peer-to-peer multiplayer networking.
+
+## Build Commands
+
+### Web (Emscripten) Build
+```bash
+# Prerequisites: Emscripten SDK installed at ~/emsdk or /usr/local/emsdk
+./build_web.sh              # Incremental build (DEBUG=1, VERSION=us)
+./build_web.sh clean        # Clean build (removes build/us_pc first)
+```
+Under the hood: `emmake make TARGET_WEB=1 VERSION=us DEBUG=1 -j$(nproc)`
+
+### Serve Locally
+```bash
+./serve.sh   # Starts HTTP server (port 8083) + WebSocket proxy (port 8765)
+# Game at: http://localhost:8083/sm64coopdx.html
+```
+
+The HTTP server (`python3 -m http.server`) does NOT set COOP/COEP headers needed for SharedArrayBuffer. Use `src/pc/web/serve.py` if you need those headers.
+
+### Proxy Server (standalone)
+```bash
+cd src/pc/web/proxy && npm install
+node proxy.js --target-host 127.0.0.1 --target-port 7777 --listen-port 8765
+```
+
+## Architecture: Web/Emscripten Port
+
+### Platform Abstraction
+
+The codebase uses conditional compilation (`#ifdef TARGET_WEB`) and pluggable backends via function-pointer structs:
+
+- **Network:** `struct NetworkSystem` in `network.h` — on web, points to WebSocket/PeerJS implementation
+- **Threading:** `src/pc/thread_web.c` — all no-ops (single-threaded on web)
+- **Sockets:** `src/pc/network/socket/socket.h` conditionally includes `socket_websocket.h` instead of platform UDP headers
+
+### PeerJS Networking (the key web-specific system)
+
+**Two layers:**
+
+1. **JavaScript side** (`src/pc/web/shell.html`, lines ~567-747): `PeerNetwork` object
+   - Manages PeerJS Peer instances, DataConnections, slot ID assignment
+   - Deterministic host peer ID: `'sm64-' + roomId + '-host'`
+   - Auto-detection: tries to register as host first; falls back to client on `unavailable-id` error
+   - Maintains `recvBuffer` array of `{slotId, data}` packets
+
+2. **C side** (`src/pc/network/socket/socket_websocket.c`): EM_JS bridge functions
+   - `peer_init(roomId)`, `peer_send(slotId, data, len)`, `peer_drain_recv()`, `peer_is_connected()`, `peer_shutdown()`
+   - Ring buffer `sRecvBuf[128KB]` with packet format: `[u16 slotId LE][u16 length LE][data...]`
+
+**Packet flow:**
+```
+PeerJS DataConnection → JS recvBuffer → peer_drain_recv() → C sRecvBuf
+→ network_update() processes → peer_send() EM_JS → PeerNetwork.send() → DataConnection
+```
+
+**Host relay:** The host (whether web or native) relays packets between clients. Broadcast packets (slotId=0) go to all except sender. This is handled in `network.c` (~lines 206-245).
+
+### WebSocket-to-UDP Proxy (`src/pc/web/proxy/proxy.js`)
+
+Alternative transport for browser↔native server communication. Two modes via query params:
+- **Client mode** (`?target=HOST:PORT`): 1:1 WebSocket↔UDP bridge
+- **Host mode** (`?host=UDPPORT`): multiplexes clients with 2-byte slot prefix
+
+### Game Loop on Web (`src/pc/pc_main.c`)
+
+Uses `requestAnimationFrame` (not `emscripten_set_main_loop`) calling `web_one_iteration()` at 30 Hz. Each frame: handle SDL events → `network_update()` (drain PeerJS packets) → game logic → Lua scripting → `buffer_audio()`.
+
+### Audio on Web
+
+Audio is fully enabled on the web build using SDL2's Emscripten audio backend (ScriptProcessorNode). Sound effects and music sequences both play faithfully.
+
+**The 32-bit pointer problem:** The pre-compressed sound data (`sound/sound_data_compressed.ctl`, `.tbl`, `sequences_compressed.bin`) was generated by `tools/assemble_sound.py` on a 64-bit host. The binary format uses pointer-sized fields (`P` = 8 bytes on 64-bit, 4 bytes on 32-bit) and padding (`X` = 4 bytes on 64-bit, 0 on 32-bit). On WASM (32-bit), the C structs (`ALSeqFile`, `ALSeqData`, `AudioBank`, `Instrument`, `Drum`, etc.) expect 4-byte pointers, causing struct field misalignment when reading 64-bit data.
+
+**Solution:** The `sound/web/` directory contains 32-bit little-endian versions of all sound data files. The Makefile conditionally uses these when `TARGET_WEB=1`.
+
+**How the web sound data was generated:**
+- **CTL (audio banks):** `tools/convert_ctl_32.py` structurally walks each bank's 64-bit body, converting P (8→4 byte) and X (4→0 byte) fields while remapping all internal pointer offsets. This preserves exact original bank data (ADSR envelopes, tuning, codebooks). Do NOT use `assemble_sound.py` regeneration — it re-encodes AIFC samples, producing different codebook parameters that cause pitch errors and audio artifacts.
+- **TBL (sample data) and sequences:** `tools/convert_seqfile_32.py` converts only the ALSeqFile header (entry table). The data blobs are opaque byte streams with no pointer fields, so they're copied verbatim.
+- **Offset headers:** `samples_offsets.h` and `sequences_offsets.h` need delta-adjusted versions in `sound/web/` because the 32-bit ALSeqFile header is smaller, shifting data start positions. The delta is `align16(8 + count*16) - align16(4 + count*8)`.
+
+**Important notes:**
+- The sequences file only contains seq 0 (SFX player) inline — all other sequences are loaded from ROM at runtime via `ROM_ASSET_LOAD_SEQUENCE`.
+- `samples_assets.c` and `sequences_assets.c` conditionally include from `sound/web/` when `TARGET_WEB` is defined.
+- If the original sound data changes (new banks, sequences, etc.), regenerate web versions by running the converter scripts on the updated compressed files.
+
+**Key files:**
+
+| File | Role |
+|------|------|
+| `sound/web/sound_data_compressed.ctl` | 32-bit LE audio bank control data (45 banks) |
+| `sound/web/sound_data_compressed.tbl` | 32-bit LE header + original sample data |
+| `sound/web/sequences_compressed.bin` | 32-bit LE header + original sequence data |
+| `sound/web/samples_offsets.h` | Sample byte offsets adjusted for 32-bit TBL header |
+| `sound/web/sequences_offsets.h` | Sequence byte offsets adjusted for 32-bit SEQ header |
+| `tools/convert_ctl_32.py` | Structural CTL converter (banks with P/X fields) |
+| `tools/convert_seqfile_32.py` | Header-only converter for TBL and sequences |
+
+### Persistence
+
+- **Config:** `localStorage['sm64coopdx_config']` restored to Emscripten VFS on startup
+- **Save files:** `localStorage['sm64coopdx_save']` (base64), persisted via `web_save_savefile()`
+- **ROM:** Cached in IndexedDB, validated by Z64 magic number, byte-swapped from N64/V64 formats
+
+### Emscripten Linker Settings
+
+Key flags in Makefile (~lines 941-952):
+- `ASYNCIFY` with 65536 stack — allows C to call async JS
+- `INITIAL_MEMORY=268435456` (256MB), `ALLOW_MEMORY_GROWTH`
+- `FORCE_FILESYSTEM` + `libidbfs.js` for virtual filesystem
+- Exported runtime: `ccall`, `cwrap`, `FS`, `allocateUTF8`
+
+### Disabled on Web
+
+Discord SDK, CoopNet (cloud hosting), Mumble voice, update checker, native threading.
+
+### iOS Viewport / Fullscreen Notes
+
+Using `viewport-fit=cover` in the viewport meta tag gives true edge-to-edge fullscreen rendering on iOS (no black bars in portrait or landscape). However, dynamically switching `viewport-fit` between orientations causes touch coordinate offsets on the gamepad overlay buttons — the `position: fixed` elements end up misaligned with where touches register. The current approach uses the default viewport (`width=device-width, initial-scale=1.0`) which has correct touch mapping but leaves a status bar gap in portrait and side bars in landscape on iOS. A future fix could use `viewport-fit=cover` permanently if the touch gamepad coordinates are adjusted to account for `env(safe-area-inset-*)` offsets.
+
+## Key Files
+
+| File | Role |
+|------|------|
+| `src/pc/web/shell.html` | Emscripten HTML shell + PeerNetwork JS (~857 lines) |
+| `src/pc/network/socket/socket_websocket.c` | C↔JS bridge via EM_JS (~360 lines) |
+| `src/pc/network/network.c` | Core networking, relay logic |
+| `src/pc/network/network.h` | NetworkSystem struct, NetworkType enum |
+| `src/pc/pc_main.c` | Game entry, `web_one_iteration()` |
+| `src/pc/web/web_main.c` | ROM/config persistence, URL param handling |
+| `src/pc/web/proxy/proxy.js` | WebSocket↔UDP proxy server |
+| `src/pc/network/packets/packet.c` | Packet processing pipeline (45+ packet types) |
+
+## URL Parameters
+
+The web build supports auto-join/host via URL:
+- `?room=NAME` — PeerJS room identifier
+- `?join=HOST:PORT` — auto-join a server
+- `?host=PORT` — auto-host a server
+
+## CI/CD
+
+`.github/workflows/build-web.yaml` builds on Ubuntu 22.04 with emsdk 3.1.64, deploys to GitHub Pages.