cubeforge 0.0.5 → 0.0.7

package/dist/components/Animation.d.ts

@@ -7,6 +7,8 @@ interface AnimationProps {
     loop?: boolean;
     /** Whether currently playing, default true */
     playing?: boolean;
+    /** Called once when a non-looping animation finishes playing */
+    onComplete?: () => void;
 }
-export declare function Animation({ frames, fps, loop, playing }: AnimationProps): null;
+export declare function Animation({ frames, fps, loop, playing, onComplete }: AnimationProps): null;
 export {};

package/dist/components/BoxCollider.d.ts

@@ -5,6 +5,13 @@ interface BoxColliderProps {
     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;
 }
-export declare function BoxCollider({ width, height, offsetX, offsetY, isTrigger, layer, }: BoxColliderProps): null;
+export declare function BoxCollider({ width, height, offsetX, offsetY, isTrigger, layer, mask, oneWay, }: BoxColliderProps): null;
 export {};

package/dist/components/Camera2D.d.ts

@@ -15,6 +15,9 @@ interface Camera2DProps {
         w: number;
         h: number;
     };
+    /** World-space offset applied to the follow target (look-ahead, vertical bias, etc.) */
+    followOffsetX?: number;
+    followOffsetY?: number;
 }
-export declare function Camera2D({ followEntity, zoom, smoothing, background, bounds, deadZone, }: Camera2DProps): null;
+export declare function Camera2D({ followEntity, zoom, smoothing, background, bounds, deadZone, followOffsetX, followOffsetY, }: Camera2DProps): null;
 export {};

package/dist/components/Checkpoint.d.ts

@@ -9,7 +9,7 @@ interface CheckpointProps {
     onActivate?: () => void;
 }
 /**
- * A trigger zone that fires `onActivate` when the player enters it, then destroys itself.
+ * A trigger zone that fires `onActivate` once when a player-tagged entity enters it.
  *
  * @example
  * <Checkpoint x={800} y={450} onActivate={() => setCheckpoint(800)} />

package/dist/components/CircleCollider.d.ts

@@ -0,0 +1,11 @@
+interface CircleColliderProps {
+    radius: number;
+    offsetX?: number;
+    offsetY?: number;
+    isTrigger?: boolean;
+    layer?: string;
+    /** Which layers this collider interacts with. '*' = all (default). */
+    mask?: string | string[];
+}
+export declare function CircleCollider({ radius, offsetX, offsetY, isTrigger, layer, mask, }: CircleColliderProps): null;
+export {};

package/dist/components/DevTools.d.ts

@@ -0,0 +1,15 @@
+import React from 'react';
+import type { WorldSnapshot } from '@cubeforge/core';
+import type { ECSWorld, GameLoop } from '@cubeforge/core';
+export declare const MAX_DEVTOOLS_FRAMES = 600;
+export interface DevToolsHandle {
+    buffer: WorldSnapshot[];
+    onFrame?: () => void;
+}
+interface DevToolsProps {
+    handle: DevToolsHandle;
+    loop: GameLoop;
+    ecs: ECSWorld;
+}
+export declare function DevToolsOverlay({ handle, loop, ecs }: DevToolsProps): React.ReactPortal;
+export {};

package/dist/components/Game.d.ts

@@ -1,5 +1,5 @@
 import React, { type CSSProperties } from 'react';
-import { type Plugin } from '@cubeforge/core';
+import { type Plugin, type System, type EntityId } from '@cubeforge/core';
 export interface GameControls {
     pause(): void;
     resume(): void;
@@ -21,11 +21,25 @@ interface GameProps {
     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;
     /** 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.ReactNode;
 }
-export declare function Game({ width, height, gravity, debug, scale, onReady, plugins, style, className, children, }: GameProps): import("react/jsx-runtime").JSX.Element;
+export declare function Game({ width, height, gravity, debug, devtools, scale, deterministic, seed, onReady, plugins, renderer: CustomRenderer, style, className, children, }: GameProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/RigidBody.d.ts

@@ -6,6 +6,10 @@ interface RigidBodyProps {
     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;
 }
-export declare function RigidBody({ mass, gravityScale, isStatic, bounce, friction, vx, vy, }: RigidBodyProps): null;
+export declare function RigidBody({ mass, gravityScale, isStatic, bounce, friction, vx, vy, lockX, lockY, }: RigidBodyProps): null;
 export {};

package/dist/context.d.ts

@@ -1,12 +1,15 @@
 import type { ECSWorld, EventBus, AssetManager, EntityId } from '@cubeforge/core';
 import type { InputManager } from '@cubeforge/input';
-import type { Canvas2DRenderer } from '@cubeforge/renderer';
+import type { Canvas2DRenderer, RenderSystem } from '@cubeforge/renderer';
 import type { PhysicsSystem } from '@cubeforge/physics';
 import type { GameLoop } from '@cubeforge/core';
 export interface EngineState {
     ecs: ECSWorld;
     input: InputManager;
-    renderer: Canvas2DRenderer;
+    /** 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;

package/dist/hooks/useCamera.d.ts

@@ -0,0 +1,37 @@
+export 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>
+ *   )
+ * }
+ * ```
+ */
+export declare function useCamera(): CameraControls;

package/dist/hooks/useContact.d.ts

@@ -0,0 +1,57 @@
+import type { EntityId } from '@cubeforge/core';
+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
+ * }
+ */
+export 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>`.
+ */
+export 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
+ * }
+ */
+export declare function useCollisionEnter(handler: (other: EntityId) => void, opts?: ContactOpts): void;
+/**
+ * Fires once when two solid dynamic bodies separate.
+ * Must be used inside an `<Entity>`.
+ */
+export 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
+ * }
+ */
+export declare function useCircleEnter(handler: (other: EntityId) => void, opts?: ContactOpts): void;
+/**
+ * Fires once when two CircleCollider entities stop overlapping.
+ * Must be used inside an `<Entity>`.
+ */
+export declare function useCircleExit(handler: (other: EntityId) => void, opts?: ContactOpts): void;
+export {};

package/dist/hooks/useInputMap.d.ts

@@ -0,0 +1,25 @@
+import type { ActionBindings } from '@cubeforge/input';
+export 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
+ * }
+ * ```
+ */
+export declare function useInputMap(bindings: ActionBindings): BoundInputMap;

package/dist/hooks/useSnapshot.d.ts

@@ -0,0 +1,42 @@
+import type { WorldSnapshot } from '@cubeforge/core';
+export 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>
+ *     </>
+ *   )
+ * }
+ * ```
+ */
+export declare function useSnapshot(): SnapshotControls;

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export { Transform } from './components/Transform';
 export { Sprite } from './components/Sprite';
 export { RigidBody } from './components/RigidBody';
 export { BoxCollider } from './components/BoxCollider';
+export { CircleCollider } from './components/CircleCollider';
 export { Script } from './components/Script';
 export { Camera2D } from './components/Camera2D';
 export { Animation } from './components/Animation';
@@ -18,23 +19,35 @@ export { ScreenFlash } from './components/ScreenFlash';
 export type { ScreenFlashHandle } from './components/ScreenFlash';
 export type { TiledObject, TiledLayer } from './components/Tilemap';
 export { useGame } from './hooks/useGame';
+export { useCamera } from './hooks/useCamera';
+export type { CameraControls } from './hooks/useCamera';
+export { useSnapshot } from './hooks/useSnapshot';
+export type { SnapshotControls } from './hooks/useSnapshot';
 export { useEntity } from './hooks/useEntity';
 export { useInput } from './hooks/useInput';
+export { useInputMap } from './hooks/useInputMap';
 export { useEvents, useEvent } from './hooks/useEvents';
 export { usePlatformerController } from './hooks/usePlatformerController';
 export { useTopDownMovement } from './hooks/useTopDownMovement';
+export { useTriggerEnter, useTriggerExit, useCollisionEnter, useCollisionExit, useCircleEnter, useCircleExit } from './hooks/useContact';
 export type { SpriteAtlas } from './components/spriteAtlas';
 export { createAtlas } from './components/spriteAtlas';
 export type { EngineState } from './context';
 export type { GameControls } from './components/Game';
+export type { DevToolsHandle } from './components/DevTools';
 export type { PlatformerControllerOptions } from './hooks/usePlatformerController';
 export type { TopDownMovementOptions } from './hooks/useTopDownMovement';
-export type { EntityId, ECSWorld, ScriptUpdateFn, Plugin } from '@cubeforge/core';
-export { definePlugin } from '@cubeforge/core';
-export type { InputManager } from '@cubeforge/input';
+export type { EntityId, ECSWorld, ScriptUpdateFn, Plugin, WorldSnapshot } from '@cubeforge/core';
+export { definePlugin, findByTag } from '@cubeforge/core';
+export { overlapBox, raycast } from '@cubeforge/physics';
+export type { RaycastHit } from '@cubeforge/physics';
+export type { InputManager, ActionBindings, InputMap } from '@cubeforge/input';
+export { createInputMap } from '@cubeforge/input';
+export type { BoundInputMap } from './hooks/useInputMap';
 export type { TransformComponent } from '@cubeforge/core';
 export type { RigidBodyComponent } from '@cubeforge/physics';
 export type { BoxColliderComponent } from '@cubeforge/physics';
+export type { CircleColliderComponent } from '@cubeforge/physics';
 export type { SpriteComponent } from '@cubeforge/renderer';
 export type { AnimationStateComponent } from '@cubeforge/renderer';
 export type { SquashStretchComponent } from '@cubeforge/renderer';