@zylem/game-lib 0.9.1 → 0.9.2

package/dist/api/game-lib.api.json

@@ -40729,6 +40729,75 @@
           ],
           "name": "lerpVec3"
         },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@zylem/game-lib!LevelStage:interface",
+          "docComment": "/**\n * The slice of a stage `streamLevelOnStage` needs.\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "interface LevelStage "
+            }
+          ],
+          "fileUrlPath": "dist/core.d.ts",
+          "releaseTag": "Public",
+          "name": "LevelStage",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "MethodSignature",
+              "canonicalReference": "@zylem/game-lib!LevelStage#spawnEntity:member(1)",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "spawnEntity(node: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "BaseNode",
+                  "canonicalReference": "@zylem/game-lib!~BaseNode:class"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Promise",
+                  "canonicalReference": "!Promise:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": "<void> | void"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isOptional": false,
+              "returnTypeTokenRange": {
+                "startIndex": 3,
+                "endIndex": 5
+              },
+              "releaseTag": "Public",
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "node",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                }
+              ],
+              "name": "spawnEntity"
+            }
+          ],
+          "extendsTokenRanges": []
+        },
         {
           "kind": "Variable",
           "canonicalReference": "@zylem/game-lib!LIGHT_TYPE:var",
@@ -60844,6 +60913,301 @@
           ],
           "extendsTokenRanges": []
         },
+        {
+          "kind": "Function",
+          "canonicalReference": "@zylem/game-lib!streamLevel:function(1)",
+          "docComment": "/**\n * Hand each buffer entry to `spawn`, in order, yielding between batches.\n *\n * @returns How many entries were handed off. A spawn that no-ops for an unknown catalog type still counts: the entry was delivered.\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "declare function streamLevel(buffer: "
+            },
+            {
+              "kind": "Reference",
+              "text": "LevelBuffer",
+              "canonicalReference": "@zylem/bridge!LevelBuffer:interface"
+            },
+            {
+              "kind": "Content",
+              "text": ", spawn: "
+            },
+            {
+              "kind": "Content",
+              "text": "(entry: "
+            },
+            {
+              "kind": "Reference",
+              "text": "LevelEntry",
+              "canonicalReference": "@zylem/bridge!LevelEntry:interface"
+            },
+            {
+              "kind": "Content",
+              "text": ") => void | "
+            },
+            {
+              "kind": "Reference",
+              "text": "Promise",
+              "canonicalReference": "!Promise:interface"
+            },
+            {
+              "kind": "Content",
+              "text": "<void>"
+            },
+            {
+              "kind": "Content",
+              "text": ", options?: "
+            },
+            {
+              "kind": "Reference",
+              "text": "StreamLevelOptions",
+              "canonicalReference": "@zylem/game-lib!StreamLevelOptions:interface"
+            },
+            {
+              "kind": "Content",
+              "text": "): "
+            },
+            {
+              "kind": "Reference",
+              "text": "Promise",
+              "canonicalReference": "!Promise:interface"
+            },
+            {
+              "kind": "Content",
+              "text": "<"
+            },
+            {
+              "kind": "Reference",
+              "text": "StreamLevelResult",
+              "canonicalReference": "@zylem/game-lib!StreamLevelResult:interface"
+            },
+            {
+              "kind": "Content",
+              "text": ">"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "dist/core.d.ts",
+          "returnTypeTokenRange": {
+            "startIndex": 11,
+            "endIndex": 15
+          },
+          "releaseTag": "Public",
+          "overloadIndex": 1,
+          "parameters": [
+            {
+              "parameterName": "buffer",
+              "parameterTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isOptional": false
+            },
+            {
+              "parameterName": "spawn",
+              "parameterTypeTokenRange": {
+                "startIndex": 3,
+                "endIndex": 8
+              },
+              "isOptional": false
+            },
+            {
+              "parameterName": "options",
+              "parameterTypeTokenRange": {
+                "startIndex": 9,
+                "endIndex": 10
+              },
+              "isOptional": true
+            }
+          ],
+          "name": "streamLevel"
+        },
+        {
+          "kind": "Function",
+          "canonicalReference": "@zylem/game-lib!streamLevelOnStage:function(1)",
+          "docComment": "/**\n * Spawn every catalog entry in `buffer` onto `stage`.\n *\n * Position is handed to the type's factory. Rotation and scale are applied after spawn, and a scale change rebuilds colliders. An entry whose catalog id is not registered is skipped.\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "declare function streamLevelOnStage(stage: "
+            },
+            {
+              "kind": "Reference",
+              "text": "LevelStage",
+              "canonicalReference": "@zylem/game-lib!LevelStage:interface"
+            },
+            {
+              "kind": "Content",
+              "text": ", buffer: "
+            },
+            {
+              "kind": "Reference",
+              "text": "LevelBuffer",
+              "canonicalReference": "@zylem/bridge!LevelBuffer:interface"
+            },
+            {
+              "kind": "Content",
+              "text": ", options?: "
+            },
+            {
+              "kind": "Reference",
+              "text": "StreamLevelOptions",
+              "canonicalReference": "@zylem/game-lib!StreamLevelOptions:interface"
+            },
+            {
+              "kind": "Content",
+              "text": "): "
+            },
+            {
+              "kind": "Reference",
+              "text": "Promise",
+              "canonicalReference": "!Promise:interface"
+            },
+            {
+              "kind": "Content",
+              "text": "<"
+            },
+            {
+              "kind": "Reference",
+              "text": "StreamLevelResult",
+              "canonicalReference": "@zylem/game-lib!StreamLevelResult:interface"
+            },
+            {
+              "kind": "Content",
+              "text": ">"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "dist/core.d.ts",
+          "returnTypeTokenRange": {
+            "startIndex": 7,
+            "endIndex": 11
+          },
+          "releaseTag": "Public",
+          "overloadIndex": 1,
+          "parameters": [
+            {
+              "parameterName": "stage",
+              "parameterTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isOptional": false
+            },
+            {
+              "parameterName": "buffer",
+              "parameterTypeTokenRange": {
+                "startIndex": 3,
+                "endIndex": 4
+              },
+              "isOptional": false
+            },
+            {
+              "parameterName": "options",
+              "parameterTypeTokenRange": {
+                "startIndex": 5,
+                "endIndex": 6
+              },
+              "isOptional": true
+            }
+          ],
+          "name": "streamLevelOnStage"
+        },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@zylem/game-lib!StreamLevelOptions:interface",
+          "docComment": "/**\n * Stream a level buffer into a stage.\n *\n * The streamer does not know the catalog. `spawn` is the host's existing create path, which resolves a catalog id and no-ops when the type is unknown. Entries are handed off in batches, yielding to the event loop between them so a large level does not stall the frame the way a single synchronous spawn loop would.\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "interface StreamLevelOptions "
+            }
+          ],
+          "fileUrlPath": "dist/core.d.ts",
+          "releaseTag": "Public",
+          "name": "StreamLevelOptions",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@zylem/game-lib!StreamLevelOptions#batchSize:member",
+              "docComment": "/**\n * @default 5\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "batchSize?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Public",
+              "name": "batchSize",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            }
+          ],
+          "extendsTokenRanges": []
+        },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@zylem/game-lib!StreamLevelResult:interface",
+          "docComment": "",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "interface StreamLevelResult "
+            }
+          ],
+          "fileUrlPath": "dist/core.d.ts",
+          "releaseTag": "Public",
+          "name": "StreamLevelResult",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@zylem/game-lib!StreamLevelResult#spawned:member",
+              "docComment": "/**\n * Entries handed to `spawn`, in buffer order.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "spawned: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "spawned",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            }
+          ],
+          "extendsTokenRanges": []
+        },
         {
           "kind": "Interface",
           "canonicalReference": "@zylem/game-lib!SwatchApplyOutcome:interface",

package/dist/api/game-lib.api.md

@@ -169,6 +169,8 @@ import { JumpInput3D } from '@zylem/behaviors';
 import { JumpState2D } from '@zylem/behaviors';
 import { JumpState3D } from '@zylem/behaviors';
 import { length as length_2 } from 'three/tsl';
+import { LevelBuffer } from '@zylem/bridge';
+import { LevelEntry } from '@zylem/bridge';
 import { Light } from 'three';
 import { Line2 } from 'three/addons/lines/webgpu/Line2.js';
 import { Material } from 'three';
@@ -3173,6 +3175,14 @@ export function lerpPose(a: EvaluatedPose, b: EvaluatedPose, t: number): Evaluat
 // @public (undocumented)
 export function lerpVec3(a: Vec3Def, b: Vec3Def, t: number): Vec3Def;
 
+export { LevelBuffer }
+
+// @public
+export interface LevelStage {
+    // (undocumented)
+    spawnEntity(node: BaseNode): Promise<void> | void;
+}
+
 // @public (undocumented)
 export const LIGHT_TYPE: unique symbol;
 
@@ -4942,6 +4952,23 @@ export interface StrategyPointer {
     y: number;
 }
 
+// @public
+export function streamLevel(buffer: LevelBuffer, spawn: (entry: LevelEntry) => void | Promise<void>, options?: StreamLevelOptions): Promise<StreamLevelResult>;
+
+// @public
+export function streamLevelOnStage(stage: LevelStage, buffer: LevelBuffer, options?: StreamLevelOptions): Promise<StreamLevelResult>;
+
+// @public
+export interface StreamLevelOptions {
+    // (undocumented)
+    batchSize?: number;
+}
+
+// @public (undocumented)
+export interface StreamLevelResult {
+    spawned: number;
+}
+
 export { SwatchApplyFailureReason }
 
 // @public

package/dist/api/game-lib.d.ts

@@ -163,6 +163,8 @@ import { JumpInput3D } from '@zylem/behaviors';
 import { JumpState2D } from '@zylem/behaviors';
 import { JumpState3D } from '@zylem/behaviors';
 import { length as length_2 } from 'three/tsl';
+import { LevelBuffer } from '@zylem/bridge';
+import { LevelEntry } from '@zylem/bridge';
 import { Light } from 'three';
 import { Line2 } from 'three/addons/lines/webgpu/Line2.js';
 import { Material } from 'three';
@@ -3555,6 +3557,13 @@ export declare class GameBridge {
      * variable's update would never reach the editor.
      */
     publishVariable(payload: GameVariablePayload): void;
+    /**
+     * Stream a level buffer through the host's catalog spawn.
+     *
+     * Each entry is handed to `createEntity`, which no-ops for an unknown
+     * type. The notice counts entries handed off, not bodies that appeared.
+     */
+    private loadLevel;
     /** Surface a diagnostic message in the editor console. */
     publishNotice(level: GameNoticePayload['level'], message: string): void;
     publishStageSnapshot(snapshot: StageSnapshotPayload): void;
@@ -4986,6 +4995,21 @@ export declare function lerpPose(a: EvaluatedPose, b: EvaluatedPose, t: number):
 
 export declare function lerpVec3(a: Vec3Def, b: Vec3Def, t: number): Vec3Def;
 
+export { LevelBuffer }
+
+/**
+ * Stream a level buffer into a stage through the catalog.
+ *
+ * `streamLevel` only walks entries. This is the call gameplay code makes:
+ * each entry is created from its catalog id, spawned, then posed. Unknown
+ * catalog ids are skipped. Batching stays in `streamLevel`.
+ */
+
+/** The slice of a stage `streamLevelOnStage` needs. */
+export declare interface LevelStage {
+    spawnEntity(node: BaseNode): Promise<void> | void;
+}
+
 /**
  * Provides BaseNode-like lifecycle without ECS/children. Consumers implement
  * the protected hooks and may assign public setup/update/destroy callbacks.
@@ -8345,6 +8369,43 @@ export declare interface StrategyPointer {
     centered?: boolean;
 }
 
+/**
+ * Hand each buffer entry to `spawn`, in order, yielding between batches.
+ *
+ * @returns How many entries were handed off. A spawn that no-ops for an
+ * unknown catalog type still counts: the entry was delivered.
+ */
+export declare function streamLevel(buffer: LevelBuffer, spawn: (entry: LevelEntry) => void | Promise<void>, options?: StreamLevelOptions): Promise<StreamLevelResult>;
+
+/**
+ * Spawn every catalog entry in `buffer` onto `stage`.
+ *
+ * Position is handed to the type's factory. Rotation and scale are applied
+ * after spawn, and a scale change rebuilds colliders. An entry whose catalog
+ * id is not registered is skipped.
+ */
+export declare function streamLevelOnStage(stage: LevelStage, buffer: LevelBuffer, options?: StreamLevelOptions): Promise<StreamLevelResult>;
+
+/**
+ * Stream a level buffer into a stage.
+ *
+ * The streamer does not know the catalog. `spawn` is the host's existing
+ * create path, which resolves a catalog id and no-ops when the type is
+ * unknown. Entries are handed off in batches, yielding to the event loop
+ * between them so a large level does not stall the frame the way a single
+ * synchronous spawn loop would.
+ */
+
+export declare interface StreamLevelOptions {
+    /** @default 5 */
+    batchSize?: number;
+}
+
+export declare interface StreamLevelResult {
+    /** Entries handed to `spawn`, in buffer order. */
+    spawned: number;
+}
+
 export { SwatchApplyFailureReason }
 
 /** What a host reports back from a swatch batch. */