wasmcart 0.2.0

package/docs/gl-surface.md

@@ -0,0 +1,111 @@
+# wasmcart GL Surface Specification
+
+## Overview
+
+The wasmcart GL surface is **WebGL2 / OpenGL ES 3.0**. This is the same on all hosts:
+browser, Node.js, wasmcart-native, and RetroArch (libretro).
+
+The host reports `GL_VERSION = "OpenGL ES 3.0 wasmcart"` regardless of the actual
+driver. Real driver extensions pass through for engines that need them (e.g., Godot
+texture format detection).
+
+## Shader Requirements
+
+All shaders MUST use one of:
+- `#version 100` (GLES 2.0 - works everywhere)
+- `#version 300 es` (GLES 3.0 / WebGL2 - recommended)
+
+Desktop GL version strings (`#version 110`, `#version 120`, `#version 330 core`)
+are NOT supported. The host does NOT translate shaders.
+
+## Texture Formats
+
+The host translates legacy/unsized formats to ES 3.0 equivalents:
+
+| Legacy Format | ES 3.0 Internal Format | ES 3.0 Format |
+|--------------|----------------------|--------------|
+| `GL_LUMINANCE` | `GL_R8` | `GL_RED` |
+| `GL_LUMINANCE_ALPHA` | `GL_RG8` | `GL_RG` |
+| `GL_ALPHA` | `GL_R8` | `GL_RED` |
+| `GL_RGB` (ubyte) | `GL_RGB8` | `GL_RGB` |
+| `GL_RGBA` (ubyte) | `GL_RGBA8` | `GL_RGBA` |
+
+Carts SHOULD use sized internal formats (`GL_RGBA8`, `GL_R8`, etc.) directly.
+The host fixup exists for compatibility with legacy GL code.
+
+## Porting GL 1.x Games
+
+Games written for OpenGL 1.x (fixed-function pipeline) need a renderer rewrite
+to target ES 3.0. There are two approaches:
+
+### 1. Purpose-built gl_compat (recommended)
+
+Write a small translation layer (~500-1000 lines) that replaces GL 1.x calls
+with ES 3.0 shader-based equivalents. This is compiled into the cart.
+
+Example: `chromium_bsu/gl_compat.cpp` - batch renderer with `#version 300 es`
+shaders. Handles glBegin/glEnd, matrix stack, texture state, blending.
+
+Advantages:
+- No external dependencies
+- Small binary size
+- Only translates what the game actually uses
+- Full ES 3.0 compliance
+
+### 2. gl4es (legacy compatibility)
+
+Use [ptitSeb/gl4es](https://github.com/ptitSeb/gl4es) to translate GL 1.x → GLES 2.0.
+gl4es is compiled to WASM as a static library and linked into the cart.
+
+Current gl4es carts: Neverball, Neverputt, Extreme Tux Racer.
+
+Limitations:
+- gl4es only targets GLES 2.0, not ES 3.0
+- Requires host-side format fixup and extension injection
+- Large dependency (~150K lines)
+- Shader version issues on Core 3.3 contexts (RetroArch desktop)
+
+gl4es patches required for wasmcart:
+- `hardext.c`: disable `#version 120` detection, force `esversion = 3`
+- Build with `NO_LOADER=ON`, `NOEGL=ON`, `STATICLIB=ON`
+
+### Games that DON'T need translation
+
+Games with native GLES 2.0/3.0 renderers work on all hosts with zero translation:
+- Godot 4.x (GLES3 Compatibility renderer)
+- ioquake3 renderergl2 (GLES2/3 path)
+- GZDoom (GLES2 renderer)
+- Any Emscripten/WebGL2 game
+- SDL2 games using GLES backend
+
+## FBO Redirect
+
+The host intercepts `glBindFramebuffer(GL_FRAMEBUFFER, 0)` and redirects to an
+internal FBO with depth24+stencil8 attachments. This FBO is then blitted to the
+display surface (EGL window, RetroArch hw_render FBO, or canvas backbuffer).
+
+Carts should bind FBO 0 when they want to render to the "screen". The host
+handles the actual presentation.
+
+## VAO Handling
+
+On GLES 3.0, VAO 0 is the default VAO. On Core 3.3 (RetroArch desktop),
+VAO 0 is invalid. The host creates an isolated cart VAO and redirects
+`glBindVertexArray(0)` to it. The host also binds this VAO at frame start
+for carts that don't use VAOs at all (gl4es).
+
+## Extension Passthrough
+
+`GL_EXTENSIONS` returns real driver extensions. On Core 3.3 contexts,
+the host also injects GLES-equivalent extension names (`GL_OES_*`, `GL_EXT_*`)
+so GLES-targeting code (like gl4es) can detect features.
+
+`GL_SHADING_LANGUAGE_VERSION` passes through real values so carts can
+detect Core vs GLES contexts if needed.
+
+## Buffer Orphaning
+
+The host applies buffer orphaning on `glBufferSubData` with offset 0:
+`glBufferData(target, size, NULL, GL_STREAM_DRAW)` is called first to
+avoid GPU sync stalls on mobile drivers (Mali, Adreno). This is transparent
+to the cart.

package/docs/input.md

@@ -0,0 +1,102 @@
+# Input - Gamepad, Pointer, Keyboard
+
+## Gamepad Input (Always Available)
+
+Every wasmcart host normalizes controller input to the **W3C Standard Gamepad** layout before writing to `wc_pads[]`. The cart always sees the same button/axis mapping regardless of the physical controller.
+
+### Normalization Pipeline
+
+```
+Physical controller (Xbox, PS5, 8BitDo, Switch Pro, etc.)
+    ↓
+Host SDL / HID driver
+    ↓
+SDL GameController mapping (gamecontrollerdb.txt - 2000+ controller definitions)
+    ↓
+Normalized to W3C Standard Gamepad layout
+    ↓
+Written to wc_pad_t[4] shared memory
+    ↓
+Cart reads buttons/axes - every controller looks the same
+```
+
+This means:
+- An Xbox controller's A button = `WC_BTN_A` = W3C `buttons[0]`
+- A PlayStation DualSense's X button = `WC_BTN_A` = W3C `buttons[0]`
+- A Nintendo Pro Controller's B button = `WC_BTN_A` = W3C `buttons[0]`
+- A virtual touchscreen overlay's south button = `WC_BTN_A` = W3C `buttons[0]`
+
+The cart never needs to know what controller is physically connected.
+
+### wc_pad_t Layout (16 bytes per pad)
+
+```c
+typedef struct {
+    uint16_t buttons;        // Bitmask (WC_BTN_A, WC_BTN_B, etc.)
+    int16_t  left_x;         // Left stick X: -32768 to 32767
+    int16_t  left_y;         // Left stick Y: -32768 to 32767
+    int16_t  right_x;        // Right stick X: -32768 to 32767
+    int16_t  right_y;        // Right stick Y: -32768 to 32767
+    uint8_t  left_trigger;   // Left trigger: 0-255
+    uint8_t  right_trigger;  // Right trigger: 0-255
+    uint8_t  connected;      // 1 if controller is connected
+    uint8_t  _pad[3];        // Alignment padding
+} wc_pad_t;
+```
+
+### Button Mapping (W3C Standard Gamepad)
+
+| Bit | Constant | W3C Index | Xbox | PlayStation | Nintendo |
+|-----|----------|-----------|------|-------------|----------|
+| 0 | `WC_BTN_A` | buttons[0] | A | Cross | B |
+| 1 | `WC_BTN_B` | buttons[1] | B | Circle | A |
+| 2 | `WC_BTN_X` | buttons[2] | X | Square | Y |
+| 3 | `WC_BTN_Y` | buttons[3] | Y | Triangle | X |
+| 4 | `WC_BTN_L` | buttons[4] | LB | L1 | L |
+| 5 | `WC_BTN_R` | buttons[5] | RB | R1 | R |
+| 6 | - | buttons[6] | LT (analog) | L2 (analog) | ZL |
+| 7 | - | buttons[7] | RT (analog) | R2 (analog) | ZR |
+| 8 | `WC_BTN_SELECT` | buttons[8] | Back/View | Share | - |
+| 9 | `WC_BTN_START` | buttons[9] | Start/Menu | Options | + |
+| 10 | `WC_BTN_UP` | buttons[12] | D-pad Up | D-pad Up | D-pad Up |
+| 11 | `WC_BTN_DOWN` | buttons[13] | D-pad Down | D-pad Down | D-pad Down |
+| 12 | `WC_BTN_LEFT` | buttons[14] | D-pad Left | D-pad Left | D-pad Left |
+| 13 | `WC_BTN_RIGHT` | buttons[15] | D-pad Right | D-pad Right | D-pad Right |
+| 14 | `WC_BTN_L3` | buttons[10] | LS Click | L3 | LS Click |
+| 15 | `WC_BTN_R3` | buttons[11] | RS Click | R3 | RS Click |
+
+Triggers (buttons[6]/[7]) are analog - use `left_trigger`/`right_trigger` (0-255) for analog values, or the button bit for digital pressed/not-pressed.
+
+### Axes
+
+| Axis | W3C Index | Range |
+|------|-----------|-------|
+| Left Stick X | axes[0] | -32768 to 32767 (left to right) |
+| Left Stick Y | axes[1] | -32768 to 32767 (up to down) |
+| Right Stick X | axes[2] | -32768 to 32767 |
+| Right Stick Y | axes[3] | -32768 to 32767 |
+
+Note: W3C Gamepad API uses -1.0 to 1.0 floats. wasmcart uses int16. JS game runtimes (wasmcart-jsgame) convert: `axes[i] = pad.left_x / 32767.0`.
+
+### For JS Game Runtimes
+
+When exposing `navigator.getGamepads()` to JavaScript games, the gamepad object **must** include `mapping: 'standard'`. Many game frameworks (Phaser, custom engines) filter gamepads by this property:
+
+```javascript
+// Common pattern in game code:
+gamepads = navigator.getGamepads().filter(gp => gp && gp.mapping === 'standard');
+```
+
+Without `mapping: 'standard'`, the gamepad is invisible to the game even though input data is available.
+
+### 4-Player Support
+
+`wc_pads[0]` through `wc_pads[3]` support up to 4 controllers. The host maps physical controllers to pad slots in connection order. `connected` field indicates which slots are active.
+
+## Pointer Input (Opt-In, ABI v3)
+
+Unified mouse + multitouch. Cart declares `"pointer": true` in manifest. Host writes `wc_pointer_t[10]` state each frame.
+
+## Keyboard Input (Opt-In, ABI v3)
+
+256-bit key state bitmask using USB HID scancodes. Cart declares `"keyboard": true` in manifest. Host writes `uint8_t[32]` bitmask each frame.

package/docs/networking.md

@@ -0,0 +1,78 @@
+# Networking - Future Design Notes
+
+## Current ABI
+
+WebSocket client-only:
+- `wc_ws_open(url, len)` - connect outbound
+- `wc_ws_send` / `wc_ws_send_text` - send data
+- `wc_ws_close` / `wc_ws_state` - lifecycle
+- `wc_ws_on_open` / `wc_ws_on_message` / `wc_ws_on_close` - callbacks (host → cart)
+
+Manifest allowlist controls which domains the cart can connect to.
+
+## Planned: Peer-to-Peer Multiplayer
+
+### Concept
+One player "hosts", another "joins" - like classic LAN play. No cloud infrastructure required.
+
+### Cart-Side API
+The cart uses the same WebSocket ABI with one addition:
+
+- `wc_ws_listen(port)` - cart thinks it's hosting a WebSocket server
+- `wc_ws_on_connect(conn_id)` - host notifies cart of new peer
+- All data flows through existing `wc_ws_send` / `wc_ws_on_message`
+
+The cart has NO idea what transport is underneath.
+
+### Host-Side Reality
+The host implements "listen" as WebRTC data channels:
+
+1. Cart calls `wc_ws_listen` → host creates WebRTC peer connection
+2. Signaling handshake (SDP/ICE exchange) - could be:
+   - Local network discovery (mDNS/broadcast)
+   - QR code displayed on screen
+   - Simple signaling server (tiny, stateless)
+3. Data channel established → host calls `wc_ws_on_connect(conn_id)`
+4. All subsequent send/receive goes through the data channel
+5. Cart sees it as a normal WebSocket connection
+
+### Why WebRTC Under the Hood
+- **NAT traversal** - works over the internet, not just LAN
+- **Peer-to-peer** - no relay server needed (STUN is free, Google/Cloudflare run public ones)
+- **Low latency** - UDP-based data channels, ideal for games
+- **No infrastructure** - the user doesn't need to run servers
+- **Browser-compatible** - browser wasmcart hosts get WebRTC for free
+
+### Why the Cart Doesn't Know
+- Same ABI for LAN and internet play
+- Cart code stays simple - just WebSocket send/receive
+- Host can swap transport (WebRTC, actual WebSocket, Bluetooth, etc.) without cart changes
+- Security - cart can't access raw WebRTC APIs (no fingerprinting, no media capture)
+
+### Signaling Options (Lightweight)
+- **QR code** - host player's screen shows QR with SDP offer, joining player scans it
+- **Local network** - mDNS/UDP broadcast discovers peers on same WiFi
+- **Room codes** - 4-digit code, tiny stateless signaling relay matches peers
+- **Manual IP** - old school, type in the IP (works on LAN without any service)
+
+### Example Flow
+```
+Player 1 (host):
+  game calls wc_ws_listen(0)
+  host creates WebRTC peer, shows room code "ABCD" on screen
+  waits for peer...
+
+Player 2 (join):
+  game calls wc_ws_open("room:ABCD")
+  host creates WebRTC peer, signals via room code
+  data channel established
+
+Both carts:
+  wc_ws_on_connect(conn_id) fires
+  wc_ws_send(conn_id, game_packet, len) - just works
+  wc_ws_on_message(conn_id, data, len) - just works
+```
+
+## Planned: wc_fetch
+
+See [fetch.md](fetch.md). Lower priority - games ship assets in .wasc, WebSocket covers real-time comms. Fetch is mainly for leaderboards/analytics which most non-browser games don't need.

package/docs/porting.md

@@ -0,0 +1,88 @@
+# Porting Games to wasmcart
+
+## Target: ES 3.0 / WebGL2
+
+wasmcart's GL surface is ES 3.0. All carts should use GLES 2.0 or 3.0
+shaders. See [gl-surface.md](gl-surface.md) for the full spec.
+
+## Easiest Ports (zero GL translation needed)
+
+| Source | Examples | Notes |
+|--------|----------|-------|
+| GLES 2.0/3.0 native | Godot, GZDoom | Engine handles GL, just wire up ABI |
+| SDL2 + GLES | Many modern games | Use wasmcart SDL2 backend (sdl2_wc/) |
+| Emscripten/WebGL2 | Browser games | Already WASM, add wasmcart ABI |
+| ioquake3-based | OpenArena, Quake 3 | renderergl2 has GLES path |
+| Canvas 2D / pixel buffer | Retro games | Use wc_gl_blit.h for GPU upload |
+
+## GL 1.x Games
+
+Games using OpenGL 1.x (glBegin/glEnd, fixed-function lighting, display lists)
+need a renderer rewrite. Two approaches:
+
+### Approach 1: Custom gl_compat (recommended)
+
+Write a purpose-built ES 3.0 batch renderer for the specific game.
+Only translate the GL 1.x calls the game actually uses.
+
+**Example:** Chromium B.S.U. - `gl_compat.cpp` (~500 lines)
+- Replaces immediate mode with VBO batching
+- `#version 300 es` shaders
+- Matrix stack, texture state, blending
+- Zero external dependencies
+- Compiled with `-include chromium_compat.h` (zero original files modified)
+
+**Upstream value:** These renderers can be submitted as PRs to the original
+game projects, benefiting the entire community.
+
+### Approach 2: gl4es (quick start, more complexity)
+
+Use [gl4es](https://github.com/ptitSeb/gl4es) for automatic translation.
+See [gl-surface.md](gl-surface.md#gl4es-legacy-compatibility) for details.
+
+## Porting Checklist
+
+1. **Build to WASM** - Emscripten with `-sWASM=1`
+2. **Export ABI** - `wc_get_info`, `wc_init`, `wc_render`
+3. **Set gpu_api** - `wc_info_t.gpu_api = 1` (GL) for all carts
+4. **Use ES 3.0 shaders** - `#version 100` or `#version 300 es`
+5. **Assets via .wasc** - Pack with `wasmcart-pack`, load via `wc_asset_size`/`wc_load_asset`
+6. **Audio** - Write to ring buffer, set sample rate + format flags
+7. **Input** - Read `wc_pad_t` array (Xbox/W3C button layout)
+8. **Test on all hosts** - Browser, Node.js, wasmcart-native, RetroArch
+
+## Shared Porting Libraries
+
+Located at `wasmcart/porting/include/`:
+
+| Header | Purpose |
+|--------|---------|
+| `wc_cart.h` | Buffer declarations, WC_FILL_INFO macro |
+| `wc_gl.h` | Shader compile/link, VAO/VBO helpers |
+| `wc_gl_blit.h` | Upload CPU pixels as GL texture (2D→GL) |
+| `wc_fb.h` | 2D framebuffer drawing (fill_rect, blit) |
+| `wc_math.h` | sin, cos, sqrt, atan2, clamp, lerp |
+| `wc_mat4.h` | 4x4 column-major matrix ops |
+| `wc_vec3.h` | 3D vector operations |
+| `wc_pcm_mixer.h` | Multi-channel PCM audio mixer |
+| `wc_sdl_stubs.h` | SDL2 type defs + no-op stubs |
+| `stb_image.h` | Image loading (JPEG, PNG, BMP) |
+| `audio_bridge.h/c` | SDL2_mixer → ring buffer bridge |
+| `emstubs.c` | Emscripten runtime stubs |
+
+## SDL2 Games (Emscripten Backend)
+
+Use the reusable `sdl2_wc/` backends for SDL2 games:
+
+```bash
+# Compile: use SDL2 headers from Emscripten
+-sUSE_SDL=2  # at compile time (headers only)
+
+# Link: use wasmcart's SDL2 backend, not Emscripten's
+-sUSE_SDL=0  # at link time
+```
+
+The SDL2 backend provides video (GL surface), audio (ring buffer),
+and input (gamepad) - all wired to the wasmcart ABI.
+
+Validated on: Neverball ES, Neverputt ES, Celeste Classic ES, Flare ES.

package/include/wc_cart.h

@@ -0,0 +1,144 @@
+/*
+ * wc_cart.h - Cart boilerplate macros for wasmcart
+ *
+ * Reduces the ~40 lines of buffer declarations + wc_get_info() that
+ * every cart copy-pastes. Include this AFTER wasmcart.h.
+ *
+ * USAGE (GL cart):
+ *
+ *   #define WC_USE_GL
+ *   #include "wasmcart.h"
+ *   #include "wc_cart.h"
+ *
+ *   // Define your resolution and audio settings:
+ *   #define DEFAULT_WIDTH  640
+ *   #define DEFAULT_HEIGHT 480
+ *   #define MAX_WIDTH  1920
+ *   #define MAX_HEIGHT 1080
+ *   #define AUDIO_CAP 4096
+ *
+ *   // Declare all cart buffers at once:
+ *   WC_CART_BUFFERS;
+ *
+ *   // In your wc_get_info():
+ *   WC_EXPORT wc_info_t *wc_get_info(void) {
+ *       WC_FILL_INFO(0);
+ *       return &wc_info;
+ *   }
+ *
+ * USAGE (2D framebuffer cart):
+ *
+ *   #include "wasmcart.h"
+ *   #include "wc_cart.h"
+ *
+ *   #define DEFAULT_WIDTH  320
+ *   #define DEFAULT_HEIGHT 240
+ *   #define MAX_WIDTH  320
+ *   #define MAX_HEIGHT 240
+ *   #define AUDIO_CAP 4096
+ *
+ *   WC_CART_BUFFERS;
+ *
+ *   WC_EXPORT wc_info_t *wc_get_info(void) {
+ *       WC_FILL_INFO(0);
+ *       return &wc_info;
+ *   }
+ *
+ * WHAT THIS PROVIDES:
+ *   WC_CART_BUFFERS   - declares all standard cart globals
+ *   WC_FILL_INFO(f)   - fills wc_info struct fields
+ *   WC_EXPORT         - shorthand for __attribute__((export_name(...)))
+ *
+ * You still write your own wc_init() and wc_render() - those have
+ * game-specific logic that can't be templated.
+ */
+
+#ifndef WC_CART_H
+#define WC_CART_H
+
+#ifndef WASMCART_H
+#error "Include wasmcart.h before wc_cart.h"
+#endif
+
+/* ── Export attribute shorthand ────────────────────────────────────── */
+
+#ifndef WC_EXPORT
+#define WC_EXPORT __attribute__((export_name("wc_get_info")))
+#endif
+
+/* Helper for other exports */
+#define WC_EXPORT_INIT   __attribute__((export_name("wc_init")))
+#define WC_EXPORT_RENDER __attribute__((export_name("wc_render")))
+
+/* ── Audio sample type ────────────────────────────────────────────── */
+
+/*
+ * Default audio format is Float32 (WC_FLAG_AUDIO_F32 set automatically).
+ * Define WC_AUDIO_FORMAT_I16 before including this header to use int16
+ * ring buffers instead (legacy format).
+ */
+#ifdef WC_AUDIO_FORMAT_I16
+  #define _WC_AUDIO_SAMPLE_T int16_t
+#else
+  #define _WC_AUDIO_SAMPLE_T float
+#endif
+
+/* ── Standard cart buffer declarations ────────────────────────────── */
+
+/*
+ * Declares all the standard globals every cart needs.
+ * Uses DEFAULT_WIDTH, DEFAULT_HEIGHT, MAX_WIDTH, MAX_HEIGHT, AUDIO_CAP
+ * which must be #defined before this macro.
+ *
+ * Names match the convention used across all existing carts.
+ */
+#define WC_CART_BUFFERS                                           \
+    static uint32_t     wc_cur_width  = DEFAULT_WIDTH;            \
+    static uint32_t     wc_cur_height = DEFAULT_HEIGHT;           \
+    static uint32_t     wc_framebuffer[MAX_WIDTH * MAX_HEIGHT];   \
+    static _WC_AUDIO_SAMPLE_T wc_audio_ring[AUDIO_CAP * 2];      \
+    static uint32_t     wc_audio_write_cursor;                    \
+    static wc_pad_t     wc_pads[4];                               \
+    static wc_time_t    wc_time;                                  \
+    static wc_info_t    wc_info;                                  \
+    static wc_host_info_t wc_host_info;                           \
+    static wc_pointer_t wc_pointers[10];                          \
+    static uint8_t      wc_keys[32]
+
+/* ── Fill info struct ─────────────────────────────────────────────── */
+
+/*
+ * Fills the wc_info struct with standard field values.
+ * Call inside wc_get_info(). Pass flags like WC_FLAG_AUDIO_F32 or 0.
+ *
+ * For carts that don't use save data, save_ptr and save_size are set to 0.
+ * Override them after this macro if you need save support.
+ */
+#define WC_FILL_INFO(_wc_flags) do {                                \
+    wc_info.version       = WC_ABI_VERSION;                        \
+    wc_info.width         = DEFAULT_WIDTH;                         \
+    wc_info.height        = DEFAULT_HEIGHT;                        \
+    wc_info.fb_ptr        = (uint32_t)(uintptr_t)wc_framebuffer;  \
+    wc_info.audio_ptr     = (uint32_t)(uintptr_t)wc_audio_ring;   \
+    wc_info.audio_cap     = AUDIO_CAP;                             \
+    wc_info.audio_write_ptr = (uint32_t)(uintptr_t)&wc_audio_write_cursor; \
+    wc_info.input_ptr     = (uint32_t)(uintptr_t)wc_pads;         \
+    wc_info.save_ptr      = 0;                                     \
+    wc_info.save_size     = 0;                                     \
+    wc_info.time_ptr      = (uint32_t)(uintptr_t)&wc_time;        \
+    wc_info.host_info_ptr = (uint32_t)(uintptr_t)&wc_host_info;   \
+    wc_info.flags         = (_wc_flags)                            \
+        _WC_FILL_INFO_AUDIO_FLAG;                                  \
+    wc_info.audio_sample_rate = 0;  /* 0 = let host decide */     \
+    wc_info.pointer_ptr   = (uint32_t)(uintptr_t)wc_pointers;    \
+    wc_info.keys_ptr      = (uint32_t)(uintptr_t)wc_keys;        \
+} while (0)
+
+/* Auto-set WC_FLAG_AUDIO_F32 unless cart opts into legacy I16 */
+#ifdef WC_AUDIO_FORMAT_I16
+  #define _WC_FILL_INFO_AUDIO_FLAG
+#else
+  #define _WC_FILL_INFO_AUDIO_FLAG | WC_FLAG_AUDIO_F32
+#endif
+
+#endif /* WC_CART_H */