@zylem/game-lib 0.6.2 → 0.6.4

package/dist/main.d.ts

@@ -1,24 +1,51 @@
-import { G as Game } from './core-bO8TzV7u.js';
-export { V as Vect3, Z as ZylemGameConfig, c as createGame, g as gameConfig, a as globalChange, b as globalChanges, d as variableChange, e as variableChanges, v as vessel } from './core-bO8TzV7u.js';
-export { a as StageOptions, d as createDisk, c as createStage } from './stage-types-Bd-KtcYT.js';
-import { S as StageBlueprint } from './blueprints-Cq3Ko6_G.js';
-export { e as entitySpawner } from './blueprints-Cq3Ko6_G.js';
-export { P as PerspectiveType, d as Perspectives, c as createCamera } from './camera-CeJPAgGg.js';
-export { A as ACTOR_TYPE, B as BOX_TYPE, P as PLANE_TYPE, R as RECT_TYPE, a as SPHERE_TYPE, S as SPRITE_TYPE, T as TEXT_TYPE, g as ZONE_TYPE, e as ZylemBox, o as createActor, j as createBox, m as createPlane, q as createRect, k as createSphere, l as createSprite, p as createText, n as createZone } from './entities-DvByhMGU.js';
-import { G as GameEntity, g as GameEntityOptions } from './world-C8tQ7Plj.js';
-export { q as BehaviorDescriptor, s as BehaviorHandle, r as BehaviorRef, e as BehaviorSystem, f as BehaviorSystemFactory, t as DefineBehaviorConfig, o as EntityConfigPayload, k as EntityEvents, E as EventEmitterDelegate, j as GameEvents, l as GameLoadingPayload, L as LoadingEvent, a as SetupContext, n as StageConfigPayload, h as StageEvents, m as StateDispatchPayload, b as UpdateContext, i as ZylemEvents, Z as ZylemShaderObject, p as defineBehavior, z as zylemEventBus } from './world-C8tQ7Plj.js';
-export { Behavior, BoundaryRicochetCoordinator, MovementSequence2DBehavior, MovementSequence2DCurrentStep, MovementSequence2DEvent, MovementSequence2DFSM, MovementSequence2DHandle, MovementSequence2DMovement, MovementSequence2DOptions, MovementSequence2DProgress, MovementSequence2DState, MovementSequence2DStep, PhysicsBodyComponent, PhysicsStepBehavior, PhysicsSyncBehavior, PlayerInput, Ricochet2DBehavior, Ricochet2DCollisionContext, Ricochet2DEvent, Ricochet2DFSM, Ricochet2DHandle, Ricochet2DOptions, Ricochet2DResult, Ricochet2DState, ScreenWrapBehavior, ScreenWrapEvent, ScreenWrapFSM, ScreenWrapOptions, ScreenWrapState, ThrusterBehavior, ThrusterBehaviorOptions, ThrusterEntity, ThrusterEvent, ThrusterFSM, ThrusterFSMContext, ThrusterInputComponent, ThrusterMovementBehavior, ThrusterMovementComponent, ThrusterState, ThrusterStateComponent, TransformComponent, WorldBoundary2DBehavior, WorldBoundary2DBounds, WorldBoundary2DEvent, WorldBoundary2DFSM, WorldBoundary2DHandle, WorldBoundary2DHit, WorldBoundary2DHits, WorldBoundary2DOptions, WorldBoundary2DPosition, WorldBoundary2DState, computeWorldBoundary2DHits, createPhysicsBodyComponent, createThrusterInputComponent, createThrusterMovementComponent, createThrusterStateComponent, createTransformComponent, hasAnyWorldBoundary2DHit, useBehavior } from './behaviors.js';
-export { m as makeMoveable, b as move, a as moveable, r as resetVelocity } from './moveable-B_vyA6cw.js';
-export { m as makeRotatable, a as makeTransformable, r as rotatable, b as rotateInDirection } from './transformable-CUhvyuYO.js';
-export { Howl } from 'howler';
+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 { 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';
+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 { 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-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';
 import 'mitt';
 import 'typescript-fsm';
@@ -39,8 +66,8 @@ declare const StageManager: {
             data?: {
                 [x: string]: any;
             } | undefined;
-            type: string;
             id: string;
+            type: string;
         }[];
     }>;
     registerStaticStage(id: string, blueprint: StageBlueprint): void;
@@ -52,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
  */
@@ -85,6 +181,942 @@ interface TemplateFactory<E extends GameEntity<O>, O extends GameEntityOptions =
  */
 declare function createEntityFactory<E extends GameEntity<O>, O extends GameEntityOptions = GameEntityOptions>(template: E): TemplateFactory<E, O>;
 
+/** Shared options that every mesh factory accepts. */
+interface BaseMeshOptions {
+    /** Offset position relative to the entity origin */
+    position?: Vec3;
+    /** Material options (texture, shader, etc.) */
+    material?: Partial<MaterialOptions>;
+    /** Convenience color override */
+    color?: Color;
+}
+interface BoxMeshOptions extends BaseMeshOptions {
+    /** Box dimensions (default: 1x1x1) */
+    size?: Vec3;
+}
+/**
+ * Create a box mesh.
+ */
+declare function boxMesh(opts?: BoxMeshOptions): Mesh;
+interface SphereMeshOptions extends BaseMeshOptions {
+    /** Sphere radius (default: 1) */
+    radius?: number;
+}
+/**
+ * Create a sphere mesh.
+ */
+declare function sphereMesh(opts?: SphereMeshOptions): Mesh;
+interface ConeMeshOptions extends BaseMeshOptions {
+    /** Base radius (default: 1) */
+    radius?: number;
+    /** Height (default: 2) */
+    height?: number;
+    /** Radial segments (default: 32) */
+    radialSegments?: number;
+}
+/**
+ * Create a cone mesh.
+ */
+declare function coneMesh(opts?: ConeMeshOptions): Mesh;
+interface PyramidMeshOptions extends BaseMeshOptions {
+    /** Base radius (default: 1) */
+    radius?: number;
+    /** Height (default: 2) */
+    height?: number;
+}
+/**
+ * Create a pyramid mesh (4-sided cone).
+ */
+declare function pyramidMesh(opts?: PyramidMeshOptions): Mesh;
+interface CylinderMeshOptions extends BaseMeshOptions {
+    /** Top radius (default: 1) */
+    radiusTop?: number;
+    /** Bottom radius (default: 1) */
+    radiusBottom?: number;
+    /** Height (default: 2) */
+    height?: number;
+    /** Radial segments (default: 32) */
+    radialSegments?: number;
+}
+/**
+ * Create a cylinder mesh.
+ */
+declare function cylinderMesh(opts?: CylinderMeshOptions): Mesh;
+interface PillMeshOptions extends BaseMeshOptions {
+    /** Capsule hemisphere radius (default: 0.5) */
+    radius?: number;
+    /** Cylindrical section length (default: 1) */
+    length?: number;
+    /** Cap segments (default: 10) */
+    capSegments?: number;
+    /** Radial segments (default: 20) */
+    radialSegments?: number;
+}
+/**
+ * Create a pill (capsule) mesh.
+ */
+declare function pillMesh(opts?: PillMeshOptions): Mesh;
+
+/**
+ * Type-safe helper to apply a behavior to an entity and return the entity cast to the behavior's interface.
+ *
+ * @param entity The entity to apply the behavior to
+ * @param descriptor The behavior descriptor
+ * @param options Behavior options
+ * @returns The entity, cast to E & I (where I is the behavior's interface)
+ */
+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
+ *
+ * A stage-scoped behavior that manages named cooldowns via the global CooldownStore.
+ * Entities use this to register, check, and fire cooldowns.
+ * UI components (CooldownIcon) can read from the same store.
+ */
+interface CooldownConfig {
+    /** Duration in seconds */
+    duration: number;
+    /** Whether the cooldown starts ready (default: true) */
+    immediate?: boolean;
+}
+interface CooldownOptions {
+    /**
+     * Named cooldowns to register.
+     * Keys are the cooldown names, values are their config.
+     */
+    cooldowns: Record<string, CooldownConfig>;
+}
+/**
+ * Handle methods returned by entity.use(CooldownBehavior, ...).
+ */
+interface CooldownHandle {
+    /** Check if a named cooldown is ready */
+    isReady(name: string): boolean;
+    /** Fire (trigger) a named cooldown, resetting its timer */
+    fire(name: string): void;
+    /** Force a cooldown to ready immediately */
+    reset(name: string): void;
+    /** Get cooldown progress 0..1 (0 = just fired, 1 = ready) */
+    getProgress(name: string): number;
+}
+/**
+ * CooldownBehavior
+ *
+ * @example
+ * ```ts
+ * import { CooldownBehavior, moveBy } from '@zylem/game-lib';
+ *
+ * const hero = createBox({ ... });
+ * const cd = hero.use(CooldownBehavior, {
+ *   cooldowns: {
+ *     attack: { duration: 5 },
+ *     dash: { duration: 2, immediate: false },
+ *   },
+ * });
+ *
+ * hero.onUpdate(({ me, inputs }) => {
+ *   if (cd.isReady('attack') && inputs.p1.buttons.A.pressed) {
+ *     cd.fire('attack');
+ *     // perform attack
+ *   }
+ *   if (cd.isReady('dash') && inputs.p1.buttons.B.pressed) {
+ *     cd.fire('dash');
+ *     me.runAction(moveBy({ x: 10, duration: 0.3 }));
+ *   }
+ * });
+ * ```
+ */
+declare const CooldownBehavior: BehaviorDescriptor<CooldownOptions, CooldownHandle, unknown>;
+
+/**
+ * A single cooldown entry in the global store.
+ */
+interface CooldownEntry {
+    /** Identifier for this cooldown */
+    name: string;
+    /** Total cooldown time in seconds */
+    duration: number;
+    /** Time accumulated since last fire */
+    elapsed: number;
+    /** Whether the cooldown is ready (elapsed >= duration) */
+    ready: boolean;
+    /** Normalized progress 0..1 (0 = just fired, 1 = ready) */
+    progress: number;
+    /** Whether this cooldown is currently counting down */
+    active: boolean;
+}
+/**
+ * Register a named cooldown in the global store.
+ * If a cooldown with the same name already exists, it is overwritten.
+ *
+ * @param name Unique cooldown identifier
+ * @param duration Cooldown duration in seconds
+ * @param immediate If true, the cooldown starts ready (default: true)
+ */
+declare function registerCooldown(name: string, duration: number, immediate?: boolean): void;
+/**
+ * Get a cooldown entry by name.
+ * Returns undefined if the cooldown has not been registered.
+ */
+declare function getCooldown(name: string): CooldownEntry | undefined;
+/**
+ * Fire (trigger) a cooldown, resetting its timer.
+ * Sets the cooldown to not-ready and starts the countdown.
+ */
+declare function fireCooldown(name: string): void;
+/**
+ * Force a cooldown to ready immediately.
+ */
+declare function resetCooldown(name: string): void;
+/**
+ * Advance all active cooldowns by delta seconds.
+ * Called once per frame by the CooldownBehavior system.
+ */
+declare function tickCooldowns(delta: number): void;
+/**
+ * Get the raw cooldown store (for advanced/debugging use).
+ */
+declare function getCooldownStore(): Record<string, CooldownEntry>;
+
+/**
+ * Coordinator that bridges WorldBoundary2DBehavior and Ricochet2DBehavior.
+ *
+ * Automatically handles:
+ * 1. Checking boundary hits
+ * 2. Computing collision normals
+ * 3. Requesting ricochet result
+ * 4. Applying movement
+ */
+declare class BoundaryRicochetCoordinator {
+    private entity;
+    private boundary;
+    private ricochet;
+    constructor(entity: GameEntity<any> & MoveableEntity, boundary: WorldBoundary2DHandle, ricochet: Ricochet2DHandle);
+    /**
+     * Update loop - call this every frame.
+     * Applies ricochet via transformStore and notifies listeners.
+     *
+     * @returns true if ricochet was applied, false otherwise
+     */
+    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.
+ *
+ * Renders a square icon with a semi-transparent clockwise sweep overlay
+ * that reflects cooldown progress from the CooldownStore. Optionally shows
+ * remaining time text in the center.
+ *
+ * Modeled after ZylemRect's canvas-based viewport-attached sprite pattern.
+ */
+
+/**
+ * Reference point on the viewport for positioning UI elements.
+ * The offset in `screenPosition` is applied relative to this anchor.
+ */
+type ScreenAnchor = 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+/** Preset icon sizes in view units. */
+declare const ICON_SIZE_PRESETS: {
+    readonly xs: 8;
+    readonly sm: 16;
+    readonly md: 32;
+    readonly lg: 48;
+    readonly xl: 64;
+};
+/** Named size preset. */
+type IconSizePreset = keyof typeof ICON_SIZE_PRESETS;
+/**
+ * Icon size expressed as a named preset, a square unit value, or
+ * a `{ width, height }` object for non-square icons.
+ *
+ * All numeric values are in **view units** (viewport height = 192 units).
+ */
+type IconSize = IconSizePreset | number | {
+    width: number;
+    height: number;
+};
+type ZylemCooldownIconOptions = GameEntityOptions & {
+    /** Name of the cooldown in the CooldownStore */
+    cooldown: string;
+    /** Texture path for the icon background (optional) */
+    icon?: string;
+    /** Solid fill color when no icon texture is provided */
+    fillColor?: Color | string;
+    /**
+     * Size of the icon in view units, a named preset, or a `{ width, height }` object.
+     *
+     * Presets: `'xs'` (8), `'sm'` (16), `'md'` (32), `'lg'` (48), `'xl'` (64).
+     * A bare number creates a square icon of that many units.
+     * The viewport height equals 192 units; width scales with aspect ratio.
+     *
+     * @default 'md'
+     */
+    iconSize?: IconSize;
+    /** Whether to show remaining time text */
+    showTimer?: boolean;
+    /** Whether to attach to the camera viewport (default: true) */
+    stickToViewport?: boolean;
+    /**
+     * Viewport anchor the icon is positioned relative to.
+     * @default 'top-left'
+     */
+    screenAnchor?: ScreenAnchor;
+    /**
+     * Offset from the {@link screenAnchor} in **view units**.
+     * Positive x = right, positive y = down.
+     * Accepts a `Vector2` or a plain `{ x, y }` object.
+     * @default { x: 0, y: 0 }
+     */
+    screenPosition?: Vector2 | {
+        x: number;
+        y: number;
+    };
+    /** Distance from camera (default: 1) */
+    zDistance?: number;
+    /** Color of the sweep overlay (default: semi-transparent black) */
+    overlayColor?: string;
+};
+declare class ZylemCooldownIcon extends GameEntity<ZylemCooldownIconOptions> {
+    static type: symbol;
+    private _sprite;
+    private _texture;
+    private _canvas;
+    private _ctx;
+    private _cameraRef;
+    private _iconTexture;
+    private _iconImage;
+    private _lastRenderedProgress;
+    constructor(options?: ZylemCooldownIconOptions);
+    private createSprite;
+    private redraw;
+    private toCssColor;
+    private getResolution;
+    private iconSetup;
+    private iconUpdate;
+    /**
+     * Resolve screen position to pixels.
+     * Computes the anchor point in pixels, then adds the view-unit offset.
+     */
+    private resolveScreenPosition;
+    /**
+     * Resolve `iconSize` to screen pixels using the view-unit grid.
+     * Viewport height = {@link VIEW_UNITS_HEIGHT} units; width scales with aspect ratio.
+     */
+    private resolveIconSize;
+    /** Compute the world-space half-extents at a given distance from the camera. */
+    private computeWorldExtents;
+    private updateStickyTransform;
+    /**
+     * Dispose Three.js / DOM resources when the entity is destroyed.
+     */
+    private iconDestroy;
+}
+type CooldownIconOptions = BaseNode | Partial<ZylemCooldownIconOptions>;
+/**
+ * Create a WoW-style cooldown icon UI entity.
+ *
+ * @example
+ * ```ts
+ * const attackIcon = createCooldownIcon({
+ *   cooldown: 'attack',
+ *   icon: swordIconPath,
+ *   screenAnchor: 'top-center',         // reference point on the viewport
+ *   screenPosition: { x: 0, y: 10 },    // offset in view units from anchor
+ *   iconSize: 'sm',                      // preset (16 × 16 view units)
+ *   // iconSize: 24,                     // square  (24 × 24 view units)
+ *   // iconSize: { width: 16, height: 24 }, // custom rectangle
+ * });
+ * ```
+ */
+declare function createCooldownIcon(...args: Array<CooldownIconOptions>): ZylemCooldownIcon;
+
 declare function destroy(entity: any, globals?: any): void;
 
 /**
@@ -97,6 +1129,66 @@ declare function ricochetSound(frequency?: number, duration?: number): void;
  */
 declare function pingPongBeep(frequency?: number, duration?: number): void;
 
+/**
+ * Maps arrow keys to axes (Horizontal/Vertical) for the given player.
+ * @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.
+ * @example stage.setInputConfiguration(useArrowsForDirections('p1'));
+ */
+declare function useArrowsForDirections(player: InputPlayer): GameInputConfig;
+/**
+ * Maps W/A/S/D keys to directions (Up/Down/Left/Right) for the given player.
+ * @example stage.setInputConfiguration(useWASDForDirections('p1'));
+ */
+declare function useWASDForDirections(player: InputPlayer): GameInputConfig;
+/**
+ * Maps W/A/S/D keys to axes (Horizontal/Vertical) for the given player.
+ * @example stage.setInputConfiguration(useWASDForAxes('p1'));
+ */
+declare function useWASDForAxes(player: InputPlayer): GameInputConfig;
+/**
+ * Maps I/J/K/L keys to axes (Horizontal/Vertical) for the given player.
+ * @example stage.setInputConfiguration(useIJKLForAxes('p1'));
+ */
+declare function useIJKLForAxes(player: InputPlayer): GameInputConfig;
+/**
+ * Maps I/J/K/L keys to directions (Up/Down/Left/Right) for the given player.
+ * @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).
+ * At the key level, later configs win on conflict.
+ * @example mergeInputConfigs(useArrowsForAxes('p1'), useWASDForDirections('p1'));
+ */
+declare function mergeInputConfigs(...configs: GameInputConfig[]): GameInputConfig;
+
 /**
  * Set a global value by path.
  * Emits a 'game:state:updated' event when the value changes.
@@ -206,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
      */
@@ -224,6 +1324,8 @@ declare class ZylemGameElement extends HTMLElement {
      */
     private syncToolbarState;
     disconnectedCallback(): void;
+    private attachHostContainer;
+    private syncDisplayRuntime;
 }
 
 declare const fireShader: {
@@ -248,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 { type DebugTools, Game, StageBlueprint, StageManager, type TemplateFactory, ZylemGameElement, type ZylemGameState, clearGlobalSubscriptions, createEntityFactory, createGlobal, createVariable, debugShader, debugState, destroy, fireShader, getGlobal, getGlobals, getVariable, objectVertexShader, onGlobalChange, onGlobalChanges, onVariableChange, onVariableChanges, pingPongBeep, ricochetSound, setDebugTool, setGlobal, setPaused, setVariable, stageState, standardShader, starShader };
+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 };