@downdraft/engine 0.2.0 → 0.3.1

package/libraries/entities/src/model-renderer.ts

@@ -86,9 +86,11 @@ export class ModelRenderer {
   private reusableUniformsU32 = new Uint32Array(this.reusableUniforms.buffer);
   private textureLoadVersion = new Map<string, number>();
 
-  // Skinning: a shared storage buffer of bone matrices (MAX_BONES * mat4),
-  // updated per-frame via updateSkinMatrices. Bound at @group(1) for skinned
-  // draws only.
+  // Skinning: a shared storage buffer of bone matrices (mat4 each), updated
+  // per-frame via updateSkinMatrices/updateSkinMatricesFor. Bound at @group(1)
+  // for skinned draws only. Each skinned nodeId owns a region of the buffer —
+  // the draw's `boneBase` uniform selects it so multiple skinned models can be
+  // animated independently in one frame.
   private skinMatrixBuffer: GPUBuffer | null = null;
   private skinBindGroupLayout: GPUBindGroupLayout | null = null;
   private skinBindGroup: GPUBindGroup | null = null;
@@ -96,6 +98,16 @@ export class ModelRenderer {
   private skinBindGroupSetThisFrame = false;
   /** Current bone capacity (number of mat4s the skin buffer can hold). Grows on demand. */
   private boneCapacity = ModelRenderer.INITIAL_BONE_CAPACITY;
+  /** nodeId → reserved bone region (offset+count in bones). */
+  private skinRegions = new Map<string, { offset: number; count: number }>();
+  /** nodeId → bone base index used by the skinning shader for that draw. */
+  private skinBaseByNode = new Map<string, number>();
+  /** Freed bone regions available for reuse (first-fit). */
+  private skinFreeList: Array<{ offset: number; count: number }> = [];
+  /** Next never-allocated bone index (high-water mark). */
+  private nextBoneOffset = 0;
+  /** Legacy caller region — updateSkinMatrices(m) without a nodeId. */
+  private static readonly DEFAULT_SKIN_NODE = "__skin_default";
 
   // Bindless deps
   private bindless: ModelRendererBindlessDeps | null = null;
@@ -822,6 +834,7 @@ export class ModelRenderer {
   }
 
   removeModel(nodeId: string): void {
+    this.releaseSkinRegion(nodeId);
     const resources = this.modelResources.get(nodeId);
     if (resources) {
       for (let i = 0; i < resources.length; i++) {
@@ -1082,43 +1095,85 @@ export class ModelRenderer {
   }
 
   /**
-   * Upload bone skin matrices for the current frame. The `matrices` buffer is
-   * a flat Float32Array of boneCount * 16 floats (column-major mat4s). It is
-   * copied into the shared skin matrix storage buffer. If the buffer is too
-   * small for the current skeleton, it is recreated (grown) automatically.
-   * Call once per frame before render() for skinned models.
+   * Upload bone skin matrices for the current frame into the shared default
+   * region. Kept for single-avatar callers — equivalent to
+   * updateSkinMatricesFor("__skin_default", matrices).
    */
   updateSkinMatrices(matrices: Float32Array): void {
+    this.updateSkinMatricesFor(ModelRenderer.DEFAULT_SKIN_NODE, matrices);
+  }
+
+  /**
+   * Upload bone skin matrices for one nodeId's reserved region. The region is
+   * (re)allocated automatically — freed regions from removeModel() are reused
+   * first-fit. Render() looks up the node's region offset and passes it to the
+   * skinning shader via the `boneBase` uniform, so multiple skinned models
+   * animate independently.
+   */
+  updateSkinMatricesFor(nodeId: string, matrices: Float32Array): void {
     if (!this.skinMatrixBuffer) return;
 
     const requiredBones = matrices.length / 16;
-    if (requiredBones > this.boneCapacity) {
-      // Grow the skin matrix buffer to fit the larger skeleton.
-      // Round up to the next power of 2 to reduce reallocations.
-      const newCapacity = Math.max(requiredBones, this.boneCapacity * 2);
-      this.skinMatrixBuffer.destroy();
-      this.skinMatrixBuffer = this.device.createBuffer({
-        size: newCapacity * 64,
-        usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
-      });
-      this.boneCapacity = newCapacity;
-      // Recreate the bind group with the new buffer
-      if (this.skinBindGroupLayout) {
-        this.skinBindGroup = this.device.createBindGroup({
-          layout: this.skinBindGroupLayout,
-          entries: [{ binding: 0, resource: { buffer: this.skinMatrixBuffer } }],
-        });
-      }
-      this.skinBindGroupSetThisFrame = false; // force re-bind
+    let region = this.skinRegions.get(nodeId);
+    if (!region || region.count < requiredBones) {
+      if (region) this.skinFreeList.push(region);
+      region = this.allocSkinRegion(requiredBones);
+      this.skinRegions.set(nodeId, region);
     }
+    this.skinBaseByNode.set(nodeId, region.offset);
 
     this.device.queue.writeBuffer(
       this.skinMatrixBuffer,
-      0,
+      region.offset * 64,
       matrices as Float32Array<ArrayBuffer>,
     );
   }
 
+  /** Allocate a bone region for `count` bones — free-list first, then bump
+   *  allocation; grows the shared buffer when the capacity is exceeded. */
+  private allocSkinRegion(count: number): { offset: number; count: number } {
+    for (let i = 0; i < this.skinFreeList.length; i++) {
+      const f = this.skinFreeList[i];
+      if (f.count >= count) {
+        this.skinFreeList.splice(i, 1);
+        return { offset: f.offset, count: f.count };
+      }
+    }
+    const needed = this.nextBoneOffset + count;
+    if (needed > this.boneCapacity) this.growSkinBuffer(needed);
+    const region = { offset: this.nextBoneOffset, count };
+    this.nextBoneOffset += count;
+    return region;
+  }
+
+  /** Recreate the skin matrix buffer at a larger capacity and rebind group(1).
+   *  Region offsets stay valid — callers rewrite their matrices next frame. */
+  private growSkinBuffer(minBones: number): void {
+    const newCapacity = Math.max(minBones, this.boneCapacity * 2);
+    this.skinMatrixBuffer?.destroy();
+    this.skinMatrixBuffer = this.device.createBuffer({
+      size: newCapacity * 64,
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+    });
+    this.boneCapacity = newCapacity;
+    if (this.skinBindGroupLayout) {
+      this.skinBindGroup = this.device.createBindGroup({
+        layout: this.skinBindGroupLayout,
+        entries: [{ binding: 0, resource: { buffer: this.skinMatrixBuffer } }],
+      });
+    }
+    this.skinBindGroupSetThisFrame = false; // force re-bind
+  }
+
+  /** Release a node's bone region back to the free list. */
+  releaseSkinRegion(nodeId: string): void {
+    const region = this.skinRegions.get(nodeId);
+    if (!region) return;
+    this.skinRegions.delete(nodeId);
+    this.skinBaseByNode.delete(nodeId);
+    this.skinFreeList.push(region);
+  }
+
   render(
     passEncoder: GPURenderPassEncoder,
     nodeId: string,
@@ -1221,6 +1276,12 @@ export class ModelRenderer {
       // fs_outline). Defaults: 0 width, black color.
       uniforms[39] = 0.0;
       uniforms[40] = 0.0; uniforms[41] = 0.0; uniforms[42] = 0.0;
+      // boneBase (u32, slot 44) — index of this node's bone region inside the
+      // shared skinMatrices storage buffer. Only read by vs_skinned.
+      this.reusableUniformsU32[44] =
+        this.skinBaseByNode.get(nodeId)
+        ?? this.skinBaseByNode.get(ModelRenderer.DEFAULT_SKIN_NODE)
+        ?? 0;
 
       this.device.queue.writeBuffer(
         this.uniformBuffer,

package/libraries/entities/src/shaders/model.wgsl

@@ -22,6 +22,14 @@ struct Uniforms {
   // Inverted-hull outline parameters (used by vs_outline / fs_outline only).
   outlineWidth: f32,
   outlineColor: vec3<f32>,
+  // Base index of this draw's bone region inside the shared skinMatrices
+  // storage buffer (group(1)). Written by ModelRenderer from the node's
+  // reserved region — lets multiple skinned models animate independently.
+  // Only read by vs_skinned.
+  boneBase: u32,
+  _padSkin0: u32,
+  _padSkin1: u32,
+  _padSkin2: u32,
 };
 
 @group(0) @binding(0) var<uniform> uniforms: Uniforms;
@@ -165,10 +173,11 @@ fn qrotate(q: vec4<f32>, v: vec3<f32>) -> vec3<f32> {
 // If all weights are zero (vertex has no bone assignment), return identity so
 // the vertex renders at its baked position instead of collapsing to the origin.
 fn skinMatrix(j: vec4<u32>, w: vec4<f32>) -> mat4x4<f32> {
-  let m = skinMatrices[j.x] * w.x
-        + skinMatrices[j.y] * w.y
-        + skinMatrices[j.z] * w.z
-        + skinMatrices[j.w] * w.w;
+  let base = uniforms.boneBase;
+  let m = skinMatrices[base + j.x] * w.x
+        + skinMatrices[base + j.y] * w.y
+        + skinMatrices[base + j.z] * w.z
+        + skinMatrices[base + j.w] * w.w;
   let wsum = w.x + w.y + w.z + w.w;
   if (wsum < 0.001) {
     return mat4x4<f32>(

package/libraries/networking/src/index.ts

@@ -43,3 +43,7 @@ export type { NetworkingLibConfig } from "./library";
 
 export { LanDiscovery, MdnsBrowser } from "./discovery";
 export type { LanBeacon, LanDiscoveryOptions, LanPeer, MdnsBrowseOptions, MdnsService } from "./discovery";
+
+export { createWebSocketServer } from "./ws-server";
+export type { WebSocketServerHandlers, WebSocketServerOptions, WsServer, WsServerConnection } from "./ws-server";
+

package/libraries/networking/src/ws-server.ts

@@ -0,0 +1,397 @@
+// ============================================================================
+// ws-server.ts — minimal tri-runtime WebSocket server for host-authoritative
+// LAN/WAN sessions. The networking library ships client transports
+// (WebSocketTransport, WebRTCTransport) but had no listener — this fills the
+// host side so a game instance can accept direct connections without any
+// external service.
+//
+// Runtime selection is capability-based (see platform/runtime.ts):
+//   Bun  → Bun.serve({ fetch, websocket })
+//   Deno → Deno.serve + Deno.upgradeWebSocket
+//   Node → node:http + a hand-rolled RFC6455 handshake/framer (pure JS,
+//          no native deps — also the fallback for any runtime with node:http)
+//
+// Semantics intentionally mirror the browser WebSocket surface: text frames
+// arrive as `string`, binary frames as `Uint8Array`. Ping/pong/close and
+// fragmented-frame reassembly are handled internally. Message cap matches
+// WebSocketTransport's 16 MiB.
+// ============================================================================
+
+import { createLogger } from "@downdraft/engine/util/logger";
+
+const log = createLogger();
+
+const WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+const MAX_MESSAGE_SIZE = 16 * 1024 * 1024;
+
+/** One accepted client connection on a {@link WsServer}. */
+export interface WsServerConnection {
+  /** Server-assigned connection id (monotonic per server). */
+  readonly id: number;
+  /** Remote peer "ip:port" or best-effort address string. */
+  readonly remoteAddress: string;
+  /** Send a text (string) or binary (Uint8Array/ArrayBuffer) frame. */
+  send(data: string | Uint8Array | ArrayBuffer): void;
+  /** Initiate the close handshake (default code 1000). */
+  close(code?: number, reason?: string): void;
+}
+
+export interface WebSocketServerHandlers {
+  /** A client completed the WS handshake. */
+  onConnection?(conn: WsServerConnection): void;
+  /** A complete (reassembled) message arrived. */
+  onMessage?(conn: WsServerConnection, data: Uint8Array | string): void;
+  /** The connection closed (cleanly or via error/timeout). */
+  onClose?(conn: WsServerConnection, code: number, reason: string): void;
+}
+
+export interface WebSocketServerOptions extends WebSocketServerHandlers {
+  /** TCP port to listen on. 0 = ephemeral (read `server.port` after start). */
+  port: number;
+  /** Bind address — default "0.0.0.0" (all interfaces, for LAN/WAN). */
+  host?: string;
+}
+
+export interface WsServer {
+  /** The port actually bound (differs from opts.port when 0 was passed). */
+  readonly port: number;
+  /** The bound hostname. */
+  readonly host: string;
+  /** All currently-open connections. */
+  connections(): WsServerConnection[];
+  /** Stop listening and close every connection. */
+  close(): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Shared plumbing
+// ---------------------------------------------------------------------------
+
+interface InternalConn extends WsServerConnection {
+  /** Runtime-specific raw socket/sendable handle. */
+  raw: unknown;
+}
+
+function makeServerBase(handlers: WebSocketServerHandlers) {
+  const conns = new Set<InternalConn>();
+  let nextId = 1;
+
+  const deliver = (conn: InternalConn, data: Uint8Array | string) => {
+    const size = typeof data === "string" ? data.length : data.byteLength;
+    if (size > MAX_MESSAGE_SIZE) { conn.close(1009, "message too large"); return; }
+    try { handlers.onMessage?.(conn, data); } catch (e) { log.error("WsServer", `onMessage threw: ${e}`); }
+  };
+
+  const drop = (conn: InternalConn, code: number, reason: string) => {
+    if (!conns.delete(conn)) return;
+    try { handlers.onClose?.(conn, code, reason); } catch (e) { log.error("WsServer", `onClose threw: ${e}`); }
+  };
+
+  return { conns, nextId: () => nextId++, deliver, drop };
+}
+
+// ---------------------------------------------------------------------------
+// Bun — Bun.serve with the `websocket` handler map
+// ---------------------------------------------------------------------------
+
+function startBunServer(opts: WebSocketServerOptions): Promise<WsServer> {
+  const Bun = (globalThis as any).Bun;
+  const base = makeServerBase(opts);
+
+  const server = (Bun.serve as (o: unknown) => { port: number; stop(force?: boolean): Promise<void> })({
+    port: opts.port,
+    hostname: opts.host ?? "0.0.0.0",
+    fetch(req: Request, srv: any) {
+      const ip = srv.requestIP(req);
+      const conn: InternalConn = {
+        id: base.nextId(),
+        remoteAddress: `${ip?.address ?? "?"}:${ip?.port ?? "?"}`,
+        raw: null,
+        send(data: string | Uint8Array | ArrayBuffer) { if (this.raw) (this.raw as any).send(data instanceof ArrayBuffer ? new Uint8Array(data) : data as never); },
+        close(code = 1000, reason = "") { if (this.raw) (this.raw as any).close(code, reason); },
+      };
+      return srv.upgrade(req, { data: { conn } }) ? undefined : new Response("WebSocket upgrade required", { status: 426 });
+    },
+    websocket: {
+      open(ws: any) {
+        const conn = ws.data.conn as InternalConn;
+        conn.raw = ws;
+        base.conns.add(conn);
+        try { opts.onConnection?.(conn); } catch (e) { log.error("WsServer", `onConnection threw: ${e}`); }
+      },
+      message(ws: any, msg: string | ArrayBuffer | Uint8Array) {
+        const conn = ws.data.conn as InternalConn;
+        base.deliver(conn, typeof msg === "string" ? msg : new Uint8Array(msg as ArrayBufferLike));
+      },
+      close(ws: any, code: number, reason: string) {
+        base.drop(ws.data.conn as InternalConn, code, reason);
+      },
+    },
+  });
+
+  return Promise.resolve({
+    port: server.port as number,
+    host: opts.host ?? "0.0.0.0",
+    connections: () => [...base.conns],
+    async close() {
+      [...base.conns].forEach((c) => c.close(1001, "server shutdown"));
+      await server.stop(true);
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Deno — Deno.serve + Deno.upgradeWebSocket
+// ---------------------------------------------------------------------------
+
+function startDenoServer(opts: WebSocketServerOptions): Promise<WsServer> {
+  const Deno = (globalThis as any).Deno;
+  const base = makeServerBase(opts);
+
+  const server = Deno.serve(
+    { port: opts.port, hostname: opts.host ?? "0.0.0.0" },
+    (req: Request, info: { remoteAddr?: { hostname: string; port: number } }) => {
+      if (req.headers.get("upgrade")?.toLowerCase() !== "websocket") {
+        return new Response("WebSocket upgrade required", { status: 426 });
+      }
+      const { socket, response } = Deno.upgradeWebSocket(req);
+      const conn: InternalConn = {
+        id: base.nextId(),
+        remoteAddress: info?.remoteAddr ? `${info.remoteAddr.hostname}:${info.remoteAddr.port}` : "?",
+        raw: socket,
+        send(data: string | Uint8Array | ArrayBuffer) { try { socket.send(data as never); } catch { /* closing */ } },
+        close(code = 1000, reason = "") { try { socket.close(code, reason); } catch { /* already closed */ } },
+      };
+      socket.binaryType = "arraybuffer";
+      socket.onopen = () => {
+        base.conns.add(conn);
+        try { opts.onConnection?.(conn); } catch (e) { log.error("WsServer", `onConnection threw: ${e}`); }
+      };
+      socket.onmessage = (e: MessageEvent) => {
+        base.deliver(conn, typeof e.data === "string" ? e.data : new Uint8Array(e.data as ArrayBuffer));
+      };
+      socket.onclose = (e: CloseEvent) => base.drop(conn, e.code, e.reason);
+      socket.onerror = () => base.drop(conn, 1006, "socket error");
+      return response;
+    },
+  );
+
+  const bound = server.addr as { port: number; hostname: string };
+  return Promise.resolve({
+    port: bound.port,
+    host: bound.hostname,
+    connections: () => [...base.conns],
+    async close() {
+      [...base.conns].forEach((c) => c.close(1001, "server shutdown"));
+      await server.shutdown();
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Node (and generic fallback) — node:http + hand-rolled RFC6455
+// ---------------------------------------------------------------------------
+
+/** Encode one server→client frame. Server frames are never masked. */
+function encodeWsFrame(opcode: number, payload: Uint8Array): Uint8Array {
+  const len = payload.byteLength;
+  let header: Uint8Array;
+  if (len < 126) {
+    header = new Uint8Array(2);
+    header[1] = len;
+  } else if (len <= 0xffff) {
+    header = new Uint8Array(4);
+    header[1] = 126;
+    header[2] = len >>> 8; header[3] = len & 0xff;
+  } else {
+    header = new Uint8Array(10);
+    header[1] = 127;
+    const dv = new DataView(header.buffer);
+    dv.setUint32(2, Math.floor(len / 0x100000000));
+    dv.setUint32(6, len >>> 0);
+  }
+  header[0] = 0x80 | (opcode & 0x0f);
+  const out = new Uint8Array(header.length + len);
+  out.set(header, 0);
+  out.set(payload, header.length);
+  return out;
+}
+
+const OP_CONT = 0x0, OP_TEXT = 0x1, OP_BIN = 0x2, OP_CLOSE = 0x8, OP_PING = 0x9, OP_PONG = 0xa;
+
+async function startNodeServer(opts: WebSocketServerOptions): Promise<WsServer> {
+  const http = await import("node:http");
+  const crypto = await import("node:crypto");
+  const base = makeServerBase(opts);
+
+  const httpServer = http.createServer((_req, res) => {
+    res.writeHead(426, { "Content-Type": "text/plain" });
+    res.end("WebSocket upgrade required");
+  });
+
+  httpServer.on("upgrade", (req: import("node:http").IncomingMessage, socket: import("node:net").Socket) => {
+    socket.setNoDelay(true);
+    const key = req.headers["sec-websocket-key"];
+    const upgrade = req.headers.upgrade?.toLowerCase();
+    if (upgrade !== "websocket" || typeof key !== "string") {
+      socket.write("HTTP/1.1 400 Bad Request\r\n\r\n");
+      socket.destroy();
+      return;
+    }
+    const accept = crypto.createHash("sha1").update(key + WS_GUID).digest("base64");
+    socket.write(
+      "HTTP/1.1 101 Switching Protocols\r\n" +
+      "Upgrade: websocket\r\n" +
+      "Connection: Upgrade\r\n" +
+      `Sec-WebSocket-Accept: ${accept}\r\n\r\n`,
+    );
+
+    let closed = false;
+    const conn: InternalConn = {
+      id: base.nextId(),
+      remoteAddress: `${socket.remoteAddress ?? "?"}:${socket.remotePort ?? "?"}`,
+      raw: socket,
+      send(data: string | Uint8Array | ArrayBuffer) {
+        if (closed || socket.destroyed) return;
+        if (typeof data === "string") {
+          socket.write(Buffer.from(encodeWsFrame(OP_TEXT, Buffer.from(data, "utf8"))));
+        } else {
+          const bytes = data instanceof ArrayBuffer ? new Uint8Array(data) : data;
+          socket.write(Buffer.from(encodeWsFrame(OP_BIN, bytes)));
+        }
+      },
+      close(code = 1000, reason = "") {
+        if (closed) return;
+        closed = true;
+        const payload = new Uint8Array(2 + reason.length);
+        payload[0] = code >>> 8; payload[1] = code & 0xff;
+        payload.set(new TextEncoder().encode(reason), 2);
+        try {
+          socket.write(Buffer.from(encodeWsFrame(OP_CLOSE, payload)));
+          socket.end();
+        } catch { /* socket already gone */ }
+      },
+    };
+
+    // ── Incremental frame parser ──
+    let buf: Buffer = Buffer.alloc(0) as Buffer;
+    let fragOp = -1;
+    const frags: Buffer[] = [];
+
+    const finishMessage = (op: number, payload: Buffer) => {
+      if (payload.byteLength > MAX_MESSAGE_SIZE) { conn.close(1009, "message too large"); return; }
+      if (op === OP_TEXT) base.deliver(conn, payload.toString("utf8"));
+      else base.deliver(conn, new Uint8Array(payload.buffer, payload.byteOffset, payload.byteLength));
+    };
+
+    const handleFrame = (fin: boolean, op: number, payload: Buffer) => {
+      if (op === OP_CLOSE) {
+        const code = payload.byteLength >= 2 ? payload.readUInt16BE(0) : 1000;
+        const reason = payload.byteLength > 2 ? payload.subarray(2).toString("utf8") : "";
+        conn.close(code, reason);
+        base.drop(conn, code, reason);
+        return;
+      }
+      if (op === OP_PING) { if (!closed && !socket.destroyed) socket.write(Buffer.from(encodeWsFrame(OP_PONG, payload))); return; }
+      if (op === OP_PONG) return;
+      if (op === OP_CONT && fragOp < 0) { conn.close(1002, "unexpected continuation"); return; }
+      if ((op === OP_TEXT || op === OP_BIN) && fragOp >= 0) { conn.close(1002, "interleaved frame"); return; }
+
+      if (op !== OP_CONT) fragOp = op;
+      frags.push(payload);
+      if (!fin) return;
+      const full = Buffer.concat(frags);
+      frags.length = 0;
+      const finalOp = fragOp;
+      fragOp = -1;
+      finishMessage(finalOp, full);
+    };
+
+    socket.on("data", (chunk: Buffer) => {
+      buf = buf.byteLength ? Buffer.concat([buf, chunk]) : chunk;
+      // Parse as many complete frames as the buffer holds.
+      for (;;) {
+        if (buf.byteLength < 2) return;
+        const b0 = buf[0], b1 = buf[1];
+        const fin = (b0 & 0x80) !== 0;
+        const op = b0 & 0x0f;
+        const masked = (b1 & 0x80) !== 0;
+        let len = b1 & 0x7f;
+        let off = 2;
+        if (len === 126) {
+          if (buf.byteLength < off + 2) return;
+          len = buf.readUInt16BE(off); off += 2;
+        } else if (len === 127) {
+          if (buf.byteLength < off + 8) return;
+          const hi = buf.readUInt32BE(off), lo = buf.readUInt32BE(off + 4); off += 8;
+          if (hi > 0 || lo > MAX_MESSAGE_SIZE) { conn.close(1009, "message too large"); return; }
+          len = lo;
+        }
+        const maskLen = masked ? 4 : 0;
+        if (buf.byteLength < off + maskLen + len) return;
+        let payload = buf.subarray(off + maskLen, off + maskLen + len);
+        if (masked) {
+          const mask = buf.subarray(off, off + 4);
+          const unmasked = Buffer.allocUnsafe(payload.byteLength);
+          for (let i = 0; i < payload.byteLength; i++) unmasked[i] = payload[i] ^ mask[i & 3];
+          payload = unmasked;
+        } else {
+          payload = Buffer.from(payload); // detach — subarray aliases buf
+        }
+        buf = buf.subarray(off + maskLen + len);
+        handleFrame(fin, op, payload);
+        if (closed) return;
+      }
+    });
+
+    const onSocketEnd = () => base.drop(conn, 1006, "socket closed");
+    socket.on("close", onSocketEnd);
+    socket.on("error", onSocketEnd);
+
+    base.conns.add(conn);
+    try { opts.onConnection?.(conn); } catch (e) { log.error("WsServer", `onConnection threw: ${e}`); }
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    httpServer.once("error", reject);
+    httpServer.listen(opts.port, opts.host ?? "0.0.0.0", () => {
+      httpServer.removeListener("error", reject);
+      resolve();
+    });
+  });
+
+  const addr = httpServer.address();
+  const boundPort = typeof addr === "object" && addr ? addr.port : opts.port;
+
+  return {
+    port: boundPort,
+    host: opts.host ?? "0.0.0.0",
+    connections: () => [...base.conns],
+    async close() {
+      [...base.conns].forEach((c) => c.close(1001, "server shutdown"));
+      await new Promise<void>((resolve) => httpServer.close(() => resolve()));
+      // httpServer.close waits for open sockets; force-destroy stragglers.
+      [...base.conns].forEach((c) => (c.raw as import("node:net").Socket).destroy());
+      base.conns.clear();
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Start a WebSocket server. Resolves once the socket is bound and listening.
+ * Runtime is picked by capability: Bun.serve → Deno.serve → node:http.
+ */
+export function createWebSocketServer(opts: WebSocketServerOptions): Promise<WsServer> {
+  const g = globalThis as Record<string, unknown>;
+  const bun = g.Bun as { serve?: unknown } | undefined;
+  if (typeof bun?.serve === "function") return startBunServer(opts);
+  const deno = g.Deno as { serve?: unknown; upgradeWebSocket?: unknown } | undefined;
+  if (typeof deno?.serve === "function" && typeof deno.upgradeWebSocket === "function") {
+    return startDenoServer(opts);
+  }
+  return startNodeServer(opts);
+}

package/libraries/physics-rapier/src/api.ts

@@ -298,6 +298,21 @@ export class UniversalPhysicsAPI {
     this.backend.setIntegrationDt(realmId, dt);
   }
 
+  /**
+   * Change gravity across all realms (applies to near/mid/far). Best-effort:
+   * backends that can't mutate realm gravity omit `setRealmGravity`, in which
+   * case callers should fall back to per-body `gravityScale` in BodyDesc.
+   */
+  setGravity(gravity: [number, number, number]): void {
+    [RealmTier.Near, RealmTier.Mid, RealmTier.Far].forEach((tier) => {
+      try {
+        const realm = this.realmManager.getRealm(tier);
+        this.backend.setRealmGravity?.(realm.id, gravity);
+      } catch { /* realm tier not initialized */ }
+    });
+    this.config.gravity = gravity;
+  }
+
   // --- Realm ---
 
   getRealmTier(body: PhysicsBody): RealmTier {

package/libraries/physics-rapier/src/backend.ts

@@ -472,6 +472,21 @@ export class RapierPhysicsBackend implements PhysicsBackend {
     }
   }
 
+  /**
+   * Change a live realm's gravity. Updates the stored realm config (the
+   * no-lib JS fallback stepper reads it) and forwards to the lib when it
+   * supports runtime gravity (the WASM Rapier world.gravity is mutable; the
+   * native FFI lib may not implement it — callers should treat this as
+   * best-effort).
+   */
+  setRealmGravity(realmId: number, gravity: [number, number, number]): void {
+    const realm = this.realms.get(realmId);
+    if (realm) realm.config.gravity = gravity;
+    if (this.lib && this.lib.setRealmGravity) {
+      this.lib.setRealmGravity(realmId, gravity);
+    }
+  }
+
   setSleepThresholds(realmId: number, linearThreshold: number, angularThreshold: number): void {
     if (this.lib) {
       this.lib.setSleepThresholds(realmId, linearThreshold, angularThreshold);

package/libraries/physics-rapier/src/rapier-backend.ts

@@ -7,6 +7,8 @@ const log = createLogger();
 export interface PhysicsLib {
   createRealm(id: number, gravity: [number, number, number]): void;
   destroyRealm(id: number): void;
+  /** Change a live realm's gravity (Rapier `world.gravity` is mutable). */
+  setRealmGravity?(realmId: number, gravity: [number, number, number]): void;
   createBody(realmId: number, bodyId: number, desc: BodyDesc, entity: Entity): void;
   destroyBody(realmId: number, bodyId: number): void;
   setBodyType(realmId: number, bodyId: number, type: BodyType): void;
@@ -251,6 +253,10 @@ async function doLoadPhysicsLib(): Promise<PhysicsLib> {
         entityByBodyHandle.delete(id);
         bodyIdByHandle.delete(id);
       },
+      setRealmGravity(id, gravity) {
+        const world = realms.get(id);
+        if (world) world.gravity = { x: gravity[0], y: gravity[1], z: gravity[2] };
+      },
       createBody(realmId, bodyId, desc, entity) {
         const world = realms.get(realmId);
         if (!world) return;

package/libraries/postfx/src/post-process-stack.ts

@@ -546,8 +546,7 @@ export class PostProcessStack {
   private createGlyphAtlas(): void {
     const chars = " .:-=+*#%@";
     const gw = 16, gh = 16, cols = chars.length;
-    const canvas = document.createElement("canvas");
-    canvas.width = cols * gw; canvas.height = gh;
+    const canvas = new OffscreenCanvas(cols * gw, gh);
     const ctx = canvas.getContext("2d")!;
     ctx.fillStyle = "black"; ctx.fillRect(0, 0, canvas.width, canvas.height);
     ctx.fillStyle = "white"; ctx.font = `bold ${gh - 2}px monospace`;