@zylem/game-lib 0.9.1 → 0.9.3

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';
@@ -679,22 +681,24 @@ export const CameraKeyframeSchema: _sinclair_typebox.TObject<{
     easing: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"linear">, _sinclair_typebox.TLiteral<"easeIn">, _sinclair_typebox.TLiteral<"easeOut">, _sinclair_typebox.TLiteral<"easeInOut">]>;
 }>;
 
+// Warning: (ae-forgotten-export) The symbol "EditorCameraHost" needs to be exported by the entry point public.d.ts
+//
 // @public
-export class CameraManager {
-    constructor();
-    activateDebugCamera(): boolean;
+export class CameraManager implements EditorCameraHost {
+    activateCameraById(id: string): boolean;
     // Warning: (ae-forgotten-export) The symbol "ZylemCamera" needs to be exported by the entry point public.d.ts
     get activeCameras(): ReadonlyArray<ZylemCamera>;
     addActiveCamera(nameOrRef: string | ZylemCamera): boolean;
     addCamera(camera: ZylemCamera, name?: string): string;
     get allCameras(): ReadonlyArray<ZylemCamera>;
     deactivateCamera(nameOrRef: string | ZylemCamera): boolean;
-    deactivateDebugCamera(): boolean;
-    get debugCamera(): ZylemCamera | null;
+    destroyEditorCameras(): void;
     dispose(): void;
     ensureDefaultCamera(): ZylemCamera;
+    ensureEditorCameras(): Promise<void>;
     getCamera(name: string): ZylemCamera | null;
-    get preDebugPrimary(): ZylemCamera | null;
+    hasEditorCameras(): boolean;
+    isEditorViewActive(): boolean;
     get primaryCamera(): ZylemCamera | null;
     removeCamera(nameOrRef: string | ZylemCamera): boolean;
     render(scene: Scene): void;
@@ -2152,6 +2156,7 @@ export class GameBridge {
     // (undocumented)
     disconnect(): void;
     onEditorAttached(callback: () => void): () => void;
+    onEditorDetached(callback: () => void): () => void;
     publishCatalog(entities: EntityTypeDescriptor[]): void;
     // (undocumented)
     publishConfig(config: GameConfigPayload): void;
@@ -3173,6 +3178,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 +4955,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
@@ -6178,8 +6208,8 @@ export class ZylemZone extends GameEntity<ZylemZoneOptions> implements Collision
 // dist/entity-XqvuWgPm.d.ts:343:9 - (ae-forgotten-export) The symbol "EntityMeshBuilder" needs to be exported by the entry point public.d.ts
 // dist/entity-XqvuWgPm.d.ts:344:9 - (ae-forgotten-export) The symbol "EntityCollisionBuilder" needs to be exported by the entry point public.d.ts
 // dist/entity-XqvuWgPm.d.ts:345:9 - (ae-forgotten-export) The symbol "MaterialBuilder" needs to be exported by the entry point public.d.ts
-// dist/game-D8KTP3fD.d.ts:258:5 - (ae-forgotten-export) The symbol "StageInterface" needs to be exported by the entry point public.d.ts
-// dist/stage-CAPlk_cN.d.ts:1117:5 - (ae-forgotten-export) The symbol "StageAssetLoaderConfig" needs to be exported by the entry point public.d.ts
+// dist/game-DBNxY6mb.d.ts:258:5 - (ae-forgotten-export) The symbol "StageInterface" needs to be exported by the entry point public.d.ts
+// dist/stage-bVLyYnOQ.d.ts:1148:5 - (ae-forgotten-export) The symbol "StageAssetLoaderConfig" needs to be exported by the entry point public.d.ts
 
 // (No @packageDocumentation comment for this package)
 

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';
@@ -456,8 +458,9 @@ declare type ActorOptions = BaseNode | ZylemActorOptions;
  * hover/select/delete/spawn, the `DebugEntityCursor` highlight and the
  * `PlacementGhost` — is live whenever a tool is armed, so the toolbar's buttons
  * work on their own. The debug layer — the wasm simulation's collider
- * wireframes and the orbit camera — is the part `debugState.enabled` gates, and
- * is torn down when it goes off while the delegate stays alive to re-activate.
+ * wireframes — is the part `debugState.enabled` gates, and is torn down when
+ * it goes off while the delegate stays alive to re-activate. Debug mode does
+ * not switch cameras; picking and gizmos use whichever camera is rendering.
  *
  * Centralizes all of this so `ZylemStage` doesn't have to know about
  * raycasting, DOM input, or debug rendering.
@@ -956,28 +959,38 @@ export declare const CameraKeyframeSchema: _sinclair_typebox.TObject<{
  * Responsibilities:
  * - Named camera registry (add/remove/get by name or reference)
  * - Active camera list management (determines which cameras render)
- * - Always-available debug camera with orbit controls
+ * - Editor view cameras (side, top, isometric, free), created only while an editor is attached
  * - Per-frame update of all active cameras' perspective controllers
  * - Coordinating rendering via RendererManager for all active viewports
  */
-export declare class CameraManager {
+export declare class CameraManager implements EditorCameraHost {
     /** Named camera registry */
     private cameras;
     /** Currently active cameras, ordered by render layer (first = bottom) */
     private _activeCameras;
-    /** Auto-created debug camera with orbit controls */
-    private _debugCamera;
-    /** Gameplay primary camera saved while the debug camera is active. */
-    private _preDebugPrimary;
-    /** Scene anchor at world origin for debug orbit when nothing is selected. */
-    private _debugOrbitTargetAnchor;
+    /** Editor view cameras, keyed by `editor:*` id. */
+    private _editorCameras;
+    /** Which editor views freeze rotation. */
+    private _lockedEditorIds;
+    /** Game camera to restore when the editor releases the main view. */
+    private _rememberedGameCamera;
+    /**
+     * True while an editor view is the main camera. Game calls to
+     * {@link setActiveCamera} update {@link _rememberedGameCamera} and leave
+     * the view on screen.
+     */
+    private _editorViewLocked;
+    /** Game cameras whose orbit input was suspended for an editor view. */
+    private _suspendedOrbits;
+    /** In-flight creation, so a second attach does not build a second set. */
+    private _editorCamerasPromise;
     /** Reference to the shared renderer manager */
     private _rendererManager;
     /** Scene reference */
     private _sceneRef;
     /** Counter for auto-generated camera names */
     private _autoNameCounter;
-    constructor();
+    private _unregisterEditorHost;
     /**
      * Get the list of currently active cameras.
      */
@@ -986,14 +999,10 @@ export declare class CameraManager {
      * Get the primary active camera (first in the active list).
      */
     get primaryCamera(): ZylemCamera | null;
-    /**
-     * Get the debug camera.
-     */
-    get debugCamera(): ZylemCamera | null;
-    /**
-     * Gameplay primary camera that was active before debug mode was enabled.
-     */
-    get preDebugPrimary(): ZylemCamera | null;
+    /** True while side, top, isometric, or free is the main view. */
+    isEditorViewActive(): boolean;
+    /** True after the four editor views have been created. */
+    hasEditorCameras(): boolean;
     /**
      * Get all registered cameras.
      */
@@ -1010,13 +1019,15 @@ export declare class CameraManager {
     addCamera(camera: ZylemCamera, name?: string): string;
     /**
      * Remove a camera by name or reference.
-     * Cannot remove the debug camera via this method.
      */
     removeCamera(nameOrRef: string | ZylemCamera): boolean;
     /**
      * Set a camera as the primary active camera (replaces all active cameras
      * except additional viewport cameras).
      *
+     * While an editor view owns the main view, a game camera is remembered
+     * and the rendered camera does not change.
+     *
      * @param nameOrRef Camera name or reference to activate
      */
     setActiveCamera(nameOrRef: string | ZylemCamera): boolean;
@@ -1034,19 +1045,27 @@ export declare class CameraManager {
     getCamera(name: string): ZylemCamera | null;
     /**
      * Setup all cameras with the given scene and renderer manager.
-     * Also creates the debug camera.
+     * Editor view cameras are created here only when an editor is already attached.
      */
     setup(scene: Scene, rendererManager: RendererManager): Promise<void>;
     /**
-     * Switch the primary viewport to the debug orbit camera, remembering the
-     * previous primary so gameplay cameras (e.g. first-person) can be restored.
+     * Create side, top, isometric, and free cameras seeded from the current
+     * game camera. Does not change which camera is rendering.
+     */
+    ensureEditorCameras(): Promise<void>;
+    /**
+     * Restore the game camera when an editor view is showing, then destroy
+     * the four editor cameras.
      */
-    activateDebugCamera(): boolean;
+    destroyEditorCameras(): void;
     /**
-     * Restore the gameplay primary camera that was active before
-     * {@link activateDebugCamera}.
+     * Switch the main view.
+     *
+     * `game` releases to the remembered game camera. Editor view ids show
+     * that view. Any other id activates a game-registered camera and clears
+     * the editor override.
      */
-    deactivateDebugCamera(): boolean;
+    activateCameraById(id: string): boolean;
     /**
      * Update all active cameras' controllers.
      */
@@ -1066,16 +1085,19 @@ export declare class CameraManager {
      * Dispose all cameras and cleanup.
      */
     dispose(): void;
-    /**
-     * Create the always-available debug camera with orbit controls.
-     * Registered for lookup/activation, but not added to the active list.
-     */
-    private createDebugCamera;
-    /**
-     * Seed the debug camera orbit pose on first activation, framing the origin
-     * or offsetting from the saved gameplay primary.
-     */
-    private seedDebugCameraPose;
+    private createEditorCameras;
+    private showEditorCamera;
+    private showGameCamera;
+    /** Enable orbit on the active editor view only. Inactive views keep their pose. */
+    private syncEditorOrbit;
+    /** Stop game-camera orbit controls from sharing the canvas with an editor view. */
+    private suspendOtherOrbits;
+    private restoreOrbitFor;
+    private gameCameraToRestore;
+    private cameraIsRegistered;
+    private isEditorCamera;
+    /** Replace the primary camera and keep picture-in-picture viewports. */
+    private commitActive;
     /**
      * Resolve a camera from a name or reference.
      */
@@ -2692,6 +2714,19 @@ export { dot }
  */
 export declare function easeValue(easing: CutsceneEasing, t: number): number;
 
+/**
+ * Editor-view cameras exist only while an editor is attached.
+ *
+ * `GameBridge.connect()` runs for every game, so it is not the signal. The
+ * bridge marks the session attached when an editor subscribes, and every live
+ * camera manager creates or destroys its four view cameras from that flag.
+ */
+declare interface EditorCameraHost {
+    ensureEditorCameras(): Promise<void>;
+    destroyEditorCameras(): void;
+    activateCameraById(id: string): boolean;
+}
+
 export { EditorToGameMessages }
 
 export declare type EffectType = Static<typeof EffectTypeSchema>;
@@ -3320,8 +3355,9 @@ export { floor }
 export { Fn }
 
 /**
- * Select an entity by UUID and frame the debug camera to fit it.
- * Enables debug mode so orbit controls are active.
+ * Select an entity by UUID and frame the active editor camera to fit it.
+ * When the game camera is showing, the stage switches to the free editor
+ * camera first. Enables debug mode so the selection is visible.
  *
  * @returns true if the entity was found and framed
  */
@@ -3488,6 +3524,8 @@ export declare class GameBridge {
      * not themselves recorded as new operations.
      */
     private applyingSceneOperation;
+    /** Frame watch used when the channel cannot report subscriber removal. */
+    private editorCameraFrame;
     constructor();
     /**
      * Subscribe to editor commands and announce the game side as ready.
@@ -3540,6 +3578,29 @@ export declare class GameBridge {
      * @returns An unsubscribe function.
      */
     onEditorAttached(callback: () => void): () => void;
+    /**
+     * Run a callback when the editor drops both entity subscriptions.
+     *
+     * Mirrors {@link onEditorAttached}: the first of the pair to unsubscribe
+     * is the same editor finishing teardown, so the callback waits until the
+     * other type is already at zero.
+     *
+     * @returns An unsubscribe function.
+     */
+    onEditorDetached(callback: () => void): () => void;
+    /** True when an editor is listening for entity data. */
+    private editorIsAttached;
+    /** Create the view cameras and, if needed, watch for the editor leaving. */
+    private attachEditorCameras;
+    /** Destroy the view cameras and stop watching for editor removal. */
+    private detachEditorCameras;
+    /**
+     * Published bridge builds do not report the last subscriber leaving.
+     * While the editor is attached, look again each frame and tear the view
+     * cameras down once both entity subscriptions are gone.
+     */
+    private watchEditorDetached;
+    private stopWatchingEditorDetached;
     publishConfig(config: GameConfigPayload): void;
     publishLoading(payload: BridgeLoadingPayload): void;
     publishStatus(status: {
@@ -3555,6 +3616,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 +5054,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.
@@ -7596,7 +7679,6 @@ declare class StageDebugDelegate {
     private debugCursor;
     private placementGhost;
     private debugLines;
-    private cameraDebugDelegate;
     private debugStateUnsubscribe;
     private focusContextUnregister;
     private entityResolverUnregister;
@@ -7618,7 +7700,7 @@ declare class StageDebugDelegate {
      * point. Without one the tool warns instead of silently doing nothing.
      */
     setAddEntityFactory(factory: AddEntityFactory | null): void;
-    /** Camera used for debug orbit / raycasts (active primary, usually `__debug__`). */
+    /** Camera used for raycasts and gizmos: whichever one is rendering. */
     private getDebugViewCamera;
     private resolveEntity;
     /**
@@ -7630,7 +7712,6 @@ declare class StageDebugDelegate {
     private forEachSelectableEntity;
     /** Copy all stage children into debugMap so raycast/select tools work after enabling debug mid-session. */
     private populateDebugMap;
-    private ensureCameraDebugDelegate;
     /**
      * Activate/deactivate only when `debugState.enabled` actually flips.
      * Hover and selection write to `debugState` every frame, and `activate()`
@@ -7641,9 +7722,9 @@ declare class StageDebugDelegate {
     /** Hand the transform tool its mode whenever the active tool changes. */
     private syncToolMode;
     private syncGrid;
-    /** Initialize DOM listeners and switch rendering to the debug orbit camera. */
+    /** Initialize DOM listeners. The rendering camera stays whatever the editor selected. */
     private activate;
-    /** Tear down visuals and restore the gameplay primary camera. */
+    /** Tear down visuals without changing which camera is rendering. */
     private deactivate;
     private rebindPostProcessing;
     /**
@@ -8345,6 +8426,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. */
@@ -9701,6 +9819,17 @@ declare class ZylemCamera {
      * Disable user-configured orbital controls.
      */
     disableOrbitalControls(): void;
+    /**
+     * Turn on orbit for an editor view camera.
+     *
+     * Locked views keep pan and zoom and freeze the seeded angle. The free
+     * view can rotate. Controls stay allocated after this so a later visit
+     * keeps the panned pose; use {@link setOrbitInteractionEnabled} to ignore
+     * pointer input while another camera is showing.
+     */
+    armEditorOrbit(lockRotation: boolean): void;
+    /** Ignore pointer input without disposing orbit controls or their pose. */
+    disarmEditorOrbit(): void;
     /**
      * Whether user orbital controls are enabled.
      */