@bloopjs/bloop 0.0.13 → 0.0.14

package/src/runtime.ts

@@ -0,0 +1,273 @@
+import {
+  DEFAULT_WASM_URL,
+  type EnginePointer,
+  type Key,
+  keyToKeyCode,
+  type MouseButton,
+  mouseButtonToMouseButtonCode,
+  SNAPSHOT_HEADER_ENGINE_LEN_OFFSET,
+  SNAPSHOT_HEADER_LEN,
+  SNAPSHOT_HEADER_USER_LEN_OFFSET,
+  TimeContext,
+  type WasmEngine,
+} from "@bloopjs/engine";
+import { assert } from "./util";
+
+export type MountOpts = {
+  wasmUrl?: URL;
+  /**
+   * A callback function to run logic for a given frame
+   */
+  systemsCallback: (system_handle: number, ptr: EnginePointer) => void;
+
+  /**
+   * Sets buffer to the latest engine memory buffer
+   *
+   * Note that if the engine wasm memory grows, all dataviews into the memory must be updated
+   */
+  setBuffer: (buffer: ArrayBuffer) => void;
+
+  /**
+   * Whether to start recording immediately upon mount
+   * Defaults to true
+   */
+  startRecording?: boolean;
+
+  /**
+   * Optional hook to serialize some data when snapshotting
+   */
+  serialize?: SerializeFn;
+
+  /**
+   * Optional hook to deserialize some data when restoring
+   */
+  deserialize?: DeserializeFn;
+};
+
+export type SerializeFn = () => {
+  size: number;
+  write(buffer: ArrayBufferLike, ptr: EnginePointer): void;
+};
+
+export type DeserializeFn = (
+  buffer: ArrayBufferLike,
+  ptr: EnginePointer,
+  size: number,
+) => void;
+
+/**
+ * The runtime is a portable runtime that is responsible for:
+ *
+ * * Moving the engine forward and backward in time
+ * * Maintaining a js-friendly view of engine memory
+ */
+export class Runtime {
+  wasm: WasmEngine;
+  #memory: WebAssembly.Memory;
+  #time: TimeContext;
+  #serialize?: SerializeFn;
+  constructor(
+    wasm: WasmEngine,
+    memory: WebAssembly.Memory,
+    opts?: { serialize?: SerializeFn },
+  ) {
+    this.wasm = wasm;
+    this.#memory = memory;
+    this.#time = new TimeContext(
+      new DataView(this.#memory.buffer, this.wasm.get_time_ctx()),
+    );
+    this.#serialize = opts?.serialize;
+  }
+
+  step(ms?: number) {
+    this.wasm.step(ms ?? 16);
+  }
+
+  stepBack() {
+    if (this.time.frame === 0) {
+      return;
+    }
+    this.seek(this.time.frame - 1);
+  }
+
+  seek(frame: number) {
+    assert(
+      this.hasHistory,
+      "Not recording or playing back, can't seek to frame",
+    );
+    this.wasm.seek(frame);
+  }
+
+  record() {
+    const serializer = this.#serialize ? this.#serialize() : null;
+    const size = serializer ? serializer.size : 0;
+    this.wasm.start_recording(size, 1024);
+  }
+
+  snapshot(): Uint8Array<ArrayBuffer> {
+    const serializer = this.#serialize ? this.#serialize() : null;
+    const size = serializer ? serializer.size : 0;
+
+    const ptr = this.wasm.take_snapshot(size);
+    const header = new Uint32Array(this.#memory.buffer, ptr, 4);
+    const userLenIndex =
+      SNAPSHOT_HEADER_USER_LEN_OFFSET / Uint32Array.BYTES_PER_ELEMENT;
+    const engineLenIndex =
+      SNAPSHOT_HEADER_ENGINE_LEN_OFFSET / Uint32Array.BYTES_PER_ELEMENT;
+    assert(header[userLenIndex], `header user length missing`);
+    assert(header[engineLenIndex], `header engine length missing`);
+    const length = header[userLenIndex] + header[engineLenIndex];
+    const memoryView = new Uint8Array(this.#memory.buffer, ptr, length);
+
+    const copy = new Uint8Array(length);
+    copy.set(memoryView);
+
+    return copy;
+  }
+
+  restore(snapshot: Uint8Array) {
+    const dataPtr = this.wasm.alloc(snapshot.byteLength);
+    assert(
+      dataPtr > 0,
+      `failed to allocate ${snapshot.byteLength} bytes for snapshot restore, pointer=${dataPtr}`,
+    );
+
+    // copy snapshot into wasm memory
+    const memoryView = new Uint8Array(
+      this.#memory.buffer,
+      dataPtr,
+      snapshot.byteLength,
+    );
+    memoryView.set(snapshot);
+
+    // restore the snapshot
+    this.wasm.restore(dataPtr);
+
+    // free the allocated memory
+    this.wasm.free(dataPtr, snapshot.byteLength);
+  }
+
+  get time(): TimeContext {
+    if (
+      !this.#time.dataView ||
+      this.#time.dataView.buffer !== this.#memory.buffer
+    ) {
+      // update the data view to the latest memory buffer
+      this.#time.dataView = new DataView(
+        this.#memory.buffer,
+        this.wasm.get_time_ctx(),
+      );
+    }
+    return this.#time;
+  }
+
+  get buffer(): ArrayBuffer {
+    return this.#memory.buffer;
+  }
+
+  get isRecording(): boolean {
+    return this.wasm.is_recording();
+  }
+
+  get isReplaying(): boolean {
+    return this.wasm.is_replaying();
+  }
+
+  get hasHistory(): boolean {
+    return this.isRecording || this.isReplaying;
+  }
+
+  emit = {
+    keydown: (key: Key): void => {
+      this.wasm.emit_keydown(keyToKeyCode(key));
+    },
+    keyup: (key: Key): void => {
+      this.wasm.emit_keyup(keyToKeyCode(key));
+    },
+    mousemove: (x: number, y: number): void => {
+      this.wasm.emit_mousemove(x, y);
+    },
+    mousedown: (button: MouseButton): void => {
+      this.wasm.emit_mousedown(mouseButtonToMouseButtonCode(button));
+    },
+    mouseup: (button: MouseButton): void => {
+      this.wasm.emit_mouseup(mouseButtonToMouseButtonCode(button));
+    },
+    mousewheel: (x: number, y: number): void => {
+      this.wasm.emit_mousewheel(x, y);
+    },
+  };
+}
+
+export type MountResult = {
+  runtime: Runtime;
+  wasm: WasmEngine;
+};
+
+export async function mount(opts: MountOpts): Promise<MountResult> {
+  if (
+    (opts.serialize && !opts.deserialize) ||
+    (!opts.serialize && opts.deserialize)
+  ) {
+    throw new Error("Snapshot and restore hooks must be provided together");
+  }
+
+  // https://github.com/oven-sh/bun/issues/12434
+  const bytes = await Bun.file(opts.wasmUrl ?? DEFAULT_WASM_URL).arrayBuffer();
+
+  // 1mb to 64mb
+  // use bun check:wasm to find initial memory page size
+  const memory = new WebAssembly.Memory({ initial: 17, maximum: 1000 });
+  const wasmInstantiatedSource = await WebAssembly.instantiate(bytes, {
+    env: {
+      memory,
+      __cb: function (system_handle: number, ptr: number) {
+        opts.setBuffer(memory.buffer);
+        opts.systemsCallback(system_handle, ptr);
+      },
+      console_log: function (ptr: EnginePointer, len: number) {
+        const bytes = new Uint8Array(memory.buffer, ptr, len);
+        const string = new TextDecoder("utf-8").decode(bytes);
+        console.log(string);
+      },
+      user_data_len: function () {
+        const serializer = opts.serialize ? opts.serialize() : null;
+        return serializer ? serializer.size : 0;
+      },
+      user_data_serialize: function (ptr: EnginePointer, len: number) {
+        if (!opts.serialize) {
+          return;
+        }
+        const serializer = opts.serialize();
+        if (len !== serializer.size) {
+          throw new Error(
+            `user_data_write length mismatch, expected=${serializer.size} got=${len}`,
+          );
+        }
+        serializer.write(memory.buffer, ptr);
+      },
+      user_data_deserialize: function (ptr: EnginePointer, len: number) {
+        if (!opts.deserialize) {
+          return;
+        }
+        opts.deserialize(memory.buffer, ptr, len);
+      },
+    },
+  });
+  const wasm = wasmInstantiatedSource.instance.exports as WasmEngine;
+
+  wasm.initialize();
+
+  const runtime = new Runtime(wasm, memory, {
+    serialize: opts.serialize,
+  });
+
+  if (opts.startRecording ?? true) {
+    runtime.record();
+  }
+
+  return {
+    runtime,
+    wasm,
+  };
+}

package/src/system.ts

@@ -1,11 +1,11 @@
+import type { Context } from "./context";
+import type { BloopSchema } from "./data/schema";
 import type {
   KeyEvent,
   MouseButtonEvent,
-  MousePositionEvent,
+  MouseMoveEvent,
   MouseWheelEvent,
-} from "@bloopjs/engine";
-import type { Context } from "./context";
-import type { BloopSchema } from "./data/schema";
+} from "./events";
 
 export type System<GS extends BloopSchema = BloopSchema> = {
   label?: string;
@@ -38,7 +38,7 @@ export type System<GS extends BloopSchema = BloopSchema> = {
 
   mousemove?: (
     context: Context<GS> & {
-      event: MousePositionEvent;
+      event: MouseMoveEvent;
     },
   ) => void;
 

package/src/util.ts

@@ -0,0 +1,23 @@
+export function toHexString(dataView: DataView, length?: number): string {
+  length ??= dataView.byteLength;
+  let hexString = "";
+  for (let i = 0; i < length; i++) {
+    const byte = dataView.getUint8(i);
+    hexString += `${byte.toString(16).padStart(2, "0")} `;
+  }
+  return hexString.trim();
+}
+
+export function assert(condition: any, message?: string): asserts condition {
+  if (condition == null || condition === false) {
+    throw new Error(message ?? "Assertion failed");
+  }
+}
+
+export function unwrap<T>(
+  value: T | null | undefined,
+  message?: string,
+): NonNullable<T> {
+  assert(value != null, message ?? `Unwrap failed: value is ${value}`);
+  return value;
+}

package/test/inputs.test.ts

@@ -1,8 +1,9 @@
-import { it, expect, describe } from "bun:test";
-import { mount, type Key, type MouseButton } from "@bloopjs/engine";
-import { Bloop } from "../src/mod";
+import { describe, expect, it } from "bun:test";
+import type { Key, MouseButton } from "@bloopjs/engine";
+import { Bloop } from "../src/bloop";
+import { mount } from "../src/runtime";
 
-describe("loop", () => {
+describe("inputs", () => {
   it("runs a single system", async () => {
     const bloop = Bloop.create();
     let count = 0;
@@ -19,7 +20,26 @@ describe("loop", () => {
     expect(count).toEqual(1);
   });
 
-  it("passes through input events", async () => {
+  it("routes keydown event", async () => {
+    const bloop = Bloop.create();
+    let receivedKey: Key | null = null;
+    let called = false;
+    bloop.system("input", {
+      keydown({ event }) {
+        receivedKey = event.key;
+        called = true;
+      },
+    });
+
+    const { runtime } = await mount(bloop);
+    runtime.emit.keydown("Space");
+    runtime.step();
+
+    expect(called).toBe(true);
+    expect(receivedKey!).toEqual("Space");
+  });
+
+  it("routes all input events", async () => {
     const bloop = Bloop.create();
 
     const events = {
@@ -53,12 +73,12 @@ describe("loop", () => {
       },
     });
 
-    const { runtime, emitter } = await mount(bloop);
+    const { runtime } = await mount(bloop);
 
-    emitter.keydown("Space");
-    emitter.mousemove(100, 150);
-    emitter.mousedown("Left");
-    emitter.mousewheel(1, 2);
+    runtime.emit.keydown("Space");
+    runtime.emit.mousedown("Left");
+    runtime.emit.mousemove(100, 150);
+    runtime.emit.mousewheel(1, 2);
 
     runtime.step();
 
@@ -67,9 +87,9 @@ describe("loop", () => {
     expect(events.mousedown).toEqual("Left");
     expect(events.mousewheel).toEqual({ x: 1, y: 2 });
 
-    emitter.keyup("Space");
-    emitter.mouseup("Left");
-    emitter.mousemove(3, 4);
+    runtime.emit.keyup("Space");
+    runtime.emit.mouseup("Left");
+    runtime.emit.mousemove(3, 4);
 
     runtime.step();
 
@@ -78,82 +98,127 @@ describe("loop", () => {
     expect(events.mousemove).toEqual({ x: 3, y: 4 });
   });
 
-  it("keeps track of keyboard and mouse snapshots", async () => {
+  it("exposes keyboard context", async () => {
     const bloop = Bloop.create({
       bag: {
-        cool: "nice",
+        down: null as boolean | null,
+        held: null as boolean | null,
+        up: null as boolean | null,
       },
     });
 
-    const events = {
-      keydown: null as boolean | null,
-      keyheld: null as boolean | null,
-      keyup: null as boolean | null,
-      mouseheld: null as boolean | null,
-      mousedown: null as boolean | null,
-      mouseup: null as boolean | null,
-    };
-
-    bloop.system("input snapshots", {
-      update({ inputs }) {
-        events.keydown = inputs.keys.space.down;
-        events.keyheld = inputs.keys.space.held;
-        events.keyup = inputs.keys.space.up;
-
-        events.mousedown = inputs.mouse.left.down;
-        events.mouseheld = inputs.mouse.left.held;
-        events.mouseup = inputs.mouse.left.up;
+    bloop.system("key state", {
+      update({ inputs, bag }) {
+        bag.down = inputs.keys.backquote.down;
+        bag.held = inputs.keys.backquote.held;
+        bag.up = inputs.keys.backquote.up;
       },
     });
 
-    const { runtime, emitter } = await mount(bloop);
+    const { runtime } = await mount(bloop);
 
     // Initial state
     runtime.step();
-    expect(events).toEqual({
-      keydown: false,
-      keyheld: false,
-      keyup: false,
-      mousedown: false,
-      mouseheld: false,
-      mouseup: false,
+    expect(bloop.bag).toEqual({
+      down: false,
+      held: false,
+      up: false,
     });
 
     // down and held are both true on the first frame of a key down
-    emitter.keydown("Space");
-    emitter.mousedown("Left");
+    runtime.emit.keydown("Backquote");
     runtime.step();
-    expect(events).toEqual({
-      keydown: true,
-      keyheld: true,
-      keyup: false,
-      mousedown: true,
-      mouseheld: true,
-      mouseup: false,
+    expect(bloop.bag).toEqual({
+      down: true,
+      held: true,
+      up: false,
     });
 
     // held remains true, down goes false
     runtime.step();
-    expect(events).toEqual({
-      keydown: false,
-      keyheld: true,
-      keyup: false,
-      mousedown: false,
-      mouseheld: true,
-      mouseup: false,
+    expect(bloop.bag).toEqual({
+      down: false,
+      held: true,
+      up: false,
     });
 
     // on key up, up is true, held and down are false
-    emitter.keyup("Space");
-    emitter.mouseup("Left");
+    runtime.emit.keyup("Backquote");
+    runtime.step();
+    expect(bloop.bag).toEqual({
+      down: false,
+      held: false,
+      up: true,
+    });
+  });
+
+  it("exposes mouse context", async () => {
+    const bloop = Bloop.create({
+      bag: {
+        down: null as boolean | null,
+        held: null as boolean | null,
+        up: null as boolean | null,
+        position: null as { x: number; y: number } | null,
+        wheel: null as { x: number; y: number } | null,
+      },
+    });
+
+    bloop.system("mouse state", {
+      update({ inputs, bag }) {
+        bag.down = inputs.mouse.left.down;
+        bag.held = inputs.mouse.left.held;
+        bag.up = inputs.mouse.left.up;
+        bag.position = { x: inputs.mouse.x, y: inputs.mouse.y };
+        bag.wheel = inputs.mouse.wheel;
+      },
+    });
+
+    const { runtime } = await mount(bloop);
+
+    // Initial state
+    runtime.step();
+    expect(bloop.bag).toEqual({
+      down: false,
+      held: false,
+      up: false,
+      position: { x: 0, y: 0 },
+      wheel: { x: 0, y: 0 },
+    });
+
+    // down and held are both true on the first frame of a key down
+    runtime.emit.mousedown("Left");
+    runtime.step();
+    expect(bloop.bag).toMatchObject({
+      down: true,
+      held: true,
+      up: false,
+    });
+
+    runtime.emit.mousemove(123, 456);
+    runtime.step();
+    expect(bloop.bag).toMatchObject({
+      down: false,
+      held: true,
+      up: false,
+      position: { x: 123, y: 456 },
+    });
+
+    runtime.emit.mousewheel(5, -3);
+    runtime.step();
+    expect(bloop.bag).toMatchObject({
+      down: false,
+      held: true,
+      up: false,
+      position: { x: 123, y: 456 },
+      wheel: { x: 5, y: -3 },
+    });
+
+    runtime.emit.mouseup("Left");
     runtime.step();
-    expect(events).toEqual({
-      keydown: false,
-      keyheld: false,
-      keyup: true,
-      mousedown: false,
-      mouseheld: false,
-      mouseup: true,
+    expect(bloop.bag).toMatchObject({
+      down: false,
+      held: false,
+      up: true,
     });
   });