@zylem/game-lib 0.6.3 → 0.6.4

package/dist/main.d.ts

@@ -1,35 +1,49 @@
-import { G as Game } from './core-DAkskq6Y.js';
-export { V as Vect3, c as createGame, g as gameConfig, v as vessel } from './core-DAkskq6Y.js';
-import { G as GameInputConfig } from './stage-types-BFsm3qsZ.js';
-export { a as StageOptions, Z as ZylemGameConfig, d as createDisk, c as createStage } from './stage-types-BFsm3qsZ.js';
-import { S as StageBlueprint } from './blueprints-BWGz8fII.js';
-export { e as entitySpawner } from './blueprints-BWGz8fII.js';
-export { C as CameraManager, e as CameraOptions, c as CameraWrapper, P as PerspectiveType, f as Perspectives, g as RendererType, V as Viewport, h as ZylemRenderer, d as createCamera, i as isWebGPUSupported } from './camera-B5e4c78l.js';
-export { A as ACTOR_TYPE, B as BOX_TYPE, C as CONE_TYPE, m as CYLINDER_TYPE, o as PILL_TYPE, P as PLANE_TYPE, k as PYRAMID_TYPE, R as RECT_TYPE, a as SPHERE_TYPE, S as SPRITE_TYPE, T as TEXT_TYPE, g as ZONE_TYPE, e as ZylemBox, v as createActor, q as createBox, y as createCone, D as createCylinder, E as createPill, t as createPlane, z as createPyramid, x as createRect, r as createSphere, s as createSprite, w as createText, u as createZone } from './entities-DC9ce_vx.js';
-import { I as GameEntity, P as GameEntityOptions, V as Vec3, R as MaterialOptions, W as MoveableEntity, N as BaseNode, X as InputPlayer } from './entity-BpbZqg19.js';
-export { A as Action, a6 as CollisionComponent, af as EntityConfigPayload, ab as EntityEvents, a7 as EventEmitterDelegate, aa as GameEvents, ac as GameLoadingPayload, O as LoadingEvent, L as SetupContext, ae as StageConfigPayload, Q as StageEvents, ad as StateDispatchPayload, U as UpdateContext, a9 as ZylemEvents, Z as ZylemShader, ag as ZylemShaderObject, ah as ZylemTSLShader, _ as boxCollision, a0 as coneCollision, Y as create, a2 as cylinderCollision, aj as isGLSLShader, ai as isTSLShader, m as move, a3 as pillCollision, a4 as planeCollision, a1 as pyramidCollision, g as resetVelocity, p as rotateInDirection, $ as sphereCollision, a5 as zoneCollision, a8 as zylemEventBus } from './entity-BpbZqg19.js';
-import { Color, Mesh, Vector2 } from 'three';
+import { G as Game, D as DeviceProfile } from './core-CARRaS55.js';
+export { A as AspectRatio, e as AspectRatioValue, a as GameConfigLike, b as GameDeviceConfig, R as ResolutionInput, d as ResolveGameConfigRuntime, i as RetroPreset, j as RetroPresetKey, k as RetroResolution, V as Vect3, c as createGame, g as gameConfig, f as getDisplayAspect, h as getPresetResolution, p as parseResolution, v as vessel } from './core-CARRaS55.js';
+import { G as GameInputConfig } from './stage-types-C19IhuzA.js';
+export { a as StageOptions, Z as ZylemGameConfig, d as createDisk, c as createStage } from './stage-types-C19IhuzA.js';
+import { S as StageBlueprint } from './blueprints-DmbK2dki.js';
+export { e as entitySpawner } from './blueprints-DmbK2dki.js';
+import { b as CameraBehavior, a as CameraWrapper, F as FirstPersonPerspective } from './camera-4XO5gbQH.js';
+export { m as CameraAction, k as CameraContext, C as CameraManager, d as CameraOptions, l as CameraPerspective, o as CameraPipeline, n as CameraPipelineState, h as CameraPose, u as FirstPersonOptions, t as Fixed2DOptions, q as Fixed2DPerspective, v as PerspectiveOptions, P as PerspectiveType, e as Perspectives, j as PoseDelta, f as RendererType, s as ThirdPersonOptions, p as ThirdPersonPerspective, T as TransformLike, V as Viewport, g as ZylemRenderer, c as createCamera, r as createPerspective, i as isWebGPUSupported } from './camera-4XO5gbQH.js';
+import { Vector3, Color, Mesh, Euler, Vector2 } from 'three';
 import * as three from 'three';
 export { three as THREE };
-import { b as BehaviorDescriptor } from './behavior-descriptor-BWNWmIjv.js';
-export { c as BehaviorHandle, d as BehaviorRef, B as BehaviorSystem, a as BehaviorSystemFactory, D as DefineBehaviorConfig, e as defineBehavior } from './behavior-descriptor-BWNWmIjv.js';
-export { B as Behavior, P as PhysicsBodyComponent, m as PlayerInput, p as ThrusterBehavior, q as ThrusterBehaviorOptions, o as ThrusterEntity, j as ThrusterEvent, k as ThrusterFSM, l as ThrusterFSMContext, d as ThrusterInputComponent, n as ThrusterMovementBehavior, b as ThrusterMovementComponent, i as ThrusterState, e as ThrusterStateComponent, T as TransformComponent, a as createPhysicsBodyComponent, g as createThrusterInputComponent, f as createThrusterMovementComponent, h as createThrusterStateComponent, c as createTransformComponent } from './thruster-DhRaJnoL.js';
+import { S as StageEntity } from './entity-Bq_eNEDI.js';
+export { A as ACTOR_TYPE, B as BOX_TYPE, C as CONE_TYPE, m as CYLINDER_TYPE, o as PILL_TYPE, P as PLANE_TYPE, k as PYRAMID_TYPE, R as RECT_TYPE, a as SPHERE_TYPE, S as SPRITE_TYPE, T as TEXT_TYPE, g as ZONE_TYPE, e as ZylemBox, v as createActor, q as createBox, y as createCone, D as createCylinder, E as createPill, t as createPlane, z as createPyramid, x as createRect, r as createSphere, s as createSprite, w as createText, u as createZone } from './entities-ChFirVL9.js';
+import { I as GameEntity, P as GameEntityOptions, V as Vec3, R as MaterialOptions, W as MoveableEntity, O as BaseNode, X as InputPlayer } from './entity-vj-HTjzU.js';
+export { A as Action, a6 as CollisionComponent, af as EntityConfigPayload, ab as EntityEvents, a7 as EventEmitterDelegate, aa as GameEvents, ac as GameLoadingPayload, N as LoadingEvent, L as SetupContext, ae as StageConfigPayload, Q as StageEvents, ad as StateDispatchPayload, U as UpdateContext, a9 as ZylemEvents, Z as ZylemShader, ag as ZylemShaderObject, ah as ZylemTSLShader, _ as boxCollision, a0 as coneCollision, Y as create, a2 as cylinderCollision, aj as isGLSLShader, ai as isTSLShader, m as move, a3 as pillCollision, a4 as planeCollision, a1 as pyramidCollision, g as resetVelocity, p as rotateInDirection, $ as sphereCollision, a5 as zoneCollision, a8 as zylemEventBus } from './entity-vj-HTjzU.js';
+import { c as BehaviorDescriptor } from './behavior-descriptor-BXnVR8Ki.js';
+export { d as BehaviorHandle, e as BehaviorRef, B as BehaviorSystem, b as BehaviorSystemFactory, D as DefineBehaviorConfig, f as defineBehavior } from './behavior-descriptor-BXnVR8Ki.js';
+import { T as ThrusterInputComponent } from './thruster-23lzoPZd.js';
+export { B as Behavior, P as PhysicsBodyComponent, m as PlayerInput, p as ThrusterBehavior, q as ThrusterBehaviorOptions, o as ThrusterEntity, j as ThrusterEvent, k as ThrusterFSM, l as ThrusterFSMContext, n as ThrusterMovementBehavior, d as ThrusterMovementComponent, i as ThrusterState, e as ThrusterStateComponent, a as TransformComponent, b as createPhysicsBodyComponent, g as createThrusterInputComponent, f as createThrusterMovementComponent, h as createThrusterStateComponent, c as createTransformComponent } from './thruster-23lzoPZd.js';
+import { TopDownMovementInputComponent } from './behavior/top-down-movement.js';
+export { TopDownMovementBehavior, TopDownMovementBehaviorOptions, TopDownMovementComponent, TopDownMovementEntity, TopDownMovementHandle, TopDownMovementRuntimeBehavior, TopDownMovementStateComponent, createTopDownMovementComponent, createTopDownMovementInputComponent, createTopDownMovementStateComponent } from './behavior/top-down-movement.js';
+import { Shooter2DSourceEntity, Shooter2DHandle, Shooter2DStageLike } from './behavior/shooter-2d.js';
+export { Shooter2DBehavior, Shooter2DBehaviorOptions, Shooter2DFireArgs, Shooter2DProjectileFactory, Shooter2DStateComponent, Shooter2DTarget, createShooter2DStateComponent } from './behavior/shooter-2d.js';
 export { ScreenWrapBehavior, ScreenWrapEvent, ScreenWrapFSM, ScreenWrapOptions, ScreenWrapState } from './behavior/screen-wrap.js';
+export { ScreenVisibilityBehavior, ScreenVisibilityChangeContext, ScreenVisibilityFSM, ScreenVisibilityHandle, ScreenVisibilityOptions, ScreenVisibilitySize, ScreenVisibilitySnapshot } from './behavior/screen-visibility.js';
 import { WorldBoundary2DHandle } from './behavior/world-boundary-2d.js';
 export { WorldBoundary2DBehavior, WorldBoundary2DBounds, WorldBoundary2DEvent, WorldBoundary2DFSM, WorldBoundary2DHit, WorldBoundary2DHits, WorldBoundary2DOptions, WorldBoundary2DPosition, WorldBoundary2DState, computeWorldBoundary2DHits, hasAnyWorldBoundary2DHit } from './behavior/world-boundary-2d.js';
+import { WorldBoundary3DHandle } from './behavior/world-boundary-3d.js';
+export { WorldBoundary3DBehavior, WorldBoundary3DBounds, WorldBoundary3DEvent, WorldBoundary3DFSM, WorldBoundary3DHit, WorldBoundary3DHits, WorldBoundary3DOptions, WorldBoundary3DPosition, WorldBoundary3DState, computeWorldBoundary3DHits, hasAnyWorldBoundary3DHit } from './behavior/world-boundary-3d.js';
 import { Ricochet2DHandle } from './behavior/ricochet-2d.js';
 export { Ricochet2DBehavior, Ricochet2DCollisionContext, Ricochet2DEvent, Ricochet2DFSM, Ricochet2DOptions, Ricochet2DResult, Ricochet2DState, RicochetCallback } from './behavior/ricochet-2d.js';
+import { Ricochet3DHandle } from './behavior/ricochet-3d.js';
+export { Ricochet3DBehavior, Ricochet3DCallback, Ricochet3DCollisionContext, Ricochet3DEvent, Ricochet3DFSM, Ricochet3DOptions, Ricochet3DResult, Ricochet3DState } from './behavior/ricochet-3d.js';
 export { Platformer3DBehavior, Platformer3DBehaviorOptions, Platformer3DContext, Platformer3DEntity, Platformer3DEvent, Platformer3DFSM, Platformer3DInputComponent, Platformer3DMovementBehavior, Platformer3DMovementComponent, Platformer3DState, Platformer3DStateComponent, PlatformerCollisionContext, createPlatformer3DInputComponent, createPlatformer3DMovementComponent, createPlatformer3DStateComponent } from './behavior/platformer-3d.js';
-export { c as callFunc, d as delay, m as moveBy, a as moveTo, o as onPress, b as onRelease, p as parallel, e as repeat, f as repeatForever, r as rotateBy, s as sequence, t as throttle } from './composition-DrzFrbqI.js';
+import { S as SyncStateMachine } from './sync-state-machine-CZyspBpj.js';
+export { JumpConfig2D, JumpContext2D, JumpInput2D, JumpState2D, Jumper2D, Jumper2DBehavior, Jumper2DBehaviorOptions, Jumper2DEntity, Jumper2DEvent, Jumper2DFSM, Jumper2DState, Jumper2DTickEvent, Jumper2DTickResult, createJumpConfig2D, createJumpInput2D, createJumpState2D } from './behavior/jumper-2d.js';
+export { c as callFunc, d as delay, m as moveBy, a as moveTo, o as onPress, b as onRelease, p as parallel, e as repeat, f as repeatForever, r as rotateBy, s as sequence, t as throttle } from './composition-BASvMKrW.js';
 export { Howl } from 'howler';
 import * as RAPIER from '@dimforge/rapier3d-compat';
 export { RAPIER };
-export { g as globalChange, a as globalChanges, v as variableChange, b as variableChanges } from './global-change-Dc8uCKi2.js';
-export { S as StageEntity } from './entity-Bq_eNEDI.js';
+export { g as globalChange, a as globalChanges, v as variableChange, b as variableChanges } from './global-change-2JvMaz44.js';
 export { Fn, float, time, uniform, uv, vec3, vec4 } from 'three/tsl';
 import 'bitecs';
-import './world-Be5m1XC1.js';
+import './world-DfgxoNMt.js';
 import './entity-types-DAu8sGJH.js';
+import './physics-pose-DCc4oE44.js';
 import '@sinclair/typebox';
 import 'three/webgpu';
 import 'three/examples/jsm/postprocessing/EffectComposer.js';
@@ -65,6 +79,75 @@ declare const StageManager: {
     preloadNext(stageId: string, loadStaticStage?: (id: string) => Promise<StageBlueprint>): Promise<void>;
 };
 
+/**
+ * Options for the followTarget behavior.
+ */
+interface FollowTargetOptions {
+    /** Key in CameraContext.targets to follow. Default 'primary'. */
+    targetKey?: string;
+    /** Position offset from the target. Default (0, 0, 0). */
+    offset?: Vector3;
+    /**
+     * Per-frame interpolation factor (0-1). Controls how quickly the
+     * pose converges on the target each frame.
+     * 1 = instant snap, lower = smoother follow.
+     * Default 0.1.
+     */
+    lerpFactor?: number;
+}
+/**
+ * A simple follow behavior that moves the camera pose toward a target's position + offset.
+ *
+ * This behavior modifies only the position (and lookAt) of the incoming pose,
+ * leaving rotation/fov/zoom to the perspective or other behaviors.
+ *
+ * @example
+ * ```ts
+ * camera.addBehavior('follow', createFollowTarget({ targetKey: 'player', offset: new Vector3(0, 3, 8) }));
+ * ```
+ */
+declare function createFollowTarget(options?: FollowTargetOptions): CameraBehavior;
+
+/**
+ * Options for setCameraFeed.
+ */
+interface CameraFeedOptions {
+    /** Render target width in pixels. Only used when the camera does not
+     *  already have a render target. @default 512 */
+    width?: number;
+    /** Render target height in pixels. Only used when the camera does not
+     *  already have a render target. @default 512 */
+    height?: number;
+}
+/**
+ * Display a camera's live feed on an entity's mesh surface.
+ *
+ * This is the primary user-facing function for "jumbotron", security-camera,
+ * or broadcast-style effects. It ensures the camera has an offscreen render
+ * target and replaces the entity's mesh material with one that shows the
+ * camera's rendered output.
+ *
+ * @param entity  The entity whose mesh will display the camera feed.
+ * @param camera  The camera whose view will be rendered to the texture.
+ * @param options Optional dimensions for the render target.
+ *
+ * @example
+ * ```ts
+ * const feedCam = createCamera({
+ *   perspective: Perspectives.ThirdPerson,
+ *   position: new Vector3(0, 30, 60),
+ *   target: new Vector3(0, 0, 0),
+ *   renderToTexture: { width: 1024, height: 576 },
+ * });
+ *
+ * const screen = createBox({ size: { x: 16, y: 9, z: 0.2 } });
+ * screen.onSetup(({ me }) => {
+ *   setCameraFeed(me, feedCam);
+ * });
+ * ```
+ */
+declare function setCameraFeed(entity: StageEntity, camera: CameraWrapper, options?: CameraFeedOptions): void;
+
 /**
  * Factory interface for generating entity copies
  */
@@ -184,6 +267,515 @@ declare function pillMesh(opts?: PillMeshOptions): Mesh;
  */
 declare function useBehavior<E extends GameEntity<any>, O extends Record<string, any>, H extends Record<string, any>, I>(entity: E, descriptor: BehaviorDescriptor<O, H, I>, options?: Partial<O>): E & I;
 
+/**
+ * First Person Controller ECS Components
+ *
+ * Components for first-person movement and camera control:
+ * - Movement configuration (walk/run speed, sensitivity, eye height)
+ * - Input intent (WASD movement + mouse look deltas)
+ * - Runtime state (yaw, pitch, speed)
+ */
+interface FirstPersonMovementComponent {
+    /** Base walking speed (units/sec) */
+    walkSpeed: number;
+    /** Sprint/run speed (units/sec) */
+    runSpeed: number;
+    /** Look sensitivity multiplier applied to raw input deltas */
+    lookSensitivity: number;
+    /** Vertical offset above entity position for eye/camera placement */
+    eyeHeight: number;
+}
+declare function createFirstPersonMovementComponent(options?: Partial<FirstPersonMovementComponent>): FirstPersonMovementComponent;
+interface FirstPersonInputComponent {
+    /** Horizontal movement input (-1 to 1, strafe) */
+    moveX: number;
+    /** Forward/backward movement input (-1 to 1) */
+    moveZ: number;
+    /** Horizontal look delta (mouse/stick, raw value before sensitivity) */
+    lookX: number;
+    /** Vertical look delta (mouse/stick, raw value before sensitivity) */
+    lookY: number;
+    /** Sprint button held */
+    sprint: boolean;
+}
+declare function createFirstPersonInputComponent(): FirstPersonInputComponent;
+interface FirstPersonStateComponent {
+    /** Current yaw in radians */
+    yaw: number;
+    /** Current pitch in radians */
+    pitch: number;
+    /** Current movement speed being applied */
+    currentSpeed: number;
+}
+declare function createFirstPersonStateComponent(): FirstPersonStateComponent;
+
+/**
+ * First Person Controller Finite State Machine
+ *
+ * Manages state transitions for first-person movement:
+ * - Idle: Standing still
+ * - Walking: Moving at walk speed
+ * - Running: Moving at run/sprint speed
+ */
+
+/**
+ * First-person movement states
+ */
+declare enum FirstPersonState {
+    Idle = "idle",
+    Walking = "walking",
+    Running = "running"
+}
+/**
+ * Events that trigger state transitions
+ */
+declare enum FirstPersonEvent {
+    Walk = "walk",
+    Run = "run",
+    Stop = "stop"
+}
+/**
+ * Context for the FSM
+ */
+interface FirstPersonContext {
+    input: FirstPersonInputComponent;
+    state: FirstPersonStateComponent;
+}
+/**
+ * First Person Controller FSM
+ */
+declare class FirstPersonFSM {
+    private ctx;
+    machine: SyncStateMachine<FirstPersonState, FirstPersonEvent, never>;
+    constructor(ctx: FirstPersonContext);
+    /** Get the current state */
+    getState(): FirstPersonState;
+    /** Dispatch an event to the FSM */
+    dispatch(event: FirstPersonEvent): void;
+    /** Get the current yaw from context */
+    getYaw(): number;
+    /** Get the current pitch from context */
+    getPitch(): number;
+    /**
+     * Update FSM based on current input and state.
+     */
+    update(input: FirstPersonInputComponent, state: FirstPersonStateComponent): void;
+}
+
+/**
+ * First Person Controller Behavior System
+ *
+ * Handles first-person camera control and movement:
+ * - Reads input component for WASD movement and mouse look deltas
+ * - Drives a FirstPersonPerspective (yaw/pitch accumulation)
+ * - Writes velocity to transformStore (physics-based movement)
+ * - Syncs camera position from the entity's rigid body each frame
+ * - Positions an optional viewmodel entity relative to the camera
+ */
+
+/**
+ * Viewmodel configuration for an entity that follows the camera.
+ */
+interface ViewmodelConfig {
+    /** The entity whose visual group should be positioned relative to the camera. */
+    entity: any;
+    /** Offset from the eye position in camera-local space (right, down, forward). */
+    offset: Vector3;
+    /** Additional rotation applied to the viewmodel in local space (Euler angles in radians). */
+    rotation?: Euler;
+}
+/**
+ * Entity interface for first-person controller.
+ * Entities with this behavior have these components attached.
+ */
+interface FirstPersonEntity {
+    uuid: string;
+    body: any;
+    transformStore: any;
+    firstPerson: FirstPersonMovementComponent;
+    $fps: FirstPersonInputComponent;
+    firstPersonState: FirstPersonStateComponent;
+}
+/**
+ * First Person Controller Behavior
+ *
+ * Core movement + look system for first-person cameras.
+ * Reads from entity.$fps input component and drives a FirstPersonPerspective.
+ */
+declare class FirstPersonControllerBehavior {
+    private world;
+    private perspectives;
+    private viewmodels;
+    constructor(world: any);
+    /**
+     * Associate a FirstPersonPerspective with an entity (by uuid).
+     * Called once by the descriptor system when the behavior is initialized.
+     */
+    setPerspective(entityUuid: string, perspective: FirstPersonPerspective): void;
+    hasPerspective(entityUuid: string): boolean;
+    /**
+     * Attach a viewmodel (weapon/item) to an entity.
+     * The viewmodel entity's group will be positioned relative to the camera each frame.
+     */
+    setViewmodel(entityUuid: string, config: ViewmodelConfig): void;
+    hasViewmodel(entityUuid: string): boolean;
+    /**
+     * Update one first-person entity.
+     */
+    updateEntity(entity: any, _delta: number): void;
+    /**
+     * Update all first-person entities.
+     */
+    update(delta: number): void;
+    /**
+     * Position a viewmodel entity relative to the camera's eye position and rotation.
+     *
+     * The physics transform system overwrites group.position from the rigid body
+     * each frame, so we must also move the body to keep them in sync.
+     */
+    private positionViewmodel;
+    /** Cleanup */
+    destroy(): void;
+}
+
+/**
+ * First-person controller behavior options (typed for entity.use() autocomplete).
+ */
+interface FirstPersonControllerOptions {
+    /** Base walking speed (default: 8) */
+    walkSpeed?: number;
+    /** Sprint/run speed (default: 16) */
+    runSpeed?: number;
+    /** Look sensitivity multiplier (default: 2) */
+    lookSensitivity?: number;
+    /** Eye height offset above entity position (default: 1.7) */
+    eyeHeight?: number;
+    /** The FirstPersonPerspective to drive (from camera.getPerspective()) */
+    perspective?: FirstPersonPerspective;
+    /** Optional viewmodel (weapon/item) to position relative to the camera */
+    viewmodel?: {
+        entity: any;
+        offset: Vector3;
+        rotation?: Euler;
+    };
+}
+/**
+ * FirstPersonController - typed descriptor for first-person movement and camera control.
+ *
+ * Provides complete first-person controller including:
+ * - WASD movement relative to camera yaw
+ * - Mouse look driving a FirstPersonPerspective
+ * - Optional viewmodel positioning (weapon/item following camera)
+ * - Walk/run state tracking via FSM
+ *
+ * @example
+ * ```typescript
+ * import { FirstPersonController, FirstPersonPerspective, createActor, createCamera, Perspectives } from "@zylem/game-lib";
+ *
+ * const fpsCamera = createCamera({ perspective: Perspectives.FirstPerson, ... });
+ * const fps = fpsCamera.getPerspective<FirstPersonPerspective>();
+ *
+ * const player = createActor({ name: 'player', ... });
+ * const controller = player.use(FirstPersonController, {
+ *   perspective: fps,
+ *   walkSpeed: 8,
+ *   runSpeed: 16,
+ *   lookSensitivity: 2,
+ * });
+ *
+ * // In update loop - write input, behavior handles the rest
+ * player.onUpdate(({ inputs }) => {
+ *   player.$fps.moveX = inputs.p1.axes.Horizontal.value;
+ *   player.$fps.moveZ = inputs.p1.axes.Vertical.value;
+ *   player.$fps.lookX = inputs.p1.axes.SecondaryHorizontal.value;
+ *   player.$fps.lookY = inputs.p1.axes.SecondaryVertical.value;
+ *   player.$fps.sprint = inputs.p1.shoulders.LTrigger.held > 0;
+ * });
+ * ```
+ */
+declare const FirstPersonController: BehaviorDescriptor<FirstPersonControllerOptions, {
+    getState: () => FirstPersonState;
+    getYaw: () => number;
+    getPitch: () => number;
+    attachViewmodel: (entity: any, offset: Vector3) => void;
+}, FirstPersonEntity>;
+
+/**
+ * Jumper 3D ECS Components
+ *
+ * Type definitions and factory functions for the 3D jump behavior system.
+ *
+ * - JumpConfig3D:  tunable parameters (stored as the capability component)
+ * - JumpInput3D:   per-tick intent written by the player/AI controller
+ * - JumpContext3D:  per-tick snapshot provided by the system adapter
+ * - JumpState3D:   internal runtime state owned by the behavior
+ */
+interface Vec3Like {
+    x: number;
+    y: number;
+    z: number;
+}
+interface JumpConfig3D {
+    /** Desired peak height in world units */
+    jumpHeight: number;
+    /** Gravity magnitude (positive, e.g. 20) */
+    gravity: number;
+    /** Terminal fall speed magnitude (optional) */
+    maxFallSpeed?: number;
+    /** 1 = single jump, 2 = double, etc. */
+    maxJumps: number;
+    /** Reset jump counter when grounded (usually true) */
+    resetJumpsOnGround: boolean;
+    /** Reset jump counter on wall contact (future wall-jump support) */
+    resetJumpsOnWall?: boolean;
+    /** Grace period after leaving ground where first jump is still allowed (ms) */
+    coyoteTimeMs: number;
+    /** Queue a jump press this many ms before landing (ms) */
+    jumpBufferMs: number;
+    /** Optional cooldown between consecutive jumps (ms) */
+    minTimeBetweenJumpsMs?: number;
+    /** Variable jump height via early release */
+    variableJump?: {
+        enabled: boolean;
+        /** Gravity multiplier applied when jump is released early while ascending */
+        cutGravityMultiplier: number;
+        /** Max hold duration before the cut triggers automatically (ms, optional) */
+        maxHoldMs?: number;
+    };
+    /** Optional planar (XZ) launch / air-control overrides */
+    planar?: {
+        /** One-time planar speed applied at takeoff */
+        launchPlanarSpeed?: number;
+        /** If true, preserve current planar speed instead of replacing it */
+        preservePlanarSpeed?: boolean;
+        airControl?: {
+            maxPlanarSpeed: number;
+            /** Acceleration per second while airborne */
+            acceleration: number;
+            /** Deceleration per second when no input */
+            deceleration: number;
+        };
+    };
+    /** Snappier descent tuning */
+    fall?: {
+        /** Gravity multiplier while falling (e.g. 1.5-2.5) */
+        fallGravityMultiplier: number;
+        /** Additional multiplier when fast-fall input is held */
+        fastFallMultiplier?: number;
+    };
+}
+declare function createJumpConfig3D(options?: Partial<JumpConfig3D>): JumpConfig3D;
+interface JumpInput3D {
+    /** True on the frame the jump button is first pressed (rising edge) */
+    jumpPressed: boolean;
+    /** True while the jump button is held down */
+    jumpHeld: boolean;
+    /** True on the frame the jump button is released (falling edge) */
+    jumpReleased: boolean;
+    /** Desired planar direction in world space (camera-relative), optional */
+    moveDirWorld?: Vec3Like;
+    /** Hold to drop faster (e.g. crouch / down input) */
+    fastFall?: boolean;
+}
+declare function createJumpInput3D(): JumpInput3D;
+interface JumpContext3D {
+    /** Frame delta in seconds */
+    dt: number;
+    /** World up direction (usually 0,1,0) */
+    up: Vec3Like;
+    /** Current vertical (Y) velocity of the entity */
+    velocityY: number;
+    /** Current horizontal velocity of the entity (read from body) */
+    horizontalVelocity: {
+        x: number;
+        z: number;
+    };
+    /** Whether the entity is on the ground */
+    isGrounded: boolean;
+    /** Surface normal at ground contact (optional) */
+    groundNormal?: Vec3Like;
+    /** Time since entity was last grounded (ms) */
+    timeSinceGroundedMs: number;
+    /** Set only the vertical (Y) component of velocity */
+    setVerticalVelocity(y: number): void;
+    /** Set only the horizontal (X/Z) components of velocity */
+    setHorizontalVelocity(x: number, z: number): void;
+}
+interface JumpState3D {
+    /** Number of jumps consumed since last reset */
+    jumpsUsed: number;
+    /** Timestamp (ms) of the most recent jump execution */
+    lastJumpTimeMs: number;
+    /** Remaining ms in the jump-buffer window (counts down) */
+    bufferedJumpMs: number;
+    /** Remaining ms in the coyote-time window (counts down) */
+    coyoteMs: number;
+    /** True while the entity is in a jump arc (ascending phase) */
+    isJumping: boolean;
+    /** Elapsed ms since jump button was first held (for variable jump) */
+    jumpHoldMs: number;
+    /** Whether the variable-jump cut has already been applied this jump */
+    jumpCutApplied: boolean;
+}
+declare function createJumpState3D(): JumpState3D;
+
+/**
+ * Jumper 3D Behavior — Pure Jump Physics
+ *
+ * A stateless tick function that receives configuration, input, context, and
+ * state, then applies jump physics through the context's velocity helpers.
+ *
+ * Vertical velocity (Y) is owned exclusively by this behavior.
+ * Horizontal velocity (X/Z) is only touched when airborne planar control
+ * is configured; otherwise the movement controller owns X/Z.
+ */
+
+declare class Jumper3DBehavior {
+    /**
+     * Advance the jump system by one frame.
+     *
+     * Call order within a frame:
+     *   1. Movement controller writes X/Z via transformStore.dirty.velocityX/Z.
+     *   2. `tick()` writes Y via ctx.setVerticalVelocity().
+     *      (Optionally writes X/Z when airborne planar control is active.)
+     */
+    tick(config: JumpConfig3D, input: JumpInput3D, ctx: JumpContext3D, state: JumpState3D): JumperTickResult;
+}
+/** Events emitted by a single tick (used by FSM). */
+declare enum JumperTickEvent {
+    None = "none",
+    Jump = "jump",
+    Fall = "fall",
+    Land = "land"
+}
+interface JumperTickResult {
+    event: JumperTickEvent;
+}
+
+/**
+ * Jumper 3D Finite State Machine
+ *
+ * Three high-level states driven by events emitted from the behavior tick:
+ *   Grounded  ──Jump──▶  Jumping
+ *   Grounded  ──Fall──▶  Falling   (walked off a ledge)
+ *   Jumping   ──Fall──▶  Falling   (apex / descending)
+ *   Jumping   ──Jump──▶  Jumping   (multi-jump)
+ *   Jumping   ──Land──▶  Grounded  (rare — very short hop)
+ *   Falling   ──Land──▶  Grounded
+ *   Falling   ──Jump──▶  Jumping   (air-jump while falling)
+ */
+
+declare enum Jumper3DState {
+    Grounded = "grounded",
+    Jumping = "jumping",
+    Falling = "falling"
+}
+declare enum Jumper3DEvent {
+    Jump = "jump",
+    Fall = "fall",
+    Land = "land"
+}
+interface Jumper3DFSMContext {
+    state: JumpState3D;
+}
+declare class Jumper3DFSM {
+    private ctx;
+    machine: SyncStateMachine<Jumper3DState, Jumper3DEvent, never>;
+    constructor(ctx: Jumper3DFSMContext);
+    getState(): Jumper3DState;
+    dispatch(event: Jumper3DEvent): void;
+    isJumping(): boolean;
+    isFalling(): boolean;
+    isGrounded(): boolean;
+    getJumpsUsed(): number;
+    /**
+     * Translate a tick event into an FSM dispatch.
+     * Also handles the implicit Grounded→Falling transition when the entity
+     * is no longer grounded but no explicit event was emitted (e.g. walked
+     * off a ledge without jumping).
+     */
+    applyTickEvent(tickEvent: string, isGrounded: boolean): void;
+}
+
+interface Jumper3DBehaviorOptions {
+    /** Desired peak height in world units (default: 2.5) */
+    jumpHeight?: number;
+    /** Gravity magnitude applied by the behavior (default: 20) */
+    gravity?: number;
+    /** Terminal fall speed (optional) */
+    maxFallSpeed?: number;
+    /** Max concurrent jumps, 1 = single, 2 = double, etc. (default: 1) */
+    maxJumps?: number;
+    /** Reset jump counter on ground (default: true) */
+    resetJumpsOnGround?: boolean;
+    /** Reset jump counter on wall contact (default: undefined) */
+    resetJumpsOnWall?: boolean;
+    /** Coyote time in ms (default: 100) */
+    coyoteTimeMs?: number;
+    /** Jump buffer in ms (default: 80) */
+    jumpBufferMs?: number;
+    /** Min cooldown between jumps in ms (optional) */
+    minTimeBetweenJumpsMs?: number;
+    /** Variable jump height config (optional) */
+    variableJump?: JumpConfig3D['variableJump'];
+    /** Planar control config (optional) */
+    planar?: JumpConfig3D['planar'];
+    /** Fall tuning (optional) */
+    fall?: JumpConfig3D['fall'];
+    /** Ground-detection ray length (default: 1.0) */
+    groundRayLength?: number;
+    /** Max support distance that counts as grounded and can snap to ground */
+    snapToGroundDistance?: number;
+    /** Enable debug visualization for ground probe rays (default: false) */
+    debugGroundProbe?: boolean;
+}
+interface Jumper3DEntity {
+    uuid: string;
+    body: any;
+    transformStore: any;
+    jumper: JumpConfig3D;
+    $jumper: JumpInput3D;
+    jumperState: JumpState3D;
+}
+/**
+ * Jumper3D — composable 3D jump behavior.
+ *
+ * Provides height-based jumping, multi-jump, coyote time, jump buffering,
+ * variable jump height, configurable fall gravity, and optional air control.
+ *
+ * Designed to compose with any movement controller (e.g. FirstPersonController)
+ * — the controller writes X/Z velocity and Jumper3D writes Y velocity.
+ *
+ * @example
+ * ```typescript
+ * import { Jumper3D } from "@zylem/game-lib";
+ *
+ * const jumper = player.use(Jumper3D, {
+ *   jumpHeight: 2.5,
+ *   gravity: 20,
+ *   maxJumps: 2,
+ *   coyoteTimeMs: 100,
+ *   jumpBufferMs: 80,
+ *   variableJump: { enabled: true, cutGravityMultiplier: 3 },
+ *   fall: { fallGravityMultiplier: 1.5 },
+ * });
+ *
+ * player.onUpdate(({ inputs }) => {
+ *   player.$jumper.jumpPressed = inputs.p1.buttons.A.pressed;
+ *   player.$jumper.jumpHeld = inputs.p1.buttons.A.held > 0;
+ *   player.$jumper.jumpReleased = inputs.p1.buttons.A.released;
+ *
+ *   const state = jumper.getState();  // Grounded | Jumping | Falling
+ * });
+ * ```
+ */
+declare const Jumper3D: BehaviorDescriptor<Jumper3DBehaviorOptions, {
+    getState: () => Jumper3DState;
+    isJumping: () => boolean;
+    getJumpsUsed: () => number;
+    getJumpsRemaining: () => number;
+}, Jumper3DEntity>;
+
 /**
  * CooldownBehavior
  *
@@ -319,6 +911,82 @@ declare class BoundaryRicochetCoordinator {
     update(): boolean;
 }
 
+declare class BoundaryRicochet3DCoordinator {
+    private entity;
+    private boundary;
+    private ricochet;
+    constructor(entity: GameEntity<any> & MoveableEntity, boundary: WorldBoundary3DHandle, ricochet: Ricochet3DHandle);
+    update(): boolean;
+}
+
+interface FirstPersonShooterInput {
+    moveX: number;
+    moveZ: number;
+    lookX: number;
+    lookY: number;
+    sprint: boolean;
+    jumpPressed: boolean;
+    jumpHeld: boolean;
+    jumpReleased: boolean;
+    fastFall?: boolean;
+}
+interface FirstPersonShooterControllerHandle {
+    getYaw(): number;
+}
+interface FirstPersonShooterJumperHandle {
+    getState(): unknown;
+}
+type FirstPersonShooterEntity = GameEntity<any> & {
+    $fps?: FirstPersonInputComponent;
+    $jumper?: JumpInput3D;
+};
+declare class FirstPersonShooterCoordinator {
+    private entity;
+    private fpsController;
+    private jumper;
+    constructor(entity: FirstPersonShooterEntity, fpsController: FirstPersonShooterControllerHandle, jumper: FirstPersonShooterJumperHandle);
+    update(input: FirstPersonShooterInput): void;
+    private getMoveDirWorld;
+}
+
+interface TopDownShooterInput {
+    moveX: number;
+    moveY: number;
+    aimX: number;
+    aimY: number;
+    shootPressed: boolean;
+    shootHeld: boolean;
+}
+type TopDownShooterEntity = Shooter2DSourceEntity & {
+    $topDownMovement?: TopDownMovementInputComponent;
+};
+declare class TopDownShooterCoordinator {
+    private entity;
+    private shooter;
+    private stage;
+    constructor(entity: TopDownShooterEntity, shooter: Shooter2DHandle, stage: Shooter2DStageLike);
+    update(input: TopDownShooterInput): void;
+}
+
+interface MultidirectionalSpaceShooterInput {
+    moveX: number;
+    moveY: number;
+    aimX: number;
+    aimY: number;
+    shootPressed: boolean;
+    shootHeld: boolean;
+}
+type MultidirectionalSpaceShooterEntity = GameEntity<any> & Shooter2DSourceEntity & {
+    $thruster?: ThrusterInputComponent;
+};
+declare class MultidirectionalSpaceShooterCoordinator {
+    private entity;
+    private shooter;
+    private stage;
+    constructor(entity: MultidirectionalSpaceShooterEntity, shooter: Shooter2DHandle, stage: Shooter2DStageLike);
+    update(input: MultidirectionalSpaceShooterInput): void;
+}
+
 /**
  * CooldownIcon -- a WoW-style cooldown icon UI entity.
  *
@@ -466,6 +1134,11 @@ declare function pingPongBeep(frequency?: number, duration?: number): void;
  * @example stage.setInputConfiguration(useArrowsForAxes('p1'));
  */
 declare function useArrowsForAxes(player: InputPlayer): GameInputConfig;
+/**
+ * Maps arrow keys to secondary axes for the given player.
+ * @example stage.setInputConfiguration(useArrowsForSecondaryAxes('p1'));
+ */
+declare function useArrowsForSecondaryAxes(player: InputPlayer): GameInputConfig;
 /**
  * Maps arrow keys to directions (Up/Down/Left/Right) for the given player.
  * Useful when `includeDefaults` is false and you still want arrow-key directions.
@@ -492,6 +1165,22 @@ declare function useIJKLForAxes(player: InputPlayer): GameInputConfig;
  * @example stage.setInputConfiguration(useIJKLForDirections('p1'));
  */
 declare function useIJKLForDirections(player: InputPlayer): GameInputConfig;
+/**
+ * Enables mouse-look with pointer lock for the given player.
+ * Mouse movement maps to SecondaryHorizontal/SecondaryVertical axes;
+ * left click maps to LTrigger, right click to RTrigger.
+ * @example stage.setInputConfiguration(useMouseLook('p1'));
+ */
+declare function useMouseLook(player: InputPlayer, options?: {
+    sensitivity?: number;
+}): GameInputConfig;
+/**
+ * Enables basic mouse input (no pointer lock) for the given player.
+ * @example stage.setInputConfiguration(useMouse('p1'));
+ */
+declare function useMouse(player: InputPlayer, options?: {
+    sensitivity?: number;
+}): GameInputConfig;
 /**
  * Deep-merges multiple GameInputConfig objects into one.
  * At the player level, configs are merged (both apply).
@@ -609,15 +1298,23 @@ declare class ZylemGameElement extends HTMLElement {
     private _game;
     private _state;
     private container;
+    private resizeObserver;
+    private _viewportProfile;
+    private static readonly HOST_CONFIG_MARKER;
     constructor();
     /**
      * Focus the game container for keyboard input
      */
     focus(): void;
+    connectedCallback(): void;
     set game(game: Game<any>);
     get game(): Game<any> | null;
     set state(value: ZylemGameState);
     get state(): ZylemGameState;
+    set viewportProfile(value: DeviceProfile);
+    get viewportProfile(): DeviceProfile;
+    static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
     /**
      * Sync the web component's state with the game-lib's internal debug state
      */
@@ -627,6 +1324,8 @@ declare class ZylemGameElement extends HTMLElement {
      */
     private syncToolbarState;
     disconnectedCallback(): void;
+    private attachHostContainer;
+    private syncDisplayRuntime;
 }
 
 declare const fireShader: {
@@ -651,4 +1350,4 @@ declare const debugShader: {
 
 declare const objectVertexShader = "\nuniform vec2 uvScale;\nvarying vec2 vUv;\n\nvoid main() {\n\tvUv = uv;\n\tvec4 mvPosition = modelViewMatrix * vec4( position, 1.0 );\n\tgl_Position = projectionMatrix * mvPosition;\n}\n";
 
-export { BehaviorDescriptor, BoundaryRicochetCoordinator, CooldownBehavior, type CooldownConfig, type CooldownEntry, type CooldownHandle, type CooldownOptions, type DebugTools, Game, type IconSize, type IconSizePreset, Ricochet2DHandle, type ScreenAnchor, StageBlueprint, StageManager, type TemplateFactory, WorldBoundary2DHandle, ZylemGameElement, type ZylemGameState, boxMesh, clearGlobalSubscriptions, coneMesh, createCooldownIcon, createEntityFactory, createGlobal, createVariable, cylinderMesh, debugShader, debugState, destroy, fireCooldown, fireShader, getCooldown, getCooldownStore, getGlobal, getGlobals, getVariable, mergeInputConfigs, objectVertexShader, onGlobalChange, onGlobalChanges, onVariableChange, onVariableChanges, pillMesh, pingPongBeep, pyramidMesh, registerCooldown, resetCooldown, ricochetSound, setDebugTool, setGlobal, setPaused, setVariable, sphereMesh, stageState, standardShader, starShader, tickCooldowns, useArrowsForAxes, useArrowsForDirections, useBehavior, useIJKLForAxes, useIJKLForDirections, useWASDForAxes, useWASDForDirections };
+export { BehaviorDescriptor, BoundaryRicochet3DCoordinator, BoundaryRicochetCoordinator, CameraBehavior, type CameraFeedOptions, CameraWrapper, CooldownBehavior, type CooldownConfig, type CooldownEntry, type CooldownHandle, type CooldownOptions, type DebugTools, DeviceProfile, type FirstPersonContext, FirstPersonController, FirstPersonControllerBehavior, type FirstPersonControllerOptions, type FirstPersonEntity, FirstPersonEvent, FirstPersonFSM, type FirstPersonInputComponent, type FirstPersonMovementComponent, FirstPersonPerspective, FirstPersonShooterCoordinator, type FirstPersonShooterInput, FirstPersonState, type FirstPersonStateComponent, type FollowTargetOptions, Game, type IconSize, type IconSizePreset, type JumpConfig3D, type JumpContext3D, type JumpInput3D, type JumpState3D, Jumper3D, Jumper3DBehavior, type Jumper3DBehaviorOptions, type Jumper3DEntity, Jumper3DEvent, Jumper3DFSM, Jumper3DState, JumperTickEvent, type JumperTickResult, MultidirectionalSpaceShooterCoordinator, type MultidirectionalSpaceShooterInput, Ricochet2DHandle, Ricochet3DHandle, type ScreenAnchor, Shooter2DHandle, Shooter2DSourceEntity, Shooter2DStageLike, StageBlueprint, StageEntity, StageManager, type TemplateFactory, ThrusterInputComponent, TopDownMovementInputComponent, TopDownShooterCoordinator, type TopDownShooterInput, type Vec3Like, type ViewmodelConfig, WorldBoundary2DHandle, WorldBoundary3DHandle, ZylemGameElement, type ZylemGameState, boxMesh, clearGlobalSubscriptions, coneMesh, createCooldownIcon, createEntityFactory, createFirstPersonInputComponent, createFirstPersonMovementComponent, createFirstPersonStateComponent, createFollowTarget, createGlobal, createJumpConfig3D, createJumpInput3D, createJumpState3D, createVariable, cylinderMesh, debugShader, debugState, destroy, fireCooldown, fireShader, getCooldown, getCooldownStore, getGlobal, getGlobals, getVariable, mergeInputConfigs, objectVertexShader, onGlobalChange, onGlobalChanges, onVariableChange, onVariableChanges, pillMesh, pingPongBeep, pyramidMesh, registerCooldown, resetCooldown, ricochetSound, setCameraFeed, setDebugTool, setGlobal, setPaused, setVariable, sphereMesh, stageState, standardShader, starShader, tickCooldowns, useArrowsForAxes, useArrowsForDirections, useArrowsForSecondaryAxes, useBehavior, useIJKLForAxes, useIJKLForDirections, useMouse, useMouseLook, useWASDForAxes, useWASDForDirections };