cubeforge 0.1.9 → 0.2.1

package/dist/index.d.mts

@@ -0,0 +1,909 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React from 'react';
+import React__default, { CSSProperties, ReactNode } from 'react';
+import { Plugin, EntityId, System, ECSWorld, ScriptUpdateFn, NavGrid, WorldSnapshot, EventBus } from '@cubeforge/core';
+export { AssetProgress, Component, ECSWorld, Ease, EntityId, GameTimer, NavGrid, Plugin, PreloadManifest, ScriptUpdateFn, TransformComponent, TweenHandle, Vec2Like, WorldSnapshot, arrive, createTag, createTimer, createTransform, definePlugin, findByTag, flee, patrol, preloadManifest, seek, tween, wander } from '@cubeforge/core';
+import { InputManager, ActionBindings, InputContextName, PlayerInput, InputRecorderControls } from '@cubeforge/input';
+export { ActionBindings, AxisBinding, InputContextName, InputManager, InputMap, InputRecorderControls, InputRecording, InputRecording as InputRecordingData, PlayerInput, createInputMap, createInputRecorder, createPlayerInput, globalInputContext } from '@cubeforge/input';
+import { EngineState } from '@cubeforge/context';
+export { EngineState, useCircleEnter, useCircleExit, useCircleStay, useCollisionEnter, useCollisionExit, useCollisionStay, useTriggerEnter, useTriggerExit, useTriggerStay } from '@cubeforge/context';
+export { AISteering, AnimationClip, AnimationControllerResult, BindingControls, GameState as GameStateDefinition, GameStateMachineResult, HealthControls, HealthOptions, KinematicBodyControls, LevelTransitionControls, PathfindingControls, PlatformerControllerOptions, RestartControls, SaveControls, SaveOptions, TopDownMovementOptions, TransitionOptions, TransitionType, useAISteering, useAnimationController, useDamageZone, useDropThrough, useGameStateMachine, useHealth, useKinematicBody, useLevelTransition, usePathfinding, usePersistedBindings, usePlatformerController, useRestart, useSave, useTopDownMovement } from '@cubeforge/gameplay';
+export { AudioGroup, SoundControls, duck, getGroupVolume, setGroupMute, setGroupVolume, setMasterVolume, stopGroup, useSound } from '@cubeforge/audio';
+export { DevToolsHandle } from '@cubeforge/devtools';
+export { BoxColliderComponent, CapsuleColliderComponent, CircleColliderComponent, RaycastHit, RigidBodyComponent, overlapBox, overlapCircle, raycast, raycastAll, sweepBox } from '@cubeforge/physics';
+export { AnimationStateComponent, ParallaxLayerComponent, Particle, ParticlePoolComponent, SpriteComponent, SquashStretchComponent, TextComponent, TrailComponent, createSprite } from '@cubeforge/renderer';
+
+interface GameControls {
+    pause(): void;
+    resume(): void;
+    reset(): void;
+}
+interface GameProps {
+    width?: number;
+    height?: number;
+    /** Pixels per second squared downward (default 980) */
+    gravity?: number;
+    /** Enable debug overlay: collider wireframes, FPS, entity count */
+    debug?: boolean;
+    /**
+     * Canvas scaling strategy (default 'none'):
+     * - 'none'    — fixed pixel size, no scaling
+     * - 'contain' — CSS scale to fit parent while preserving aspect ratio
+     * - 'pixel'   — nearest-neighbor pixel-art scaling via CSS
+     */
+    scale?: 'none' | 'contain' | 'pixel';
+    /** Called once the engine is ready — receives pause/resume/reset controls */
+    onReady?: (controls: GameControls) => void;
+    /** Enable time-travel debugging overlay (frame scrubber + entity inspector). */
+    devtools?: boolean;
+    /** Run the simulation in deterministic mode using a seeded RNG. */
+    deterministic?: boolean;
+    /** Seed for the deterministic RNG (default 0). Only used when deterministic=true. */
+    seed?: number;
+    /**
+     * When true, the game loop starts immediately and sprites swap from color → image as
+     * they load in the background. When false (default) the loop is held until every
+     * sprite that is part of the initial scene has finished loading, so the first frame
+     * shown is fully rendered with real assets.
+     */
+    asyncAssets?: boolean;
+    /** Custom plugins to register after core systems. Each plugin's systems run after Render. */
+    plugins?: Plugin[];
+    /**
+     * Custom render system constructor. Must implement the System interface and accept
+     * `(canvas: HTMLCanvasElement, entityIds: Map<string, EntityId>)`.
+     *
+     * Defaults to the built-in Canvas2D RenderSystem.
+     * Example: `import { WebGLRenderSystem } from '@cubeforge/webgl-renderer'`
+     */
+    renderer?: new (canvas: HTMLCanvasElement, entityIds: Map<string, EntityId>) => System;
+    style?: CSSProperties;
+    className?: string;
+    children?: React__default.ReactNode;
+}
+declare function Game({ width, height, gravity, debug, devtools, scale, deterministic, seed, asyncAssets, onReady, plugins, renderer: CustomRenderer, style, className, children, }: GameProps): react_jsx_runtime.JSX.Element;
+
+interface WorldProps {
+    /** Gravitational acceleration in pixels/s² (default inherited from Game) */
+    gravity?: number;
+    /** Canvas background color */
+    background?: string;
+    children?: ReactNode;
+}
+declare function World({ gravity, background, children }: WorldProps): react_jsx_runtime.JSX.Element;
+
+interface EntityProps {
+    /** Optional string ID for cross-entity lookups (e.g. camera follow) */
+    id?: string;
+    /** Tags for grouping / querying (e.g. ['enemy', 'damageable']) */
+    tags?: string[];
+    children?: ReactNode;
+}
+declare function Entity({ id, tags, children }: EntityProps): react_jsx_runtime.JSX.Element | null;
+
+interface TransformProps {
+    x?: number;
+    y?: number;
+    rotation?: number;
+    scaleX?: number;
+    scaleY?: number;
+}
+declare function Transform({ x, y, rotation, scaleX, scaleY }: TransformProps): null;
+
+/** Maps frame names to frameIndex numbers */
+type SpriteAtlas = Record<string, number>;
+/**
+ * Helper to build an atlas from a grid spritesheet.
+ * columns = number of frames per row.
+ * names = frame names in row-major order.
+ */
+declare function createAtlas(names: string[], _columns: number): SpriteAtlas;
+
+interface SpriteProps {
+    width: number;
+    height: number;
+    color?: string;
+    src?: string;
+    offsetX?: number;
+    offsetY?: number;
+    zIndex?: number;
+    visible?: boolean;
+    flipX?: boolean;
+    anchorX?: number;
+    anchorY?: number;
+    frameIndex?: number;
+    frameWidth?: number;
+    frameHeight?: number;
+    frameColumns?: number;
+    atlas?: SpriteAtlas;
+    frame?: string;
+    tileX?: boolean;
+    tileY?: boolean;
+}
+declare function Sprite({ width, height, color, src, offsetX, offsetY, zIndex, visible, flipX, anchorX, anchorY, frameIndex, frameWidth, frameHeight, frameColumns, atlas, frame, tileX, tileY, }: SpriteProps): null;
+
+interface TextProps {
+    text: string;
+    fontSize?: number;
+    fontFamily?: string;
+    color?: string;
+    align?: CanvasTextAlign;
+    baseline?: CanvasTextBaseline;
+    zIndex?: number;
+    visible?: boolean;
+    maxWidth?: number;
+    offsetX?: number;
+    offsetY?: number;
+}
+declare function Text({ text, fontSize, fontFamily, color, align, baseline, zIndex, visible, maxWidth, offsetX, offsetY, }: TextProps): null;
+
+interface RigidBodyProps {
+    mass?: number;
+    gravityScale?: number;
+    isStatic?: boolean;
+    bounce?: number;
+    friction?: number;
+    vx?: number;
+    vy?: number;
+    /** Prevent any horizontal movement — velocity.x is zeroed every frame */
+    lockX?: boolean;
+    /** Prevent any vertical movement — velocity.y is zeroed every frame (disables gravity) */
+    lockY?: boolean;
+}
+declare function RigidBody({ mass, gravityScale, isStatic, bounce, friction, vx, vy, lockX, lockY, }: RigidBodyProps): null;
+
+interface BoxColliderProps {
+    width: number;
+    height: number;
+    offsetX?: number;
+    offsetY?: number;
+    isTrigger?: boolean;
+    layer?: string;
+    /** Which layers this collider interacts with. '*' = all (default). */
+    mask?: string | string[];
+    /**
+     * One-way platform: only blocks entities falling onto the top surface.
+     * Entities below pass through freely (useful for jump-through ledges).
+     */
+    oneWay?: boolean;
+}
+declare function BoxCollider({ width, height, offsetX, offsetY, isTrigger, layer, mask, oneWay, }: BoxColliderProps): null;
+
+interface CircleColliderProps {
+    radius: number;
+    offsetX?: number;
+    offsetY?: number;
+    isTrigger?: boolean;
+    layer?: string;
+    /** Which layers this collider interacts with. '*' = all (default). */
+    mask?: string | string[];
+}
+declare function CircleCollider({ radius, offsetX, offsetY, isTrigger, layer, mask, }: CircleColliderProps): null;
+
+interface CapsuleColliderProps {
+    width: number;
+    height: number;
+    offsetX?: number;
+    offsetY?: number;
+    isTrigger?: boolean;
+    layer?: string;
+    mask?: string | string[];
+}
+declare function CapsuleCollider({ width, height, offsetX, offsetY, isTrigger, layer, mask, }: CapsuleColliderProps): null;
+
+interface ScriptProps {
+    /** Called once when the entity is mounted — use to attach extra components */
+    init?: (entityId: EntityId, world: ECSWorld) => void;
+    /** Called every frame */
+    update: ScriptUpdateFn | ((entityId: EntityId, world: ECSWorld, input: InputManager, dt: number) => void);
+}
+declare function Script({ init, update }: ScriptProps): null;
+
+interface Camera2DProps {
+    /** String ID of entity to follow */
+    followEntity?: string;
+    /** Initial camera X position in world space (default 0 = world origin at screen center) */
+    x?: number;
+    /** Initial camera Y position in world space (default 0 = world origin at screen center) */
+    y?: number;
+    zoom?: number;
+    /** Lerp smoothing factor (0 = instant snap, 0.85 = smooth) */
+    smoothing?: number;
+    background?: string;
+    bounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    deadZone?: {
+        w: number;
+        h: number;
+    };
+    /** World-space offset applied to the follow target (look-ahead, vertical bias, etc.) */
+    followOffsetX?: number;
+    followOffsetY?: number;
+}
+declare function Camera2D({ followEntity, x, y, zoom, smoothing, background, bounds, deadZone, followOffsetX, followOffsetY, }: Camera2DProps): null;
+
+interface AnimationProps {
+    /** Frame indices to play (indexes into the sprite sheet) */
+    frames: number[];
+    /** Frames per second, default 12 */
+    fps?: number;
+    /** Whether to loop, default true */
+    loop?: boolean;
+    /** Whether currently playing, default true */
+    playing?: boolean;
+    /** Called once when a non-looping animation finishes playing */
+    onComplete?: () => void;
+    /**
+     * Callbacks fired when the animation advances to specific frame indices.
+     * Key = 0-based position in the `frames` array.
+     *
+     * @example
+     * frameEvents={{ 2: () => playFootstep(), 5: () => playFootstep() }}
+     */
+    frameEvents?: Record<number, () => void>;
+}
+declare function Animation({ frames, fps, loop, playing, onComplete, frameEvents }: AnimationProps): null;
+
+interface SquashStretchProps {
+    /** How much to squash/stretch (default 0.2) */
+    intensity?: number;
+    /** How fast it returns to 1.0 — lerp speed (default 8) */
+    recovery?: number;
+}
+declare function SquashStretch({ intensity, recovery }: SquashStretchProps): null;
+
+type ParticlePreset = 'explosion' | 'spark' | 'smoke' | 'coinPickup' | 'jumpDust';
+
+interface ParticleEmitterProps {
+    active?: boolean;
+    /** Named preset — values can be overridden by explicit props */
+    preset?: ParticlePreset;
+    /** Particles per second, default 20 */
+    rate?: number;
+    /** Initial particle speed (pixels/s), default 80 */
+    speed?: number;
+    /** Angle spread in radians, default Math.PI */
+    spread?: number;
+    /** Base emit angle in radians (0=right, -PI/2=up), default -Math.PI/2 */
+    angle?: number;
+    /** Particle lifetime in seconds, default 0.8 */
+    particleLife?: number;
+    /** Particle size in pixels, default 4 */
+    particleSize?: number;
+    /** Particle color, default '#ffffff' */
+    color?: string;
+    /** Gravity applied to particles (pixels/s²), default 200 */
+    gravity?: number;
+    /** Maximum live particles, default 100 */
+    maxParticles?: number;
+}
+declare function ParticleEmitter({ active, preset, rate, speed, spread, angle, particleLife, particleSize, color, gravity, maxParticles, }: ParticleEmitterProps): null;
+
+interface VirtualJoystickProps {
+    /** Diameter of the joystick base in pixels (default 120) */
+    size?: number;
+    /** Screen corner to anchor to (default 'left') */
+    position?: 'left' | 'right';
+    /** Extra CSS applied to the outer container */
+    style?: React__default.CSSProperties;
+    /** Show an action button (e.g. jump) alongside the joystick (default false) */
+    actionButton?: boolean;
+    /** Label shown on the action button (default 'A') */
+    actionLabel?: string;
+    /** Name of the virtual button to set (default 'action') */
+    actionName?: string;
+}
+/**
+ * On-screen virtual joystick for touch / mobile. Place it as a sibling of the
+ * `<Game>` canvas (inside a `position: relative` container).
+ *
+ * Read the joystick state with `useVirtualInput()`.
+ *
+ * @example
+ * <div style={{ position: 'relative' }}>
+ *   <Game ...>...</Game>
+ *   <VirtualJoystick position="left" actionButton />
+ * </div>
+ *
+ * // Inside an entity:
+ * function MobilePlayer() {
+ *   const virt = useVirtualInput()
+ *   // virt.axisX, virt.axisY, virt.button('action')
+ * }
+ */
+declare function VirtualJoystick({ size, position, style, actionButton, actionLabel, actionName, }: VirtualJoystickProps): react_jsx_runtime.JSX.Element;
+
+interface MovingPlatformProps {
+    /** Start position */
+    x1: number;
+    y1: number;
+    /** End position */
+    x2: number;
+    y2: number;
+    width?: number;
+    height?: number;
+    /** Seconds for a full round trip (default 3) */
+    duration?: number;
+    color?: string;
+}
+/**
+ * A static platform that oscillates between (x1,y1) and (x2,y2).
+ *
+ * @example
+ * <MovingPlatform x1={200} y1={350} x2={450} y2={350} width={120} duration={2.5} />
+ */
+declare function MovingPlatform({ x1, y1, x2, y2, width, height, duration, color, }: MovingPlatformProps): React__default.ReactElement;
+
+interface CheckpointProps {
+    x: number;
+    y: number;
+    width?: number;
+    height?: number;
+    color?: string;
+    /** Called once when a 'player'-tagged entity enters the checkpoint */
+    onActivate?: () => void;
+}
+/**
+ * A trigger zone that fires `onActivate` once when a player-tagged entity enters it.
+ *
+ * @example
+ * <Checkpoint x={800} y={450} onActivate={() => setCheckpoint(800)} />
+ */
+declare function Checkpoint({ x, y, width, height, color, onActivate, }: CheckpointProps): React__default.ReactElement;
+
+interface TiledProperty {
+    name: string;
+    type: string;
+    value: string | number | boolean;
+}
+interface TiledObject {
+    id: number;
+    name: string;
+    type: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    properties?: TiledProperty[];
+}
+interface TiledLayer {
+    type: 'tilelayer' | 'objectgroup';
+    name: string;
+    visible: boolean;
+    opacity: number;
+    data?: number[];
+    objects?: TiledObject[];
+    properties?: TiledProperty[];
+}
+interface TilemapProps {
+    /** URL to the Tiled JSON file */
+    src: string;
+    /**
+     * Object layer spawner: called for each object in object layers.
+     * Return a React element or null.
+     */
+    onSpawnObject?: (obj: TiledObject, layer: TiledLayer) => React__default.ReactNode;
+    /**
+     * Layer filter: return false to skip rendering/processing a layer.
+     * Default: all layers rendered.
+     */
+    layerFilter?: (layer: TiledLayer) => boolean;
+    /** Z-index for tile sprites (default 0) */
+    zIndex?: number;
+    /**
+     * Name of the layer (or layers with property `collision: true`) that
+     * should create invisible solid colliders. Default: "collision".
+     */
+    collisionLayer?: string;
+    /**
+     * Name of the layer (or layers with property `trigger: true`) that
+     * should create trigger BoxColliders (no sprite). Default: "triggers".
+     */
+    triggerLayer?: string;
+    /**
+     * Called for every tile that has custom properties defined in the tileset.
+     * Receives the global tile ID, the property map, and the tile's world position.
+     */
+    onTileProperty?: (tileId: number, properties: Record<string, unknown>, x: number, y: number) => void;
+    /**
+     * If provided, collision-layer tiles automatically mark the corresponding
+     * NavGrid cells as non-walkable. The grid must already be created with the
+     * correct dimensions (map.width × map.height) and cellSize (map.tilewidth).
+     */
+    navGrid?: NavGrid;
+    /**
+     * Name of the object layer that contains spawn markers.
+     * Objects in this layer are forwarded to `onSpawnObject` just like any
+     * other object layer, but they are also identified as spawn points so you
+     * can filter them by `layer.name === spawnLayer` inside the callback.
+     */
+    spawnLayer?: string;
+}
+declare function Tilemap({ src, onSpawnObject, layerFilter, zIndex, collisionLayer, triggerLayer: triggerLayerName, onTileProperty, navGrid, }: TilemapProps): React__default.ReactElement | null;
+
+interface ParallaxLayerProps {
+    /** Image URL to use as the background layer */
+    src: string;
+    /** Scroll speed relative to camera (0 = fixed, 1 = moves with camera, 0.3 = slow parallax). Default 0.5 */
+    speedX?: number;
+    /** Vertical scroll speed relative to camera. Default 0 */
+    speedY?: number;
+    /** Tile image horizontally. Default true */
+    repeatX?: boolean;
+    /** Tile image vertically. Default false */
+    repeatY?: boolean;
+    /** Render order — use negative values to render behind sprites. Default -10 */
+    zIndex?: number;
+    /** Manual horizontal offset in pixels. Default 0 */
+    offsetX?: number;
+    /** Manual vertical offset in pixels. Default 0 */
+    offsetY?: number;
+}
+/**
+ * A background layer that scrolls at a fraction of the camera speed to create depth.
+ *
+ * @example
+ * <ParallaxLayer src="/bg/sky.png" speedX={0.2} repeatX />
+ * <ParallaxLayer src="/bg/mountains.png" speedX={0.5} repeatX zIndex={-5} />
+ */
+declare function ParallaxLayer({ src, speedX, speedY, repeatX, repeatY, zIndex, offsetX, offsetY, }: ParallaxLayerProps): React__default.ReactElement;
+
+interface ScreenFlashHandle {
+    flash(color: string, duration: number): void;
+}
+declare const ScreenFlash: React.ForwardRefExoticComponent<React.RefAttributes<ScreenFlashHandle>>;
+
+interface CameraZoneProps {
+    /** World-space center X of the trigger zone */
+    x: number;
+    /** World-space center Y of the trigger zone */
+    y: number;
+    /** Half-width of the trigger zone */
+    width: number;
+    /** Half-height of the trigger zone */
+    height: number;
+    /**
+     * When an entity with this tag enters the zone, the camera stops following
+     * its entity and locks to the fixed position (targetX, targetY).
+     */
+    watchTag?: string;
+    /** Fixed world-space X the camera moves to when activated (defaults to zone center) */
+    targetX?: number;
+    /** Fixed world-space Y the camera moves to when activated (defaults to zone center) */
+    targetY?: number;
+    children?: React__default.ReactNode;
+}
+/**
+ * Invisible trigger area. When the player (or another tagged entity) enters
+ * the zone, the camera follow entity is cleared and the camera locks to the
+ * zone's center (or a custom target). On exit, the camera resumes following.
+ *
+ * Zone detection runs inside the ScriptSystem tick — it respects pause and
+ * deterministic stepping.
+ *
+ * @example
+ * ```tsx
+ * <CameraZone x={500} y={300} width={200} height={150} watchTag="player" />
+ * ```
+ */
+declare function CameraZone({ x, y, width, height, watchTag, targetX, targetY, children, }: CameraZoneProps): react_jsx_runtime.JSX.Element;
+
+interface TrailProps {
+    /** Maximum number of trail points (default 20) */
+    length?: number;
+    /** CSS color string (default '#ffffff') */
+    color?: string;
+    /** Trail width in pixels (default 3) */
+    width?: number;
+}
+/**
+ * Renders a fading polyline that follows the entity's position.
+ *
+ * The trail is drawn in the render pass — it uses the entity's Transform
+ * history collected each frame.
+ *
+ * Must be used inside an `<Entity>` with a `<Transform>`.
+ *
+ * @example
+ * ```tsx
+ * <Entity id="bullet">
+ *   <Transform x={x} y={y} />
+ *   <Sprite width={6} height={6} color="#ff0" />
+ *   <Trail length={15} color="#ff0" width={2} />
+ * </Entity>
+ * ```
+ */
+declare function Trail({ length, color, width }: TrailProps): null;
+
+interface AssetLoaderProps {
+    /** List of asset URLs to preload */
+    assets: string[];
+    /** Shown while assets are loading */
+    fallback?: React__default.ReactNode;
+    /** Called if any asset fails to load */
+    onError?: (err: Error) => void;
+    children: React__default.ReactNode;
+}
+/**
+ * Suspense-style asset loading boundary.
+ *
+ * Shows `fallback` until all assets in the list are loaded (or errored).
+ * Once loaded, renders `children`.
+ *
+ * @example
+ * ```tsx
+ * <AssetLoader
+ *   assets={['/hero.png', '/tiles.png', '/jump.wav']}
+ *   fallback={<div>Loading…</div>}
+ * >
+ *   <GameScene />
+ * </AssetLoader>
+ * ```
+ */
+declare function AssetLoader({ assets, fallback, onError, children }: AssetLoaderProps): react_jsx_runtime.JSX.Element;
+
+declare function useGame(): EngineState;
+
+interface CameraControls {
+    /**
+     * Trigger a screen-shake effect.
+     * @param intensity - Maximum pixel displacement per frame.
+     * @param duration  - How long the shake lasts in seconds.
+     */
+    shake(intensity: number, duration: number): void;
+    /**
+     * Set the world-space offset applied to the camera's follow target.
+     * Useful for look-ahead: `setFollowOffset(facing * 80, 0)`.
+     */
+    setFollowOffset(x: number, y: number): void;
+    /**
+     * Instantly move the camera center to a world-space position.
+     * Bypasses smoothing — useful for instant scene cuts.
+     */
+    setPosition(x: number, y: number): void;
+    /**
+     * Programmatically set the camera zoom level.
+     */
+    setZoom(zoom: number): void;
+}
+/**
+ * Returns controls for the active Camera2D in the scene.
+ * Must be used inside `<Game>`.
+ *
+ * @example
+ * ```tsx
+ * function HUD() {
+ *   const camera = useCamera()
+ *   return (
+ *     <button onClick={() => camera.shake(8, 0.4)}>Shake!</button>
+ *   )
+ * }
+ * ```
+ */
+declare function useCamera(): CameraControls;
+
+interface SnapshotControls {
+    /**
+     * Capture a full serialisable snapshot of all ECS entity/component data.
+     * Safe to JSON-stringify and store externally (localStorage, server, etc.)
+     *
+     * @example
+     * ```ts
+     * const { save, restore } = useSnapshot()
+     * const checkpoint = save()          // capture at checkpoint
+     * restore(checkpoint)                // reset to that state
+     * ```
+     */
+    save(): WorldSnapshot;
+    /**
+     * Restore the world to a previously captured snapshot.
+     * All current entities are replaced with the snapshot's entities.
+     *
+     * Note: React component state is NOT rolled back — only ECS data is restored.
+     * For a full game reset, prefer remounting the `<Game>` key instead.
+     */
+    restore(snapshot: WorldSnapshot): void;
+}
+/**
+ * Returns save/restore controls for the ECS world snapshot system.
+ * Must be used inside `<Game>`.
+ *
+ * @example
+ * ```tsx
+ * function SaveButton() {
+ *   const { save, restore } = useSnapshot()
+ *   const [slot, setSlot] = useState<WorldSnapshot | null>(null)
+ *   return (
+ *     <>
+ *       <button onClick={() => setSlot(save())}>Save</button>
+ *       <button onClick={() => slot && restore(slot)}>Load</button>
+ *     </>
+ *   )
+ * }
+ * ```
+ */
+declare function useSnapshot(): SnapshotControls;
+
+declare function useEntity(): EntityId;
+
+/**
+ * Returns a function that destroys the current entity on the next ECS update.
+ * Must be used inside `<Entity>`.
+ *
+ * Useful for collectibles, projectiles, or any entity that needs to destroy
+ * itself in response to a collision or trigger event.
+ *
+ * @example
+ * function CoinPickup() {
+ *   const destroy = useDestroyEntity()
+ *   useTriggerEnter(() => {
+ *     collectCoin()
+ *     destroy()
+ *   }, { tag: 'player' })
+ *   return null
+ * }
+ */
+declare function useDestroyEntity(): () => void;
+
+interface VirtualInputState {
+    /** Left–right axis in [−1, 1]. Positive = right. */
+    readonly axisX: number;
+    /** Up–down axis in [−1, 1]. Positive = down. */
+    readonly axisY: number;
+    /** Whether a named virtual button is currently pressed. */
+    button(name: string): boolean;
+}
+/**
+ * Returns the current state of the on-screen virtual joystick and buttons.
+ * Reads synchronously from the module-level store — safe to call in a Script
+ * update function every frame without triggering React re-renders.
+ *
+ * Combine with keyboard or gamepad input for multi-input support:
+ *
+ * @example
+ * function MobilePlayer() {
+ *   const input = useInput()
+ *   const virt  = useVirtualInput()
+ *
+ *   // Script update:
+ *   const moveX = input.isHeld('ArrowRight') ? 1
+ *               : input.isHeld('ArrowLeft')  ? -1
+ *               : virt.axisX
+ *   const jump  = input.isPressed('Space') || virt.button('action')
+ * }
+ */
+declare function useVirtualInput(): VirtualInputState;
+
+declare function useInput(): InputManager;
+
+interface BoundInputMap {
+    /** True every frame any bound key is held. */
+    isActionDown(action: string): boolean;
+    /** True only on the first frame any bound key was pressed. */
+    isActionPressed(action: string): boolean;
+    /** True only on the frame any bound key was released. */
+    isActionReleased(action: string): boolean;
+    /**
+     * Returns -1..1 for axis bindings. For key bindings, 1 if down, 0 otherwise.
+     * @see {@link AxisBinding}
+     */
+    getAxis(action: string): number;
+    /**
+     * Alias for `getAxis`. Matches the `PlayerInput` naming convention — use this
+     * when writing code that needs to work with both `useInputMap` and `usePlayerInput`.
+     */
+    getActionAxis(action: string): number;
+}
+/**
+ * React hook that returns a pre-bound action map for use inside `<Game>`.
+ *
+ * @example
+ * ```tsx
+ * function MyScript() {
+ *   const actions = useInputMap({
+ *     left:  ['ArrowLeft', 'KeyA'],
+ *     right: ['ArrowRight', 'KeyD'],
+ *     jump:  ['Space', 'ArrowUp', 'KeyW'],
+ *   })
+ *   // use actions.isActionDown('left') in a Script update or game loop callback
+ * }
+ * ```
+ */
+declare function useInputMap(bindings: ActionBindings): BoundInputMap;
+
+declare function useEvents(): EventBus;
+declare function useEvent<T>(event: string, handler: (data: T) => void): void;
+
+interface CoordinateHelpers {
+    /**
+     * Convert a world-space position to canvas pixel coordinates.
+     * Takes current camera position and zoom into account.
+     */
+    worldToScreen(wx: number, wy: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Convert canvas pixel coordinates to world-space position.
+     * Takes current camera position and zoom into account.
+     */
+    screenToWorld(sx: number, sy: number): {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Returns helpers for converting between world-space and screen (canvas pixel) coordinates.
+ *
+ * @example
+ * ```tsx
+ * function Minimap() {
+ *   const { worldToScreen, screenToWorld } = useCoordinates()
+ *   // worldToScreen(player.x, player.y) → canvas pixel position of player
+ * }
+ * ```
+ */
+declare function useCoordinates(): CoordinateHelpers;
+
+interface PreloadState {
+    /** 0–1 loading progress */
+    progress: number;
+    /** True when all assets have finished loading (or errored) */
+    loaded: boolean;
+    /** First error encountered, if any */
+    error: Error | null;
+}
+/**
+ * Preloads a list of asset URLs using the engine's AssetManager.
+ * Returns loading progress and a `loaded` flag.
+ *
+ * Works with images (any extension) — audio goes through the engine's audio API.
+ *
+ * @example
+ * ```tsx
+ * function Level() {
+ *   const { progress, loaded } = usePreload(['/hero.png', '/tiles.png'])
+ *   if (!loaded) return <LoadingBar progress={progress} />
+ *   return <GameScene />
+ * }
+ * ```
+ */
+declare function usePreload(assets: string[]): PreloadState;
+
+interface InputContextControls {
+    push(ctx: InputContextName): void;
+    pop(ctx: InputContextName): void;
+    readonly active: InputContextName;
+}
+/**
+ * Access and manipulate the global input context stack.
+ *
+ * If you pass a `ctx` argument, that context is automatically pushed on mount
+ * and popped on unmount — ideal for pause menus, cutscenes, etc.
+ *
+ * @example
+ * ```tsx
+ * function PauseMenu() {
+ *   useInputContext('pause') // auto-push/pop
+ *   return <div>Paused</div>
+ * }
+ * ```
+ */
+declare function useInputContext(ctx?: InputContextName): InputContextControls;
+
+/**
+ * Returns a `PlayerInput` bound to the shared InputManager for the given player ID.
+ *
+ * @param playerId  - Player number (1-based).
+ * @param bindings  - Action bindings for this player.
+ *
+ * @example
+ * ```tsx
+ * function P1({ x, y }: Props) {
+ *   const p1 = usePlayerInput(1, { jump: 'Space', left: 'ArrowLeft', right: 'ArrowRight' })
+ *   return (
+ *     <Entity id="p1">
+ *       <Script update={(id, world, input, dt) => {
+ *         if (p1.isActionPressed('jump')) rb.vy = -400
+ *       }} />
+ *     </Entity>
+ *   )
+ * }
+ * ```
+ */
+declare function usePlayerInput(playerId: number, bindings: ActionBindings): PlayerInput;
+
+/**
+ * Returns an array of `PlayerInput` objects for local multiplayer.
+ * Each player gets their own action bindings.
+ *
+ * @param bindingsPerPlayer - Array of binding objects, one per player.
+ *
+ * @example
+ * ```tsx
+ * const [p1, p2] = useLocalMultiplayer([
+ *   { jump: 'Space', left: 'ArrowLeft', right: 'ArrowRight' },
+ *   { jump: 'KeyW',  left: 'KeyA',      right: 'KeyD' },
+ * ])
+ * ```
+ */
+declare function useLocalMultiplayer(bindingsPerPlayer: ActionBindings[]): PlayerInput[];
+
+/**
+ * Returns an `InputRecorderControls` instance that persists across renders.
+ *
+ * Use inside a `<Script update>` to drive recording/playback:
+ *
+ * @example
+ * ```tsx
+ * function DemoPlayer() {
+ *   const recorder = useInputRecorder()
+ *
+ *   return (
+ *     <Script update={(id, world, input, dt) => {
+ *       if (recorder.isRecording) {
+ *         recorder.captureFrame([...downKeys])
+ *       }
+ *       if (recorder.isPlaying) {
+ *         const frame = recorder.advancePlayback()
+ *         // apply frame.pressedKeys to player controller
+ *       }
+ *     }} />
+ *   )
+ * }
+ * ```
+ */
+declare function useInputRecorder(): InputRecorderControls;
+
+interface GamepadState {
+    /** Whether a gamepad is connected at this player index. */
+    connected: boolean;
+    /**
+     * Normalised axis values (typically −1 to +1).
+     * Index 0 = left stick X, 1 = left stick Y, 2 = right stick X, 3 = right stick Y
+     * (varies by browser / controller).
+     */
+    axes: readonly number[];
+    /**
+     * Button pressed states.
+     * Standard mapping: 0=A/Cross, 1=B/Circle, 2=X/Square, 3=Y/Triangle,
+     * 4=LB, 5=RB, 12=DPad-Up, 13=DPad-Down, 14=DPad-Left, 15=DPad-Right
+     */
+    buttons: readonly boolean[];
+}
+/**
+ * Polls the Gamepad API every frame and returns the current state.
+ *
+ * @param playerIndex - Which gamepad slot to read (0–3). Default 0.
+ *
+ * @example
+ * function MoveWithGamepad() {
+ *   const gp = useGamepad()
+ *   // gp.axes[0] = left stick horizontal
+ *   // gp.buttons[0] = A button
+ * }
+ */
+declare function useGamepad(playerIndex?: number): GamepadState;
+
+interface PauseControls {
+    paused: boolean;
+    pause(): void;
+    resume(): void;
+    toggle(): void;
+}
+/**
+ * Controls the game loop pause state from inside a `<Game>` tree.
+ *
+ * @example
+ * function PauseButton() {
+ *   const { paused, toggle } = usePause()
+ *   return <button onClick={toggle}>{paused ? 'Resume' : 'Pause'}</button>
+ * }
+ */
+declare function usePause(): PauseControls;
+
+export { Animation, AssetLoader, type BoundInputMap, BoxCollider, Camera2D, type CameraControls, CameraZone, CapsuleCollider, Checkpoint, CircleCollider, type CoordinateHelpers, Entity, Game, type GameControls, type GamepadState, type InputContextControls, MovingPlatform, ParallaxLayer, ParticleEmitter, type ParticlePreset, type PauseControls, type PreloadState, RigidBody, ScreenFlash, type ScreenFlashHandle, Script, type SnapshotControls, Sprite, type SpriteAtlas, SquashStretch, Text, type TiledLayer, type TiledObject, Tilemap, Trail, Transform, type VirtualInputState, VirtualJoystick, type VirtualJoystickProps, World, createAtlas, useCamera, useCoordinates, useDestroyEntity, useEntity, useEvent, useEvents, useGame, useGamepad, useInput, useInputContext, useInputMap, useInputRecorder, useLocalMultiplayer, usePause, usePlayerInput, usePreload, useSnapshot, useVirtualInput };