@bloopjs/bloop 0.0.21 → 0.0.22

package/src/bloop.ts

@@ -21,7 +21,7 @@ import type {
   MouseMoveEvent,
   MouseWheelEvent,
 } from "./events";
-import type { DeserializeFn, SerializeFn } from "./runtime";
+import type { DeserializeFn, EngineHooks, SerializeFn } from "./runtime";
 import type { System } from "./system";
 
 export type BloopOpts<B extends Bag> = {
@@ -63,6 +63,9 @@ export class Bloop<GS extends BloopSchema> {
     return new Bloop<MakeGS<B>>(opts, "dontCallMeDirectly");
   }
 
+  /**
+   * DO NOT USE `new Bloop` - use `Bloop.create()` instead for proper type hints.
+   */
   constructor(opts: BloopOpts<GS["B"]> = {}, dontCallMeDirectly: string) {
     if (dontCallMeDirectly !== "dontCallMeDirectly") {
       throw new Error(
@@ -78,51 +81,22 @@ export class Bloop<GS extends BloopSchema> {
     };
   }
 
+  /**
+   * Read the game singleton bag
+   */
   get bag(): GS["B"] {
     return this.#context.bag;
   }
 
+  /**
+   * Read the game context object
+   */
   get context(): Readonly<Context<GS>> {
     return this.#context;
   }
 
-  /**
-   * Take a snapshot of the game state outside the engine
-   * @returns linear memory representation of the game state that the engine is unaware of
-   */
-  serialize = (): ReturnType<SerializeFn> => {
-    const str = JSON.stringify(this.#context.bag);
-    const encoder = new TextEncoder();
-    const textBytes = encoder.encode(str);
-
-    return {
-      size: textBytes.byteLength,
-      write: (buffer: ArrayBufferLike, ptr: EnginePointer) => {
-        const memoryView = new Uint8Array(buffer, ptr, textBytes.byteLength);
-        memoryView.set(textBytes);
-      },
-    };
-  };
-
-  /**
-   * Restore a snapshot of the game state outside the engine
-   * @returns linear memory representation of the game state that the engine is unaware of
-   */
-  deserialize: DeserializeFn = (buffer, ptr, len) => {
-    const bagBytes = new Uint8Array(buffer, ptr, len);
-    const decoder = new TextDecoder();
-    const str = decoder.decode(bagBytes);
-
-    try {
-      this.#context.bag = JSON.parse(str);
-    } catch (e) {
-      console.error("failed to deserialize bag", { json: str, error: e });
-    }
-  };
-
   /**
    * Register a system with the game loop.
-   *
    */
   system(label: string, system: System<GS>): number {
     system.label ??= label;
@@ -130,102 +104,144 @@ export class Bloop<GS extends BloopSchema> {
     return this.#systems.length;
   }
 
-  systemsCallback(system_handle: number, ptr: EnginePointer) {
-    // todo - move this to engine
-    const dv = new DataView(this.#engineBuffer, ptr);
-    const timeCtxPtr = dv.getUint32(TIME_CTX_OFFSET, true);
-    const inputCtxPtr = dv.getUint32(INPUT_CTX_OFFSET, true);
-    const eventsPtr = dv.getUint32(EVENTS_OFFSET, true);
-
-    this.#context.rawPointer = ptr;
-    this.#context.inputs.dataView = new DataView(
-      this.#engineBuffer,
-      inputCtxPtr,
-    );
-    this.#context.time.dataView = new DataView(this.#engineBuffer, timeCtxPtr);
-
-    const eventsDataView = new DataView(this.#engineBuffer, eventsPtr);
-
-    for (const system of this.#systems) {
-      system.update?.(this.#context);
-
-      const eventCount = eventsDataView.getUint32(0, true);
-
-      let offset = Uint32Array.BYTES_PER_ELEMENT;
-
-      for (let i = 0; i < eventCount; i++) {
-        const eventType = eventsDataView.getUint8(offset);
-        const payloadSize = EVENT_PAYLOAD_SIZE;
-        const payloadByte = eventsDataView.getUint8(
-          offset + EVENT_PAYLOAD_ALIGN,
-        );
-        const payloadVec2 = {
-          x: eventsDataView.getFloat32(offset + EVENT_PAYLOAD_ALIGN, true),
-          y: eventsDataView.getFloat32(
-            offset + EVENT_PAYLOAD_ALIGN + Float32Array.BYTES_PER_ELEMENT,
-            true,
-          ),
-        };
-
-        switch (eventType) {
-          case Enums.EventType.KeyDown: {
-            system.keydown?.(
-              attachEvent<KeyEvent, GS>(this.#context, {
-                key: keyCodeToKey(payloadByte),
-              }),
-            );
-            break;
+  /**
+   * Low level hooks to engine functionality. Editing these is for advanced use cases, defaults should usually work.
+   */
+  hooks: EngineHooks = {
+    /**
+     * Take a snapshot of the game state outside the engine
+     * @returns linear memory representation of the game state that the engine is unaware of
+     */
+    serialize: () => {
+      const str = JSON.stringify(this.#context.bag);
+      const encoder = new TextEncoder();
+      const textBytes = encoder.encode(str);
+
+      return {
+        size: textBytes.byteLength,
+        write: (buffer: ArrayBufferLike, ptr: EnginePointer) => {
+          const memoryView = new Uint8Array(buffer, ptr, textBytes.byteLength);
+          memoryView.set(textBytes);
+        },
+      };
+    },
+
+    /**
+     * Restore a snapshot of the game state outside the engine
+     * @returns linear memory representation of the game state that the engine is unaware of
+     */
+    deserialize: (buffer, ptr, len) => {
+      const bagBytes = new Uint8Array(buffer, ptr, len);
+      const decoder = new TextDecoder();
+      const str = decoder.decode(bagBytes);
+
+      try {
+        this.#context.bag = JSON.parse(str);
+      } catch (e) {
+        console.error("failed to deserialize bag", { json: str, error: e });
+      }
+    },
+
+    setBuffer: (buffer: ArrayBuffer) => {
+      this.#engineBuffer = buffer;
+    },
+
+    systemsCallback: (system_handle: number, ptr: EnginePointer) => {
+      // todo - move this to engine
+      const dv = new DataView(this.#engineBuffer, ptr);
+      const timeCtxPtr = dv.getUint32(TIME_CTX_OFFSET, true);
+      const inputCtxPtr = dv.getUint32(INPUT_CTX_OFFSET, true);
+      const eventsPtr = dv.getUint32(EVENTS_OFFSET, true);
+
+      this.#context.rawPointer = ptr;
+      this.#context.inputs.dataView = new DataView(
+        this.#engineBuffer,
+        inputCtxPtr,
+      );
+      this.#context.time.dataView = new DataView(
+        this.#engineBuffer,
+        timeCtxPtr,
+      );
+
+      const eventsDataView = new DataView(this.#engineBuffer, eventsPtr);
+
+      for (const system of this.#systems) {
+        system.update?.(this.#context);
+
+        const eventCount = eventsDataView.getUint32(0, true);
+
+        let offset = Uint32Array.BYTES_PER_ELEMENT;
+
+        for (let i = 0; i < eventCount; i++) {
+          const eventType = eventsDataView.getUint8(offset);
+          const payloadSize = EVENT_PAYLOAD_SIZE;
+          const payloadByte = eventsDataView.getUint8(
+            offset + EVENT_PAYLOAD_ALIGN,
+          );
+          const payloadVec2 = {
+            x: eventsDataView.getFloat32(offset + EVENT_PAYLOAD_ALIGN, true),
+            y: eventsDataView.getFloat32(
+              offset + EVENT_PAYLOAD_ALIGN + Float32Array.BYTES_PER_ELEMENT,
+              true,
+            ),
+          };
+
+          switch (eventType) {
+            case Enums.EventType.KeyDown: {
+              system.keydown?.(
+                attachEvent<KeyEvent, GS>(this.#context, {
+                  key: keyCodeToKey(payloadByte),
+                }),
+              );
+              break;
+            }
+            case Enums.EventType.KeyUp:
+              system.keyup?.(
+                attachEvent<KeyEvent, GS>(this.#context, {
+                  key: keyCodeToKey(payloadByte),
+                }),
+              );
+              break;
+            case Enums.EventType.MouseDown:
+              system.mousedown?.(
+                attachEvent<MouseButtonEvent, GS>(this.#context, {
+                  button: mouseButtonCodeToMouseButton(payloadByte),
+                }),
+              );
+              break;
+            case Enums.EventType.MouseUp:
+              system.mouseup?.(
+                attachEvent<MouseButtonEvent, GS>(this.#context, {
+                  button: mouseButtonCodeToMouseButton(payloadByte),
+                }),
+              );
+              break;
+            case Enums.EventType.MouseMove:
+              system.mousemove?.(
+                attachEvent<MouseMoveEvent, GS>(this.#context, {
+                  x: payloadVec2.x,
+                  y: payloadVec2.y,
+                }),
+              );
+              break;
+            case Enums.EventType.MouseWheel:
+              system.mousewheel?.(
+                attachEvent<MouseWheelEvent, GS>(this.#context, {
+                  x: payloadVec2.x,
+                  y: payloadVec2.y,
+                }),
+              );
+              break;
+            default:
+              throw new Error(`Unknown event type: ${eventType}`);
           }
-          case Enums.EventType.KeyUp:
-            system.keyup?.(
-              attachEvent<KeyEvent, GS>(this.#context, {
-                key: keyCodeToKey(payloadByte),
-              }),
-            );
-            break;
-          case Enums.EventType.MouseDown:
-            system.mousedown?.(
-              attachEvent<MouseButtonEvent, GS>(this.#context, {
-                button: mouseButtonCodeToMouseButton(payloadByte),
-              }),
-            );
-            break;
-          case Enums.EventType.MouseUp:
-            system.mouseup?.(
-              attachEvent<MouseButtonEvent, GS>(this.#context, {
-                button: mouseButtonCodeToMouseButton(payloadByte),
-              }),
-            );
-            break;
-          case Enums.EventType.MouseMove:
-            system.mousemove?.(
-              attachEvent<MouseMoveEvent, GS>(this.#context, {
-                x: payloadVec2.x,
-                y: payloadVec2.y,
-              }),
-            );
-            break;
-          case Enums.EventType.MouseWheel:
-            system.mousewheel?.(
-              attachEvent<MouseWheelEvent, GS>(this.#context, {
-                x: payloadVec2.x,
-                y: payloadVec2.y,
-              }),
-            );
-            break;
-          default:
-            throw new Error(`Unknown event type: ${eventType}`);
+          // the event type u8 + padding + payload
+          offset += EVENT_PAYLOAD_ALIGN + EVENT_PAYLOAD_SIZE;
         }
-        // the event type u8 + padding + payload
-        offset += EVENT_PAYLOAD_ALIGN + EVENT_PAYLOAD_SIZE;
+        (this.#context as any).event = undefined;
       }
-      (this.#context as any).event = undefined;
-    }
-  }
-
-  setBuffer(buffer: ArrayBuffer) {
-    this.#engineBuffer = buffer;
-  }
+    },
+  };
 }
 
 function attachEvent<IE extends InputEvent, GS extends BloopSchema>(

package/src/mod.ts

@@ -1,4 +1,9 @@
-export * from "./runtime"
-export * from "./bloop"
+export type * as typesRuntime from "./runtime"
+export type * as typesMount from "./mount"
+export type * as typesBloop from "./bloop"
+export type * as typesContext from "./context"
 
-export * as Util from "./util";
+export * as Util from "./util";
+
+export { mount } from "./mount";
+export { Bloop } from "./bloop"

package/src/mount.ts

@@ -0,0 +1,86 @@
+import {
+  DEFAULT_WASM_URL,
+  type EnginePointer,
+  type WasmEngine,
+} from "@bloopjs/engine";
+import { type EngineHooks, Runtime } from "./runtime";
+import { assert } from "./util";
+
+export async function mount(opts: MountOpts): Promise<MountResult> {
+  // https://github.com/oven-sh/bun/issues/12434
+  const bytes = await fetch(opts.wasmUrl ?? DEFAULT_WASM_URL)
+    .then((res) => res.arrayBuffer())
+    .catch((e) => {
+      console.error(
+        `Failed to fetch wasm at ${opts.wasmUrl ?? DEFAULT_WASM_URL}`,
+        e,
+      );
+      throw e;
+    });
+
+  // 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.hooks.setBuffer(memory.buffer);
+        opts.hooks.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.hooks.serialize();
+        return serializer ? serializer.size : 0;
+      },
+      user_data_serialize: function (ptr: EnginePointer, len: number) {
+        const serializer = opts.hooks.serialize();
+        assert(
+          len === serializer.size,
+          `user_data_serialize length mismatch, expected=${serializer.size} got=${len}`,
+        );
+        serializer.write(memory.buffer, ptr);
+      },
+      user_data_deserialize: function (ptr: EnginePointer, len: number) {
+        opts.hooks.deserialize(memory.buffer, ptr, len);
+      },
+    },
+  });
+  const wasm = wasmInstantiatedSource.instance.exports as WasmEngine;
+
+  wasm.initialize();
+
+  const runtime = new Runtime(wasm, memory, {
+    serialize: opts.hooks.serialize,
+  });
+
+  if (opts.startRecording ?? true) {
+    runtime.record();
+  }
+
+  return {
+    runtime,
+    wasm,
+  };
+}
+
+export type MountOpts = {
+  hooks: EngineHooks;
+
+  wasmUrl?: URL;
+
+  /**
+   * Whether to start recording immediately upon mount
+   * Defaults to true
+   */
+  startRecording?: boolean;
+};
+
+export type MountResult = {
+  runtime: Runtime;
+  wasm: WasmEngine;
+};

package/src/runtime.ts

@@ -6,44 +6,38 @@ import {
   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;
+export type EngineHooks = {
+  /**
+   * Hook to serialize some data when snapshotting
+   */
+  serialize: SerializeFn;
+  /**
+   * Hook to deserialize some data when restoring
+   */
+  deserialize: DeserializeFn;
   /**
    * A callback function to run logic for a given frame
    */
-  systemsCallback: (system_handle: number, ptr: EnginePointer) => void;
-
+  systemsCallback: SystemsCallback;
   /**
    * 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 SystemsCallback = (
+  system_handle: number,
+  ptr: EnginePointer,
+) => void;
+
 export type SerializeFn = () => {
   size: number;
   write(buffer: ArrayBufferLike, ptr: EnginePointer): void;
@@ -198,76 +192,3 @@ export class Runtime {
     },
   };
 }
-
-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,
-  };
-}