@zylem/game-lib 0.9.2 → 0.9.4

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

@@ -681,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;
@@ -2154,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;
@@ -6205,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-DBt7iVu4.d.ts:258:5 - (ae-forgotten-export) The symbol "StageInterface" needs to be exported by the entry point public.d.ts
+// dist/stage-PBmwT5-Y.d.ts:1150: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

@@ -458,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.
@@ -958,28 +959,40 @@ 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;
+    /** Which editor views pan in screen space (the view plane). */
+    private _screenSpacePanIds;
+    /** 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.
      */
@@ -988,14 +1001,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.
      */
@@ -1012,13 +1021,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;
@@ -1036,19 +1047,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.
      */
@@ -1068,16 +1087,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.
      */
@@ -2694,6 +2716,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>;
@@ -3322,8 +3357,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
  */
@@ -3490,6 +3526,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.
@@ -3542,6 +3580,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: {
@@ -7620,7 +7681,6 @@ declare class StageDebugDelegate {
     private debugCursor;
     private placementGhost;
     private debugLines;
-    private cameraDebugDelegate;
     private debugStateUnsubscribe;
     private focusContextUnregister;
     private entityResolverUnregister;
@@ -7642,7 +7702,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;
     /**
@@ -7654,7 +7714,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()`
@@ -7665,9 +7724,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;
     /**
@@ -9762,6 +9821,18 @@ 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. Screen-space
+     * pan keeps those drags on the view plane: side moves on Y and Z, top on
+     * X and Z. 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, screenSpacePan?: boolean): void;
+    /** Ignore pointer input without disposing orbit controls or their pose. */
+    disarmEditorOrbit(): void;
     /**
      * Whether user orbital controls are enabled.
      */