@zylem/game-lib 0.8.0 → 0.8.2

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

@@ -551,16 +551,19 @@ export interface CameraFeedOptions {
 // @public
 export class CameraManager {
     constructor();
+    activateDebugCamera(): 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;
     dispose(): void;
     ensureDefaultCamera(): ZylemCamera;
     getCamera(name: string): ZylemCamera | null;
+    get preDebugPrimary(): ZylemCamera | null;
     get primaryCamera(): ZylemCamera | null;
     removeCamera(nameOrRef: string | ZylemCamera): boolean;
     render(scene: Scene): void;
@@ -1282,6 +1285,7 @@ export class FirstPersonPerspective implements CameraPerspective {
     lookAt(target: Vector3, lerpSpeed?: number): void;
     get pitch(): number;
     resetZoom(): void;
+    setEyeHeight(height: number): void;
     setLook(yaw: number, pitch: number): void;
     get yaw(): number;
     zoom(fov: number): void;
@@ -1419,6 +1423,9 @@ export const GameConfigJsonSchema: _sinclair_typebox.TObject<{
             mapping: _sinclair_typebox.TOptional<_sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TArray<_sinclair_typebox.TString>>>;
             pointerLock: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
             sensitivity: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+            lookMode: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"delta">, _sinclair_typebox.TLiteral<"screenCenter">]>>;
+            maxLookDegrees: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+            lookSensitivity: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
         }>>;
         touch: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
             enabled: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TBoolean, _sinclair_typebox.TLiteral<"auto">]>>;
@@ -1666,6 +1673,7 @@ export class GameEntity<O extends GameEntityOptions> extends BaseNode<O> impleme
     physicsWorldRef: unknown;
     // (undocumented)
     resetVelocity: () => void;
+    reveal(): void;
     // (undocumented)
     rotateEuler: (eulerRotation: Vector3) => void;
     // (undocumented)
@@ -1715,6 +1723,10 @@ export class GameEntity<O extends GameEntityOptions> extends BaseNode<O> impleme
     // (undocumented)
     setRotationZ: (z: number) => void;
     _setup(params: SetupContext<this>): void;
+    _spawnInProgress: boolean;
+    _spawnPlacementPending: boolean;
+    _spawnPlacementReady: boolean;
+    _spawnPositionExplicit: boolean;
     _tickActions(delta: number): void;
     // (undocumented)
     transformStore: TransformState;
@@ -1735,6 +1747,8 @@ export type GameEntityOptions = {
     color?: Color;
     size?: Vec3Input;
     position?: Vec3Input;
+    hideUntilPositioned?: boolean;
+    visible?: boolean;
     category?: RenderCategory_2;
     runtime?: RuntimeEntityOptions;
     collision?: Partial<CollisionOptions>;
@@ -1796,6 +1810,9 @@ export const GameInputConfigSchema: _sinclair_typebox.TRecord<_sinclair_typebox.
         mapping: _sinclair_typebox.TOptional<_sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TArray<_sinclair_typebox.TString>>>;
         pointerLock: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
         sensitivity: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+        lookMode: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"delta">, _sinclair_typebox.TLiteral<"screenCenter">]>>;
+        maxLookDegrees: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+        lookSensitivity: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
     }>>;
     touch: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
         enabled: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TBoolean, _sinclair_typebox.TLiteral<"auto">]>>;
@@ -1889,6 +1906,9 @@ export const GameInputPlayerConfigSchema: _sinclair_typebox.TObject<{
         mapping: _sinclair_typebox.TOptional<_sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TArray<_sinclair_typebox.TString>>>;
         pointerLock: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
         sensitivity: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+        lookMode: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"delta">, _sinclair_typebox.TLiteral<"screenCenter">]>>;
+        maxLookDegrees: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+        lookSensitivity: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
     }>>;
     touch: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
         enabled: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TBoolean, _sinclair_typebox.TLiteral<"auto">]>>;
@@ -2085,6 +2105,8 @@ export interface InputGamepad {
     pointer?: {
         x: number;
         y: number;
+        centerX: number;
+        centerY: number;
     };
     // (undocumented)
     shoulders: {
@@ -2258,7 +2280,10 @@ export { mod }
 
 // @public (undocumented)
 export interface MouseConfig {
+    lookMode?: 'delta' | 'screenCenter';
+    lookSensitivity?: number;
     mapping?: MouseMapping;
+    maxLookDegrees?: number;
     pointerLock?: boolean;
     sensitivity?: number;
 }
@@ -2268,6 +2293,9 @@ export const MouseConfigSchema: _sinclair_typebox.TObject<{
     mapping: _sinclair_typebox.TOptional<_sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TArray<_sinclair_typebox.TString>>>;
     pointerLock: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
     sensitivity: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+    lookMode: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"delta">, _sinclair_typebox.TLiteral<"screenCenter">]>>;
+    maxLookDegrees: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+    lookSensitivity: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
 }>;
 
 // @public (undocumented)
@@ -2844,6 +2872,30 @@ export { RuntimeTriggerRegion2DOptions }
 // @public
 export type ScreenAnchor = 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
 
+// @public
+export function screenCenterLookDeltas(nx: number, ny: number, currentYaw: number, currentPitch: number, options?: ScreenCenterLookOptions): {
+    lookX: number;
+    lookY: number;
+};
+
+// @public (undocumented)
+export interface ScreenCenterLookOptions {
+    lookSensitivity?: number;
+    // (undocumented)
+    maxLookDegrees?: number;
+}
+
+// @public
+export interface ScreenCenterLookTargets {
+    // (undocumented)
+    targetPitch: number;
+    // (undocumented)
+    targetYaw: number;
+}
+
+// @public
+export function screenCenterLookTargets(nx: number, ny: number, maxDegrees?: number): ScreenCenterLookTargets;
+
 export { ScreenVisibilityBehavior }
 
 export { ScreenVisibilityChangeContext }
@@ -2968,6 +3020,9 @@ export { Shooter2DStateComponent }
 
 export { Shooter2DTarget }
 
+// @public
+export function shortestAngleDelta(from: number, to: number): number;
+
 export { Simulation }
 
 // Warning: (ae-forgotten-export) The symbol "PhysicsRenderPoseProvider" needs to be exported by the entry point public.d.ts
@@ -2998,6 +3053,8 @@ export class SimulationBody implements PhysicsRenderPoseProvider {
     isSleeping(): boolean;
     // (undocumented)
     linvel(): PhysicsVector3;
+    lockRotations(locked: boolean, _wakeUp?: boolean): void;
+    lockTranslations(locked: boolean, _wakeUp?: boolean): void;
     // (undocumented)
     mass(): number;
     // Warning: (ae-forgotten-export) The symbol "PhysicsQuaternion" needs to be exported by the entry point public.d.ts
@@ -3213,6 +3270,7 @@ export interface StageEntity extends Entity {
     mesh: Mesh;
     // (undocumented)
     name: string;
+    skipRenderPoseSync?: boolean;
     // (undocumented)
     uuid: string;
 }
@@ -3614,6 +3672,12 @@ export function useMouseLook(player: InputPlayer, options?: {
     sensitivity?: number;
 }): GameInputConfig;
 
+// @public
+export function useScreenCenterLook(player: InputPlayer, options?: {
+    maxLookDegrees?: number;
+    lookSensitivity?: number;
+}): GameInputConfig;
+
 // @public
 export function usesManagedRenderPath(options?: RenderCategoryOptions | null): boolean;
 
@@ -4528,16 +4592,16 @@ export class ZylemZone extends GameEntity<ZylemZoneOptions> implements Collision
 
 // Warnings were encountered during analysis:
 //
-// dist/entity-BdSI8CL3.d.ts:406:5 - (ae-forgotten-export) The symbol "RenderCategory_2" needs to be exported by the entry point public.d.ts
-// dist/entity-BdSI8CL3.d.ts:407:5 - (ae-forgotten-export) The symbol "RuntimeEntityOptions" needs to be exported by the entry point public.d.ts
-// dist/entity-BdSI8CL3.d.ts:408:5 - (ae-forgotten-export) The symbol "CollisionOptions" needs to be exported by the entry point public.d.ts
-// dist/entity-BdSI8CL3.d.ts:409:5 - (ae-forgotten-export) The symbol "MaterialOptions" needs to be exported by the entry point public.d.ts
-// dist/entity-BdSI8CL3.d.ts:417:9 - (ae-forgotten-export) The symbol "IBuilder" needs to be exported by the entry point public.d.ts
-// dist/entity-BdSI8CL3.d.ts:417:9 - (ae-forgotten-export) The symbol "EntityMeshBuilder" needs to be exported by the entry point public.d.ts
-// dist/entity-BdSI8CL3.d.ts:418:9 - (ae-forgotten-export) The symbol "EntityCollisionBuilder" needs to be exported by the entry point public.d.ts
-// dist/entity-BdSI8CL3.d.ts:419:9 - (ae-forgotten-export) The symbol "MaterialBuilder" needs to be exported by the entry point public.d.ts
-// dist/game-C1FHVqXl.d.ts:908:5 - (ae-forgotten-export) The symbol "StageAssetLoaderConfig" needs to be exported by the entry point public.d.ts
-// dist/game-C1FHVqXl.d.ts:1520:5 - (ae-forgotten-export) The symbol "StageInterface" needs to be exported by the entry point public.d.ts
+// dist/entity-BGEq1yfC.d.ts:423:5 - (ae-forgotten-export) The symbol "RenderCategory_2" needs to be exported by the entry point public.d.ts
+// dist/entity-BGEq1yfC.d.ts:424:5 - (ae-forgotten-export) The symbol "RuntimeEntityOptions" needs to be exported by the entry point public.d.ts
+// dist/entity-BGEq1yfC.d.ts:425:5 - (ae-forgotten-export) The symbol "CollisionOptions" needs to be exported by the entry point public.d.ts
+// dist/entity-BGEq1yfC.d.ts:426:5 - (ae-forgotten-export) The symbol "MaterialOptions" needs to be exported by the entry point public.d.ts
+// dist/entity-BGEq1yfC.d.ts:434:9 - (ae-forgotten-export) The symbol "IBuilder" needs to be exported by the entry point public.d.ts
+// dist/entity-BGEq1yfC.d.ts:434:9 - (ae-forgotten-export) The symbol "EntityMeshBuilder" needs to be exported by the entry point public.d.ts
+// dist/entity-BGEq1yfC.d.ts:435:9 - (ae-forgotten-export) The symbol "EntityCollisionBuilder" needs to be exported by the entry point public.d.ts
+// dist/entity-BGEq1yfC.d.ts:436:9 - (ae-forgotten-export) The symbol "MaterialBuilder" needs to be exported by the entry point public.d.ts
+// dist/game-DbqBQiFC.d.ts:937:5 - (ae-forgotten-export) The symbol "StageAssetLoaderConfig" needs to be exported by the entry point public.d.ts
+// dist/game-DbqBQiFC.d.ts:1549:5 - (ae-forgotten-export) The symbol "StageInterface" needs to be exported by the entry point public.d.ts
 
 // (No @packageDocumentation comment for this package)
 

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

@@ -518,6 +518,12 @@ declare interface BaseCollisionOptions {
     collisionType?: string;
     /** Allowed collision types for filtering */
     collisionFilter?: string[];
+    /** Gravity scale applied at body spawn (no live setter FFI; default 1). */
+    gravityScale?: number;
+    /** Lock rotation axes at body spawn: `true` for all, or per-axis tuple. */
+    lockRotations?: LockAxesInput;
+    /** Lock translation axes at body spawn: `true` for all, or per-axis tuple. */
+    lockTranslations?: LockAxesInput;
 }
 
 /**
@@ -801,6 +807,10 @@ export declare class CameraManager {
     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;
     /** Reference to the shared renderer manager */
     private _rendererManager;
     /** Scene reference */
@@ -820,6 +830,10 @@ export declare class CameraManager {
      * Get the debug camera.
      */
     get debugCamera(): ZylemCamera | null;
+    /**
+     * Gameplay primary camera that was active before debug mode was enabled.
+     */
+    get preDebugPrimary(): ZylemCamera | null;
     /**
      * Get all registered cameras.
      */
@@ -863,6 +877,16 @@ export declare class CameraManager {
      * Also creates the debug camera.
      */
     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.
+     */
+    activateDebugCamera(): boolean;
+    /**
+     * Restore the gameplay primary camera that was active before
+     * {@link activateDebugCamera}.
+     */
+    deactivateDebugCamera(): boolean;
     /**
      * Update all active cameras' controllers.
      */
@@ -884,8 +908,14 @@ export declare class CameraManager {
     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;
     /**
      * Resolve a camera from a name or reference.
      */
@@ -1157,6 +1187,9 @@ export declare function clearGlobalSubscriptions(): void;
 declare class CollisionBuilder {
     static: boolean;
     sensor: boolean;
+    gravityScale?: number;
+    lockRotations?: LockAxesInput;
+    lockTranslations?: LockAxesInput;
     build(options: Partial<CollisionOptions>): [SimulationBodyDefinition, SimulationColliderDefinition];
     withCollision(collisionOptions: Partial<CollisionOptions>): this;
     collider(options: CollisionOptions): SimulationColliderDefinition;
@@ -1214,6 +1247,12 @@ declare interface CollisionOptions {
     position?: Vec3Input;
     collisionType?: string;
     collisionFilter?: string[];
+    /** Gravity scale applied at body spawn (no live setter FFI; default 1). */
+    gravityScale?: number;
+    /** Lock rotation axes at body spawn: `true` for all, or per-axis tuple. */
+    lockRotations?: LockAxesInput;
+    /** Lock translation axes at body spawn: `true` for all, or per-axis tuple. */
+    lockTranslations?: LockAxesInput;
 }
 
 declare type CollisionPhase = 'enter' | 'stay';
@@ -1385,8 +1424,10 @@ export declare function createEntity<T extends GameEntity<any>, CreateOptions ex
  * const asteroidFactory = createEntityFactory(asteroidTemplate);
  * const asteroids = asteroidFactory.generate(10);
  *
- * asteroids.forEach((asteroid, i) => {
- *     asteroid.setPosition(Math.random() * 20 - 10, Math.random() * 15 - 7.5, 0);
+ * asteroids.forEach((asteroid) => {
+ *     asteroid.onSetup(({ me }) => {
+ *         me.setPosition(Math.random() * 20 - 10, Math.random() * 15 - 7.5, 0);
+ *     });
  *     stage.add(asteroid);
  * });
  * ```
@@ -2188,6 +2229,8 @@ export declare class FirstPersonPerspective implements CameraPerspective {
     look(deltaYaw: number, deltaPitch: number): void;
     /** Set absolute yaw and pitch. Pitch is clamped to the configured limit. */
     setLook(yaw: number, pitch: number): void;
+    /** Set eye height above the followed target (used when syncing from FirstPersonBehavior). */
+    setEyeHeight(height: number): void;
     /** Current yaw in radians. */
     get yaw(): number;
     /** Current pitch in radians. */
@@ -2502,6 +2545,9 @@ export declare const GameConfigJsonSchema: _sinclair_typebox.TObject<{
             mapping: _sinclair_typebox.TOptional<_sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TArray<_sinclair_typebox.TString>>>;
             pointerLock: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
             sensitivity: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+            lookMode: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"delta">, _sinclair_typebox.TLiteral<"screenCenter">]>>;
+            maxLookDegrees: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+            lookSensitivity: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
         }>>;
         touch: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
             enabled: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TBoolean, _sinclair_typebox.TLiteral<"auto">]>>;
@@ -2709,6 +2755,14 @@ export declare class GameEntity<O extends GameEntityOptions> extends BaseNode<O>
     private trackAddedComponents;
     private trackedComponents;
     transformStore: TransformState;
+    /** Hide render target until spawn placement is confirmed. */
+    _spawnPlacementPending: boolean;
+    /** Author passed `position` in create options. */
+    _spawnPositionExplicit: boolean;
+    /** setPosition / setPose assigned a spawn placement during this spawn. */
+    _spawnPlacementReady: boolean;
+    /** True while {@link StageEntityDelegate.spawnEntity} is running for this entity. */
+    _spawnInProgress: boolean;
     moveX: (delta: number) => void;
     moveY: (delta: number) => void;
     moveZ: (delta: number) => void;
@@ -2741,6 +2795,9 @@ export declare class GameEntity<O extends GameEntityOptions> extends BaseNode<O>
     setRotation: (x: number, y: number, z: number) => void;
     getRotation: () => any;
     constructor();
+    private wrapSpawnPlacementMutators;
+    /** Make the entity visible, clearing spawn placement pending state. */
+    reveal(): void;
     /**
      * Read the entity's pose from the wasm simulation. Returns `null` when
      * the entity has not been spawned into the runtime yet.
@@ -2896,6 +2953,17 @@ export declare type GameEntityOptions = {
     color?: Color;
     size?: Vec3Input;
     position?: Vec3Input;
+    /**
+     * Spawn visibility behavior:
+     * - `undefined` (default): hidden while `spawnEntity` runs, revealed once
+     *   the spawn finalizes — even if no position was assigned.
+     * - `true` (strict): stays hidden until the first `setPosition`/`setPose`,
+     *   for spawner patterns that place the entity frames after spawn.
+     * - `false`: never hidden during spawn.
+     */
+    hideUntilPositioned?: boolean;
+    /** Explicit render visibility. When false, entity stays hidden until {@link GameEntity.reveal}. */
+    visible?: boolean;
     /** Render path: `environment` (bundle), `pack` (instanced), or `none` (default). */
     category?: RenderCategory_2;
     runtime?: RuntimeEntityOptions;
@@ -2953,6 +3021,9 @@ export declare const GameInputConfigSchema: _sinclair_typebox.TRecord<_sinclair_
         mapping: _sinclair_typebox.TOptional<_sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TArray<_sinclair_typebox.TString>>>;
         pointerLock: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
         sensitivity: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+        lookMode: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"delta">, _sinclair_typebox.TLiteral<"screenCenter">]>>;
+        maxLookDegrees: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+        lookSensitivity: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
     }>>;
     touch: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
         enabled: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TBoolean, _sinclair_typebox.TLiteral<"auto">]>>;
@@ -3041,6 +3112,9 @@ export declare const GameInputPlayerConfigSchema: _sinclair_typebox.TObject<{
         mapping: _sinclair_typebox.TOptional<_sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TArray<_sinclair_typebox.TString>>>;
         pointerLock: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
         sensitivity: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+        lookMode: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"delta">, _sinclair_typebox.TLiteral<"screenCenter">]>>;
+        maxLookDegrees: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+        lookSensitivity: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
     }>>;
     touch: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
         enabled: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TBoolean, _sinclair_typebox.TLiteral<"auto">]>>;
@@ -3297,8 +3371,14 @@ export declare interface InputGamepad {
     };
     /** Screen-space cursor position (normalized 0..1). Only populated by MouseProvider. */
     pointer?: {
+        /** Window-normalized X (0 = left, 1 = right). */
         x: number;
+        /** Window-normalized Y (0 = top, 1 = bottom). */
         y: number;
+        /** Canvas-center-relative X (−1 = left edge, +1 = right edge). */
+        centerX: number;
+        /** Canvas-center-relative Y (−1 = top edge, +1 = bottom edge). */
+        centerY: number;
     };
 }
 
@@ -3590,6 +3670,9 @@ export declare type LoadingEvent = {
     current?: number;
 };
 
+/** Per-axis lock input: `true` locks all axes, or pass an [x, y, z] tuple. */
+declare type LockAxesInput = boolean | readonly [boolean, boolean, boolean];
+
 declare class MaterialBuilder {
     static sharedMaterialMap: Map<MaterialCacheKey, SharedMaterialMapEntry>;
     /**
@@ -3688,6 +3771,12 @@ export declare interface MouseConfig {
     pointerLock?: boolean;
     /** Sensitivity multiplier for mouse movement (default 0.002). */
     sensitivity?: number;
+    /** How mouse position drives look: delta (movement) or screenCenter (cursor offset from viewport center). */
+    lookMode?: 'delta' | 'screenCenter';
+    /** Max yaw/pitch in degrees when `lookMode` is `screenCenter` (default 45). */
+    maxLookDegrees?: number;
+    /** Screen-center follow rate toward cursor-mapped target (lower = snappier; default 2). */
+    lookSensitivity?: number;
 }
 
 /** Mouse input configuration. */
@@ -3695,6 +3784,9 @@ export declare const MouseConfigSchema: _sinclair_typebox.TObject<{
     mapping: _sinclair_typebox.TOptional<_sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TArray<_sinclair_typebox.TString>>>;
     pointerLock: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
     sensitivity: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+    lookMode: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"delta">, _sinclair_typebox.TLiteral<"screenCenter">]>>;
+    maxLookDegrees: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+    lookSensitivity: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
 }>;
 
 export declare type MouseMapping = Record<string, string[]>;
@@ -4832,6 +4924,41 @@ declare interface SceneState {
  */
 export declare type ScreenAnchor = 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
 
+/**
+ * Computes WASM look deltas that drive current yaw/pitch toward screen-center targets.
+ *
+ * `lookSensitivity` controls follow rate toward the cursor-mapped target (lower = snappier).
+ * WASM applies its own `look_sensitivity` multiplier to these deltas.
+ */
+export declare function screenCenterLookDeltas(nx: number, ny: number, currentYaw: number, currentPitch: number, options?: ScreenCenterLookOptions): {
+    lookX: number;
+    lookY: number;
+};
+
+export declare interface ScreenCenterLookOptions {
+    maxLookDegrees?: number;
+    /** How fast cursor position pulls yaw/pitch toward target (lower = snappier). @default 2 */
+    lookSensitivity?: number;
+}
+
+/**
+ * Maps canvas-center-relative pointer offset to absolute yaw/pitch targets.
+ * Used with screen-center mouse look (free cursor, no pointer lock).
+ */
+export declare interface ScreenCenterLookTargets {
+    targetYaw: number;
+    targetPitch: number;
+}
+
+/**
+ * Converts normalized pointer offset from viewport center to look angles.
+ *
+ * @param nx Horizontal offset from center (−1 = left edge, +1 = right edge).
+ * @param ny Vertical offset from center (−1 = top edge, +1 = bottom edge).
+ * @param maxDegrees Maximum yaw/pitch at viewport edges (default 45).
+ */
+export declare function screenCenterLookTargets(nx: number, ny: number, maxDegrees?: number): ScreenCenterLookTargets;
+
 export { ScreenVisibilityBehavior }
 
 export { ScreenVisibilityChangeContext }
@@ -5023,6 +5150,9 @@ export { Shooter2DStateComponent }
 
 export { Shooter2DTarget }
 
+/** Shortest signed angle from `from` to `to` in radians. */
+export declare function shortestAngleDelta(from: number, to: number): number;
+
 declare function shortHash(objString: string): string;
 
 export { Simulation }
@@ -5034,7 +5164,19 @@ export declare class SimulationBody implements PhysicsRenderPoseProvider {
     private readonly poseScratch;
     private readonly renderScratch;
     private readonly previousScratch;
+    /**
+     * First step at which the shared render buffers are coherent for this
+     * body. After a spawn or an explicit pose write (teleport), the current
+     * slot isn't written until the next fixed step and the previous-step
+     * copy lags one more; interpolating across that gap would sweep the
+     * mesh from a stale pose (often the origin). Until this step is
+     * reached, render reads collapse to the live body pose.
+     */
+    private interpolationValidAfterStep;
     constructor(simulation: Simulation, handle: EntityHandle, clock: SimulationStepClock);
+    /** Suppress interpolation until the render buffers catch up. */
+    private markPoseDiscontinuity;
+    private isInterpolationStale;
     translation(): PhysicsVector3;
     rotation(): PhysicsQuaternion;
     linvel(): PhysicsVector3;
@@ -5044,6 +5186,22 @@ export declare class SimulationBody implements PhysicsRenderPoseProvider {
     setLinvel(velocity: PhysicsVector3, _wakeUp?: boolean): void;
     setAngvel(velocity: PhysicsVector3, _wakeUp?: boolean): void;
     applyImpulse(impulse: PhysicsVector3, _wakeUp?: boolean): void;
+    /**
+     * Rotation locks are fixed at body-creation time in the wasm runtime
+     * (`SimulationBodyDefinition.lockRotation`); there is no live setter FFI
+     * yet. Accepted for Rapier compat — when locking, the angular velocity is
+     * zeroed to approximate the intent. Prefer lock flags on the body
+     * definition at spawn time.
+     */
+    lockRotations(locked: boolean, _wakeUp?: boolean): void;
+    /**
+     * Translation locks are fixed at body-creation time in the wasm runtime
+     * (`SimulationBodyDefinition.lockTranslation`); there is no live setter
+     * FFI yet. Accepted for Rapier compat — when locking, the linear velocity
+     * is zeroed to approximate the intent. Prefer lock flags on the body
+     * definition at spawn time.
+     */
+    lockTranslations(locked: boolean, _wakeUp?: boolean): void;
     /**
      * Damping is fixed at body-creation time in the wasm runtime; there is no
      * live setter FFI yet, so this is accepted (for `MoveableBodyLike`
@@ -5377,15 +5535,18 @@ declare class StageDebugDelegate {
     private debugStateUnsubscribe;
     private focusContextUnregister;
     constructor(stage: ZylemStage, options?: StageDebugDelegateOptions);
+    /** Camera used for debug orbit / raycasts (active primary, usually `__debug__`). */
+    private getDebugViewCamera;
     private resolveEntity;
     /** Copy all stage children into debugMap so raycast/select tools work after enabling debug mid-session. */
     private populateDebugMap;
     private ensureCameraDebugDelegate;
     private syncWithDebugState;
-    /** Initialize DOM listeners and camera debug delegate when debug is turned on. */
+    /** Initialize DOM listeners and switch rendering to the debug orbit camera. */
     private activate;
-    /** Tear down visuals and camera debug delegate when debug is turned off. */
+    /** Tear down visuals and restore the gameplay primary camera. */
     private deactivate;
+    private rebindPostProcessing;
     private initDebugVisuals;
     private disposeDebugVisuals;
     update(): void;
@@ -5410,6 +5571,12 @@ export declare interface StageEntity extends Entity {
     instanceId: number;
     isInstanced?: boolean;
     isBundled?: boolean;
+    /**
+     * When true, `syncRenderPoses` leaves the entity's Three.js transform alone.
+     * Used for camera-parented viewmodels so physics pose sync cannot overwrite
+     * the local offset.
+     */
+    skipRenderPoseSync?: boolean;
     controlledRotation: boolean;
     name: string;
     markedForRemoval: boolean;
@@ -6355,6 +6522,16 @@ export declare function useMouseLook(player: InputPlayer, options?: {
     sensitivity?: number;
 }): GameInputConfig;
 
+/**
+ * Enables screen-center mouse look (free cursor, no pointer lock).
+ * Cursor offset from the game canvas center maps to yaw/pitch up to `maxLookDegrees`.
+ * @example stage.setInputConfiguration(useScreenCenterLook('p1'));
+ */
+export declare function useScreenCenterLook(player: InputPlayer, options?: {
+    maxLookDegrees?: number;
+    lookSensitivity?: number;
+}): GameInputConfig;
+
 /** Whether the entity opts into a managed render path (bundle or instanced). */
 export declare function usesManagedRenderPath(options?: RenderCategoryOptions | null): boolean;
 
@@ -6961,6 +7138,8 @@ declare class ZylemCamera {
     private _useOrbitalControls;
     /** When true, debug-mode orbital controls are not attached to this camera. */
     _skipDebugOrbit: boolean;
+    /** Dedicated debug-view camera (e.g. `__debug__`); uses simplified orbit path. */
+    isDebugViewCamera: boolean;
     /** Reference to the shared renderer manager (set during setup). */
     private _rendererManager;
     /** Elapsed time tracker for CameraContext. */
@@ -7047,6 +7226,16 @@ declare class ZylemCamera {
      * Dispose camera resources.
      */
     destroy(): void;
+    /**
+     * Set the default orbit target for debug mode (e.g. origin anchor).
+     */
+    setDefaultOrbitTarget(target: Object3D): void;
+    /**
+     * Seed the debug orbit camera to an initial pose.
+     */
+    seedDebugOrbitPose(position: Vector3, lookAt: Vector3): void;
+    /** Whether the debug orbit camera has received its initial pose. */
+    isDebugOrbitPoseSeeded(): boolean;
     /**
      * Attach a delegate to react to debug state changes.
      * Skipped when _skipDebugOrbit is true so the pipeline always runs.