cubeforge 0.1.2 → 0.1.4

package/dist/index.d.mts

@@ -0,0 +1,619 @@
+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, EventBus, AssetManager, GameLoop, WorldSnapshot } from '@cubeforge/core';
+export { Component, ECSWorld, Ease, EntityId, Plugin, ScriptUpdateFn, TransformComponent, TweenHandle, WorldSnapshot, createTag, createTransform, definePlugin, findByTag, tween } from '@cubeforge/core';
+import { InputManager, ActionBindings } from '@cubeforge/input';
+export { ActionBindings, InputManager, InputMap, createInputMap } from '@cubeforge/input';
+import { Canvas2DRenderer, RenderSystem } from '@cubeforge/renderer';
+export { AnimationStateComponent, ParallaxLayerComponent, Particle, ParticlePoolComponent, SpriteComponent, SquashStretchComponent, createSprite } from '@cubeforge/renderer';
+import { PhysicsSystem } from '@cubeforge/physics';
+export { BoxColliderComponent, CircleColliderComponent, RaycastHit, RigidBodyComponent, overlapBox, raycast } from '@cubeforge/physics';
+
+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;
+}
+declare function Sprite({ width, height, color, src, offsetX, offsetY, zIndex, visible, flipX, anchorX, anchorY, frameIndex, frameWidth, frameHeight, frameColumns, atlas, frame, }: SpriteProps): 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 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;
+}
+declare function Animation({ frames, fps, loop, playing, onComplete }: 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 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;
+}
+declare function Tilemap({ src, onSpawnObject, layerFilter, zIndex, collisionLayer, triggerLayer: triggerLayerName, onTileProperty, }: 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 EngineState {
+    ecs: ECSWorld;
+    input: InputManager;
+    /** Canvas2D renderer. Undefined when a custom WebGL renderer is used via the `renderer` Game prop. */
+    renderer?: Canvas2DRenderer;
+    /** The active render system. Undefined when a custom renderer is used. */
+    renderSystem?: RenderSystem;
+    physics: PhysicsSystem;
+    events: EventBus;
+    assets: AssetManager;
+    loop: GameLoop;
+    canvas: HTMLCanvasElement;
+    /** Maps string entity IDs (e.g. "player") to numeric ECS EntityIds */
+    entityIds: Map<string, EntityId>;
+}
+
+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;
+
+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;
+}
+/**
+ * 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 PlatformerControllerOptions {
+    /** Horizontal move speed in px/s (default 200) */
+    speed?: number;
+    /** Upward impulse on jump (default -500) */
+    jumpForce?: number;
+    /** Max consecutive jumps, e.g. 2 for double jump (default 1) */
+    maxJumps?: number;
+    /** Seconds after leaving ground the player can still jump (default 0.08) */
+    coyoteTime?: number;
+    /** Seconds to buffer a jump input before landing (default 0.08) */
+    jumpBuffer?: number;
+}
+/**
+ * Attaches platformer movement (WASD/Arrows + Space/Up to jump) to an entity.
+ * The entity must already have a RigidBody component.
+ *
+ * @example
+ * function Player() {
+ *   const id = useEntity()
+ *   usePlatformerController(id, { speed: 220, maxJumps: 2 })
+ *   return (
+ *     <Entity id="player">
+ *       <Transform x={100} y={300} />
+ *       <Sprite width={28} height={40} color="#4fc3f7" />
+ *       <RigidBody />
+ *       <BoxCollider width={26} height={40} />
+ *     </Entity>
+ *   )
+ * }
+ */
+declare function usePlatformerController(entityId: EntityId, opts?: PlatformerControllerOptions): void;
+
+interface TopDownMovementOptions {
+    /** Movement speed in px/s (default 200) */
+    speed?: number;
+    /** Normalize diagonal movement to avoid faster diagonal movement (default true) */
+    normalizeDiagonal?: boolean;
+}
+/**
+ * Attaches 4-directional top-down movement (WASD/Arrows) to an entity.
+ * The entity must have a RigidBody with gravityScale=0 for top-down games.
+ *
+ * @example
+ * <Entity id="player">
+ *   <Transform x={100} y={100} />
+ *   <Sprite width={24} height={24} color="#4fc3f7" />
+ *   <RigidBody gravityScale={0} />
+ *   <BoxCollider width={24} height={24} />
+ * </Entity>
+ * // In a Script or parent component:
+ * useTopDownMovement(playerId, { speed: 180 })
+ */
+declare function useTopDownMovement(entityId: EntityId, opts?: TopDownMovementOptions): void;
+
+interface ContactOpts {
+    /** Only fire if the other entity has this tag */
+    tag?: string;
+    /** Only fire if the other entity's BoxCollider is on this layer */
+    layer?: string;
+}
+/**
+ * Fires once when another entity's collider first overlaps this entity's trigger.
+ * Must be used inside an `<Entity>`.
+ *
+ * @example
+ * function CoinPickup() {
+ *   useTriggerEnter((other) => collectCoin(), { tag: 'player' })
+ *   return null
+ * }
+ */
+declare function useTriggerEnter(handler: (other: EntityId) => void, opts?: ContactOpts): void;
+/**
+ * Fires once when an overlapping entity's collider leaves this entity's trigger.
+ * Must be used inside an `<Entity>`.
+ */
+declare function useTriggerExit(handler: (other: EntityId) => void, opts?: ContactOpts): void;
+/**
+ * Fires once on the first frame two solid dynamic bodies touch.
+ * Must be used inside an `<Entity>`.
+ *
+ * @example
+ * function Enemy() {
+ *   useCollisionEnter((other) => takeDamage(), { tag: 'player' })
+ *   return null
+ * }
+ */
+declare function useCollisionEnter(handler: (other: EntityId) => void, opts?: ContactOpts): void;
+/**
+ * Fires once when two solid dynamic bodies separate.
+ * Must be used inside an `<Entity>`.
+ */
+declare function useCollisionExit(handler: (other: EntityId) => void, opts?: ContactOpts): void;
+/**
+ * Fires once when another entity's CircleCollider first overlaps this entity's CircleCollider.
+ * Also fires when a CircleCollider overlaps a BoxCollider.
+ * Must be used inside an `<Entity>`.
+ *
+ * @example
+ * function Asteroid() {
+ *   useCircleEnter((other) => onHit(other), { tag: 'bullet' })
+ *   return null
+ * }
+ */
+declare function useCircleEnter(handler: (other: EntityId) => void, opts?: ContactOpts): void;
+/**
+ * Fires once when two CircleCollider entities stop overlapping.
+ * Must be used inside an `<Entity>`.
+ */
+declare function useCircleExit(handler: (other: EntityId) => void, opts?: ContactOpts): void;
+
+interface DevToolsHandle {
+    buffer: WorldSnapshot[];
+    onFrame?: () => void;
+}
+
+export { Animation, type BoundInputMap, BoxCollider, Camera2D, type CameraControls, Checkpoint, CircleCollider, type DevToolsHandle, type EngineState, Entity, Game, type GameControls, MovingPlatform, ParallaxLayer, ParticleEmitter, type ParticlePreset, type PlatformerControllerOptions, RigidBody, ScreenFlash, type ScreenFlashHandle, Script, type SnapshotControls, Sprite, type SpriteAtlas, SquashStretch, type TiledLayer, type TiledObject, Tilemap, type TopDownMovementOptions, Transform, World, createAtlas, useCamera, useCircleEnter, useCircleExit, useCollisionEnter, useCollisionExit, useEntity, useEvent, useEvents, useGame, useInput, useInputMap, usePlatformerController, useSnapshot, useTopDownMovement, useTriggerEnter, useTriggerExit };