@threenative/core 0.2.0 → 0.3.1

package/dist/gpu-readback-D2iRvoe9.d.ts

@@ -0,0 +1,112 @@
+import { Object3D } from 'three';
+import { I as IRendererLike } from './renderer-C6hqZpoG.js';
+
+/**
+ * The lifecycle contract for a game-owned GPU simulation.
+ *
+ * A compute-driven object owns its kernels, buffers, and appearance. The framework only attaches
+ * the active renderer, warms the kernels before the world is shown, dispatches process calls at
+ * the object's declared cadence, and releases the object when its scene ends.
+ */
+interface IComputeDriven {
+    /** Kernels to compile before the world is shown. Read once, at attach. */
+    readonly warmupNodes: readonly unknown[];
+    attachRenderer(renderer: IRendererLike): void;
+    /**
+     * The loop phase that dispatches `process`. Defaults to fixed-step; render cadence preserves the
+     * existing behavior of consumers whose simulation is intentionally tied to presentation.
+     */
+    readonly processCadence?: "fixed" | "render";
+    /** Dispatched once per fixed step, in scene-add order unless render cadence is declared. */
+    process(renderer: IRendererLike): void;
+    detach(): void;
+    readonly released: boolean;
+}
+/** The ordered registry used by the game loop for all compute-driven scene objects. */
+declare class ComputeDrivenRegistry {
+    #private;
+    get size(): number;
+    /** Attach and remember one object. Re-adding the same object is idempotent. */
+    add(object: Object3D & IComputeDriven, renderer: IRendererLike): void;
+    /** Release one object without disturbing the order of the remaining objects. */
+    remove(driven: IComputeDriven): void;
+    /** Kernels in the same order as their objects were added to the scene. */
+    get warmupNodes(): readonly unknown[];
+    /** Dispatch fixed-step objects once; detached scene children are released before dispatch. */
+    process(renderer: IRendererLike): void;
+    /** Dispatch render-cadence objects once; detached scene children are released before dispatch. */
+    processRender(renderer: IRendererLike): void;
+    /** Release every registered object, continuing after a failure so no resource is stranded. */
+    clear(): void;
+}
+
+interface IGPUReadbackOptions {
+    /** The GPU storage attribute to copy — a TSL storage node's `.value`. */
+    readonly attribute: unknown;
+    /**
+     * Frames between readback requests. `1` asks every frame; larger values throttle.
+     *
+     * A copy off the GPU costs a queue submission and a mapped buffer, so a game reading a field it
+     * only consults for physics asks for it every few frames and pays the staleness instead.
+     */
+    readonly everyFrames: number;
+}
+/** A landed copy of GPU memory, with the age of the frame that produced it. */
+interface IGPUReadbackSample {
+    readonly data: Float32Array;
+    /**
+     * Frames between the frame whose GPU state these bytes hold and the frame reading them.
+     *
+     * This is the number a caller must not be allowed to ignore. A buoyancy solver that treats a
+     * 4-frame-old surface as this frame's surface floats a hull through the water it is drawn on,
+     * and nothing in the frame says so.
+     */
+    readonly staleFrames: number;
+}
+/**
+ * A throttled, fire-and-forget copy of a GPU buffer into CPU memory.
+ *
+ * Every sample it hands back carries its own age. That is the whole point: the copy is
+ * asynchronous, so the bytes are always some frames behind the GPU, and a class that hid that
+ * would let a caller mistake stale data for live data with no way to find out.
+ *
+ * `request()` never awaits and never blocks the frame. One copy is in flight at a time; requests
+ * made while one is pending are dropped rather than queued, because a backlog of copies of a field
+ * that has already moved on is latency with no information in it.
+ */
+declare class GPUReadback {
+    #private;
+    readonly everyFrames: number;
+    constructor(options: IGPUReadbackOptions);
+    get released(): boolean;
+    /** True while a copy is in flight. A game that wants to pace its own work can read it. */
+    get pending(): boolean;
+    /** The newest landed bytes, or `undefined` before the first copy lands. */
+    get data(): Float32Array | undefined;
+    /**
+     * How many frames old the landed bytes are.
+     *
+     * Before anything has landed this is the number of frames since construction, which grows
+     * without bound on purpose: "no data yet" and "data from frame zero" must not read the same.
+     */
+    get staleFrames(): number;
+    /** The newest bytes with their age attached, or `undefined` before the first copy lands. */
+    get sample(): IGPUReadbackSample | undefined;
+    /** Requests, landings and failures, for a report that has to say why a sample is old. */
+    get stats(): {
+        readonly requests: number;
+        readonly lands: number;
+        readonly failures: number;
+    };
+    /**
+     * Advances the frame clock and starts a copy when the throttle allows one.
+     *
+     * Safe to call every frame. It returns before the GPU has answered — awaiting it is the one
+     * thing that would turn this class into the stall it exists to avoid.
+     */
+    request(renderer: IRendererLike): void;
+    /** Drops the attribute reference and the landed bytes. Further requests throw. */
+    dispose(): void;
+}
+
+export { ComputeDrivenRegistry as C, GPUReadback as G, type IComputeDriven as I, type IGPUReadbackSample as a, type IGPUReadbackOptions as b };

package/dist/hot.d.ts

@@ -1,6 +1,10 @@
-import { a as audioRuntimeSnapshot } from './audio-CEAw0w5y.js';
-import { I as IGame } from './game-DRt1Qhq3.js';
+import { a as audioRuntimeSnapshot } from './audio-BFiGneTL.js';
+import { I as IGame } from './game-XGrTzapq.js';
 import 'three';
+import './assets-kyoF7JlJ.js';
+import './renderer-C6hqZpoG.js';
+import 'three/webgpu';
+import './canvas-layer-BLVijiUJ.js';
 import 'zustand/vanilla';
 
 interface IHotDiagnostics {
@@ -11,7 +15,21 @@ interface IHotDiagnostics {
     readonly audio: ReturnType<typeof audioRuntimeSnapshot>;
     readonly physics: number | null;
 }
+/**
+ * Validate that hot-reload state can cross the Vite boundary.
+ * @situation preserve JSON-shaped state during hot reload
+ * @situation reject a non-portable game state before reload
+ * @constraint state must contain finite numbers and plain objects only
+ * @example assertPortableState(game.state.getState());
+ */
 declare function assertPortableState(state: unknown): void;
+/**
+ * Register hot-reload state preservation for a game.
+ * @situation keep game state while editing source in development
+ * @situation diagnose state shape changes during hot reload
+ * @constraint use only in the web development entry
+ * @example acceptHotUpdate(game, import.meta.hot);
+ */
 declare function acceptHotUpdate<TState extends Record<string, unknown>, TPhysics>(game: IGame<TState, TPhysics>, hot: IImportMeta["hot"]): void;
 interface IImportMeta {
     readonly env?: {

package/dist/hot.js

@@ -5,11 +5,17 @@ var buses = /* @__PURE__ */ new Set();
 function audioRuntimeSnapshot() {
   let queued = 0;
   let voices = 0;
+  let pooled = 0;
+  let paused = 0;
+  const unsupported = /* @__PURE__ */ new Set();
   for (const bus of buses) {
     queued += bus.queued;
     voices += bus.voices;
+    pooled += bus.pooled;
+    paused += bus.pausedVoices;
+    for (const option of bus.unsupported) unsupported.add(option);
   }
-  return { queued, voices };
+  return { paused, pooled, queued, unsupported: [...unsupported].sort(), voices };
 }
 
 // src/hot.ts
@@ -23,6 +29,12 @@ function acceptHotUpdate(game, hot) {
   const carried = hot.data.threenative;
   const reloads = carried?.reloads ?? 0;
   if (carried !== void 0) restoreState(game, carried.state);
+  if (carried?.sceneName !== void 0) {
+    try {
+      game.resumeScene(carried.sceneName);
+    } catch {
+    }
+  }
   if (isDev && typeof window !== "undefined") {
     const host = window;
     host.__THREENATIVE__ = {
@@ -39,7 +51,7 @@ function acceptHotUpdate(game, hot) {
       game.state.flush();
       const state = game.state.getState();
       assertPortableState(state);
-      data.threenative = { reloads: reloads + 1, state };
+      data.threenative = { reloads: reloads + 1, sceneName: game.sceneName, state };
     } catch (error) {
       data.threenative = void 0;
       hot.invalidate(error instanceof Error ? error.message : String(error));