@zylem/game-lib 0.6.0 → 0.6.3

package/dist/entity-types-DAu8sGJH.d.ts

@@ -0,0 +1,26 @@
+import { Group } from 'three';
+import { RigidBody, Collider } from '@dimforge/rapier3d-compat';
+
+/**
+ * Base entity interface - shared across modules to prevent circular dependencies
+ */
+interface BaseEntityInterface {
+    uuid: string;
+    name: string;
+    eid: number;
+    group: Group | null | undefined;
+    body: RigidBody | null | undefined;
+    collider: Collider | null | undefined;
+}
+/**
+ * Game entity interface - minimal interface to break circular dependencies
+ */
+interface GameEntityInterface extends BaseEntityInterface {
+    type: string;
+    isStatic: boolean;
+    setPosition(x: number, y: number, z: number): void;
+    setRotation(x: number, y: number, z: number): void;
+    setScale(x: number, y: number, z: number): void;
+}
+
+export type { BaseEntityInterface as B, GameEntityInterface as G };

package/dist/global-change-Dc8uCKi2.d.ts

@@ -0,0 +1,25 @@
+import { U as UpdateContext } from './entity-BpbZqg19.js';
+
+/**
+ * Listen for a single global key change inside an onUpdate pipeline.
+ * Usage: onUpdate(globalChange('p1Score', (value) => { ... }))
+ */
+declare function globalChange<T = any>(key: string, callback: (value: T, ctx: UpdateContext<any>) => void): (ctx: UpdateContext<any>) => void;
+/**
+ * Listen for multiple global key changes inside an onUpdate pipeline.
+ * Calls back when any of the provided keys changes.
+ * Usage: onUpdate(globalChanges(['p1Score','p2Score'], ([p1,p2]) => { ... }))
+ */
+declare function globalChanges<T = any>(keys: string[], callback: (values: T[], ctx: UpdateContext<any>) => void): (ctx: UpdateContext<any>) => void;
+/**
+ * Listen for a single stage variable change inside an onUpdate pipeline.
+ * Usage: onUpdate(variableChange('score', (value, ctx) => { ... }))
+ */
+declare function variableChange<T = any>(key: string, callback: (value: T, ctx: UpdateContext<any>) => void): (ctx: UpdateContext<any>) => void;
+/**
+ * Listen for multiple stage variable changes; fires when any changes.
+ * Usage: onUpdate(variableChanges(['a','b'], ([a,b], ctx) => { ... }))
+ */
+declare function variableChanges<T = any>(keys: string[], callback: (values: T[], ctx: UpdateContext<any>) => void): (ctx: UpdateContext<any>) => void;
+
+export { globalChanges as a, variableChanges as b, globalChange as g, variableChange as v };

package/dist/main.d.ts

@@ -1,25 +1,40 @@
-import { G as Game } from './core-CZhozNRH.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-CZhozNRH.js';
-export { a as StageOptions, c as createStage } from './stage-types-CD21XoIU.js';
-import { S as StageBlueprint } from './blueprints-BOCc3Wve.js';
-export { e as entitySpawner } from './blueprints-BOCc3Wve.js';
-export { P as PerspectiveType, a as Perspectives, c as camera } from './camera-CpbDr4-V.js';
-export { A as ACTOR_TYPE, B as BOX_TYPE, P as PLANE_TYPE, R as RECT_TYPE, d as SPHERE_TYPE, S as SPRITE_TYPE, T as TEXT_TYPE, e as ZONE_TYPE, Z as ZylemBox, c as actor, b as box, p as plane, r as rect, s as sphere, a as sprite, t as text, z as zone } from './entities-BAxfJOkk.js';
-import { U as UpdateContext, B as BehaviorCallbackType, G as GameEntity } from './entity-COvRtFNG.js';
-export { a as Behavior, L as LoadingEvent, S as SetupContext } from './entity-COvRtFNG.js';
-export { boundary2d, ricochet2DCollision, ricochet2DInBounds } from './behaviors.js';
-import { M as MoveableEntity } from './moveable-B_vyA6cw.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 } 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 * 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';
+export { ScreenWrapBehavior, ScreenWrapEvent, ScreenWrapFSM, ScreenWrapOptions, ScreenWrapState } from './behavior/screen-wrap.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 { Ricochet2DHandle } from './behavior/ricochet-2d.js';
+export { Ricochet2DBehavior, Ricochet2DCollisionContext, Ricochet2DEvent, Ricochet2DFSM, Ricochet2DOptions, Ricochet2DResult, Ricochet2DState, RicochetCallback } from './behavior/ricochet-2d.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';
+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 { Fn, float, time, uniform, uv, vec3, vec4 } from 'three/tsl';
 import 'bitecs';
+import './world-Be5m1XC1.js';
+import './entity-types-DAu8sGJH.js';
 import '@sinclair/typebox';
+import 'three/webgpu';
 import 'three/examples/jsm/postprocessing/EffectComposer.js';
+import 'mitt';
+import 'typescript-fsm';
 
 declare const stageState: {
     previous: StageBlueprint | null;
@@ -50,26 +65,389 @@ declare const StageManager: {
     preloadNext(stageId: string, loadStaticStage?: (id: string) => Promise<StageBlueprint>): Promise<void>;
 };
 
-interface MovementSequence2DStep {
+/**
+ * Factory interface for generating entity copies
+ */
+interface TemplateFactory<E extends GameEntity<O>, O extends GameEntityOptions = GameEntityOptions> {
+    /** The template entity used for cloning */
+    readonly template: E;
+    /**
+     * Generate multiple copies of the template entity
+     * @param count Number of copies to generate
+     * @returns Array of new entity instances
+     */
+    generate(count: number): E[];
+}
+/**
+ * Create an entity factory from a template entity.
+ *
+ * @param template The entity to use as a template for cloning
+ * @returns Factory object with generate() method
+ *
+ * @example
+ * ```typescript
+ * const asteroidTemplate = createSprite({ images: [{ name: 'asteroid', file: asteroidImg }] });
+ * const asteroidFactory = createEntityFactory(asteroidTemplate);
+ * const asteroids = asteroidFactory.generate(10);
+ *
+ * asteroids.forEach((asteroid, i) => {
+ *     asteroid.setPosition(Math.random() * 20 - 10, Math.random() * 15 - 7.5, 0);
+ *     stage.add(asteroid);
+ * });
+ * ```
+ */
+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;
+
+/**
+ * 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;
-    moveX?: number;
-    moveY?: number;
-    timeInSeconds: number;
+    /** 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;
 }
-interface MovementSequence2DOptions {
-    sequence: MovementSequence2DStep[];
-    loop?: 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;
 }
-type MovementSequence2DCallback = (current: MovementSequence2DStep, index: number, ctx: UpdateContext<MoveableEntity>) => void;
+
 /**
- * Behavior that sequences 2D movements over time.
- * Each step sets linear velocity via `moveXY` for a duration, then advances.
- * Defaults to looping when the end is reached.
+ * 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.
  */
-declare function movementSequence2D(opts: MovementSequence2DOptions, onStep?: MovementSequence2DCallback): {
-    type: BehaviorCallbackType;
-    handler: (ctx: UpdateContext<MoveableEntity>) => void;
+
+/**
+ * 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;
 
@@ -83,6 +461,45 @@ 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 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;
+/**
+ * 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.
@@ -193,6 +610,10 @@ declare class ZylemGameElement extends HTMLElement {
     private _state;
     private container;
     constructor();
+    /**
+     * Focus the game container for keyboard input
+     */
+    focus(): void;
     set game(game: Game<any>);
     get game(): Game<any> | null;
     set state(value: ZylemGameState);
@@ -208,4 +629,26 @@ declare class ZylemGameElement extends HTMLElement {
     disconnectedCallback(): void;
 }
 
-export { type DebugTools, Game, StageBlueprint, StageManager, UpdateContext, ZylemGameElement, type ZylemGameState, clearGlobalSubscriptions, createGlobal, createVariable, debugState, destroy, getGlobal, getGlobals, getVariable, movementSequence2D, onGlobalChange, onGlobalChanges, onVariableChange, onVariableChanges, pingPongBeep, ricochetSound, setDebugTool, setGlobal, setPaused, setVariable, stageState };
+declare const fireShader: {
+    vertex: string;
+    fragment: string;
+};
+
+declare const starShader: {
+    vertex: string;
+    fragment: string;
+};
+
+declare const standardShader: {
+    vertex: string;
+    fragment: string;
+};
+
+declare const debugShader: {
+    vertex: string;
+    fragment: string;
+};
+
+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 };