cubeforge 0.5.2 → 0.6.1

package/dist/index.d.ts

@@ -503,7 +503,48 @@ interface SquashStretchProps {
 }
 declare function SquashStretch({ intensity, recovery }: SquashStretchProps): null;
 
-type ParticlePreset = 'explosion' | 'spark' | 'smoke' | 'coinPickup' | 'jumpDust';
+type ParticlePreset = 'explosion' | 'spark' | 'smoke' | 'coinPickup' | 'jumpDust' | 'fire' | 'magic' | 'rain' | 'snow' | 'confetti' | 'sparkle' | 'heal' | 'damage' | 'pickup' | 'fountain' | 'trail';
+interface ParticleEmitterConfig {
+    rate?: number;
+    speed?: number;
+    spread?: number;
+    angle?: number;
+    particleLife?: number;
+    particleSize?: number;
+    color?: string;
+    gravity?: number;
+    maxParticles?: number;
+    /** Colors to interpolate through over particle lifetime. */
+    colorOverLife?: string[];
+    /** Start/end size ratios for per-particle size curve (end is multiplier of particleSize). */
+    sizeOverLife?: {
+        start: number;
+        end: number;
+    };
+    /** Blend mode for the emitter (additive for glows, normal for solid). */
+    blendMode?: 'normal' | 'additive';
+    /** Particle shape: 'soft' gradient, 'circle' hard disc, 'square' quad. */
+    particleShape?: 'soft' | 'circle' | 'square';
+}
+/**
+ * Ready-made particle configurations. Pass via the `preset` prop on
+ * `<ParticleEmitter>`:
+ *
+ * ```tsx
+ * <ParticleEmitter preset="fire" />
+ * <ParticleEmitter preset="explosion" color="#8bc34a" />  // overrides
+ * ```
+ *
+ * Individual props always override preset values — presets are defaults.
+ *
+ * ## Catalog
+ *
+ * Action / combat: `explosion`, `spark`, `damage`, `heal`, `magic`
+ * Environment:     `fire`, `smoke`, `rain`, `snow`, `fountain`
+ * UI / reward:     `coinPickup`, `pickup`, `sparkle`, `confetti`
+ * Character:       `jumpDust`, `trail`
+ */
+declare const PARTICLE_PRESETS: Record<ParticlePreset, ParticleEmitterConfig>;
 
 interface ParticleEmitterProps {
     active?: boolean;
@@ -876,6 +917,100 @@ interface CameraZoneProps {
  */
 declare function CameraZone({ x, y, width, height, watchTag, targetX, targetY, children }: CameraZoneProps): react_jsx_runtime.JSX.Element;
 
+interface VirtualCameraConfig {
+    /** Unique identifier for this virtual camera. */
+    id: string;
+    /** Higher-priority cameras take control when active. Default 0. */
+    priority: number;
+    /** Whether this camera is currently contending for control. Default true. */
+    active: boolean;
+    /** Entity ID string to follow (same as Camera2D.followEntityId). */
+    followEntityId?: string;
+    /** Static world-space X when not following an entity. */
+    x?: number;
+    /** Static world-space Y when not following an entity. */
+    y?: number;
+    /** Zoom level. Default 1. */
+    zoom?: number;
+    /** Follow smoothing (0 = instant, 0.85 = smooth). Inherits Camera2D value when omitted. */
+    smoothing?: number;
+    /** World-space camera bounds clamp. */
+    bounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** How long (seconds) to blend when transitioning to this camera. Default 0.4. */
+    blendDuration: number;
+}
+interface VirtualCameraProps {
+    /** Unique ID used to identify and blend between cameras. */
+    id: string;
+    /**
+     * Higher values win when multiple virtual cameras are active simultaneously.
+     * Default 0.
+     */
+    priority?: number;
+    /** Whether this camera is currently competing for control. Default true. */
+    active?: boolean;
+    /**
+     * Entity string ID to follow (same semantics as `<Camera2D followEntity>`).
+     * Takes precedence over x/y when set.
+     */
+    followEntity?: string;
+    /** Static world-space X to center on (when not following an entity). */
+    x?: number;
+    /** Static world-space Y to center on (when not following an entity). */
+    y?: number;
+    /** Zoom level applied while this camera is active. Default 1. */
+    zoom?: number;
+    /**
+     * Follow-smoothing factor (0 = instant snap, 0.85 = very smooth).
+     * When omitted, inherits the current Camera2D smoothing.
+     */
+    smoothing?: number;
+    /** World-space bounds clamping while this camera is active. */
+    bounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /**
+     * Blend-in duration in seconds when transitioning to this camera.
+     * Use 0 for an instant cut. Default 0.4.
+     */
+    blendDuration?: number;
+}
+/**
+ * Declares a virtual camera that competes for control of the scene's
+ * `Camera2D`. The active virtual camera with the highest `priority` wins.
+ * Transitions between cameras blend smoothly over `blendDuration` seconds.
+ *
+ * Multiple `<VirtualCamera>` components can coexist. Toggle `active` to hand
+ * off camera control — ideal for cutscenes, boss arenas, and split focus.
+ *
+ * Must be placed inside `<Game>` alongside a `<Camera2D>`.
+ *
+ * @example
+ * ```tsx
+ * // Normal gameplay: follow the player
+ * <VirtualCamera id="main" priority={0} followEntity={playerId} zoom={1} active />
+ *
+ * // Boss fight: zoom out to show the arena
+ * <VirtualCamera
+ *   id="boss"
+ *   priority={10}
+ *   x={arenaX} y={arenaY}
+ *   zoom={0.7}
+ *   blendDuration={0.8}
+ *   active={bossActive}
+ * />
+ * ```
+ */
+declare function VirtualCamera({ id, priority, active, followEntity, x, y, zoom, smoothing, bounds, blendDuration, }: VirtualCameraProps): null;
+
 interface TrailProps {
     /** Maximum number of trail points (default 20) */
     length?: number;
@@ -1276,6 +1411,104 @@ interface CameraLookaheadOptions {
  */
 declare function useCameraLookahead(entityId: EntityId, opts?: CameraLookaheadOptions): void;
 
+interface CameraBlendControls {
+    /**
+     * Activate a registered virtual camera by id.
+     * If the camera has a lower priority than the current one, raising its
+     * priority temporarily is more ergonomic — but activating it is the
+     * simplest way to hand off control from code.
+     */
+    activate(id: string): void;
+    /**
+     * Deactivate a registered virtual camera by id.
+     * The next highest-priority active camera takes over automatically.
+     */
+    deactivate(id: string): void;
+    /**
+     * Force a specific virtual camera to take over immediately, regardless of
+     * priority, by temporarily setting its priority to a very high value and
+     * activating it. Call `restore()` to return to normal priority-based control.
+     */
+    override(id: string): void;
+    /**
+     * Remove any priority override set by `override()`, restoring the camera's
+     * original priority.
+     */
+    restore(id: string): void;
+    /**
+     * Returns the id of the virtual camera currently in control, or null if
+     * no virtual cameras are active.
+     */
+    getActiveId(): string | null;
+}
+/**
+ * Imperative controls for the virtual camera system. Lets you activate,
+ * deactivate, and force-override virtual cameras from game logic.
+ *
+ * Must be used inside `<Game>`.
+ *
+ * @example
+ * ```tsx
+ * function BossEncounter() {
+ *   const cam = useCameraBlend()
+ *
+ *   useEffect(() => {
+ *     cam.override('bossArena')
+ *     return () => cam.restore('bossArena')
+ *   }, [])
+ * }
+ * ```
+ */
+declare function useCameraBlend(): CameraBlendControls;
+
+interface CinematicStep {
+    /** ID of the virtual camera to activate for this step. */
+    cameraId: string;
+    /**
+     * How long to hold this camera in seconds before advancing.
+     * Use `Infinity` to hold until `stop()` is called or the sequence is unmounted.
+     */
+    holdFor: number;
+    /**
+     * Override the virtual camera's `blendDuration` for this specific step.
+     * When omitted, uses the camera's configured `blendDuration`.
+     */
+    blendDuration?: number;
+}
+interface CinematicSequenceControls {
+    /** Start the sequence from the beginning. */
+    play(): void;
+    /** Stop the sequence and deactivate the current camera step. */
+    stop(): void;
+    /** Whether the sequence is currently playing. */
+    readonly isPlaying: boolean;
+    /** Zero-based index of the current step, or -1 when stopped. */
+    readonly currentStep: number;
+}
+/**
+ * Plays an ordered sequence of virtual camera shots inside the engine loop.
+ * Each step activates a named `<VirtualCamera>` for `holdFor` seconds, then
+ * automatically advances to the next step. Respects engine pause.
+ *
+ * The virtual cameras referenced in the steps must be mounted in the scene
+ * tree via `<VirtualCamera>` before calling `play()`.
+ *
+ * @example
+ * ```tsx
+ * const { play, stop, isPlaying } = useCinematicSequence([
+ *   { cameraId: 'intro',     holdFor: 2,        blendDuration: 0 },
+ *   { cameraId: 'overview',  holdFor: 3,        blendDuration: 1 },
+ *   { cameraId: 'mainFollow', holdFor: Infinity, blendDuration: 0.5 },
+ * ], { onComplete: () => console.log('cutscene done') })
+ *
+ * // Trigger on mount:
+ * useEffect(() => { play() }, [])
+ * ```
+ */
+declare function useCinematicSequence(steps: CinematicStep[], opts?: {
+    onComplete?: () => void;
+}): CinematicSequenceControls;
+
 interface SnapshotControls {
     /**
      * Capture a full serialisable snapshot of all ECS entity/component data.
@@ -3100,6 +3333,143 @@ declare function deleteSavedScene(key: string): boolean;
  */
 declare function listSavedScenes(prefix?: string): string[];
 
+type HUDPosition = 'topLeft' | 'topCenter' | 'topRight' | 'centerLeft' | 'center' | 'centerRight' | 'bottomLeft' | 'bottomCenter' | 'bottomRight';
+interface HUDProps {
+    /**
+     * Whether the HUD fades out during scene transitions. Default true. When a
+     * `SceneTransitionOverlay` is active or `usePause` is paused, the HUD will
+     * dim to `dimmedOpacity` to get out of the way.
+     */
+    dimDuringTransitions?: boolean;
+    /** Opacity when dimmed. Default 0.25. */
+    dimmedOpacity?: number;
+    /** Whether the HUD is currently visible. Default true. */
+    visible?: boolean;
+    /** Whether to apply CSS `env(safe-area-inset-*)` padding. Default true on touch. */
+    safeArea?: boolean;
+    /** Extra padding around all zones in CSS pixels. Default 12. */
+    padding?: number;
+    /** Additional style for the HUD root. */
+    style?: CSSProperties;
+    /** Additional CSS class. */
+    className?: string;
+    children?: ReactNode;
+}
+/**
+ * Heads-up-display root. Positions a full-screen overlay over the game canvas
+ * and provides layout zones via {@link HUDZone}. Integrates automatically with
+ * CubeForge primitives:
+ *
+ * - Fades out during scene transitions (via `dimDuringTransitions`)
+ * - Respects `prefers-reduced-motion` for fade timing
+ * - Honors mobile safe-area insets when `safeArea` is on
+ *
+ * @example
+ * ```tsx
+ * <Stage>
+ *   <HUD>
+ *     <HUDZone position="topLeft">
+ *       <HUDBar value={hp} max={100} label="HP" color="#ef5350" />
+ *     </HUDZone>
+ *     <HUDZone position="topRight">
+ *       <span>Score: {score}</span>
+ *     </HUDZone>
+ *     <HUDZone position="bottomCenter">
+ *       <button onClick={onJump}>Jump</button>
+ *     </HUDZone>
+ *   </HUD>
+ * </Stage>
+ * ```
+ */
+declare function HUD({ dimDuringTransitions, dimmedOpacity, visible, safeArea, padding, style, className, children, }: HUDProps): react_jsx_runtime.JSX.Element;
+interface HUDZoneProps {
+    /** Where to anchor this zone. Default 'topLeft'. */
+    position?: HUDPosition;
+    /** Direction children lay out. Default 'row' for top/bottom, 'column' for left/right/center. */
+    direction?: 'row' | 'column';
+    /** Gap between children in CSS pixels. Default 8. */
+    gap?: number;
+    /** Allow pointer events on zone contents (buttons, sliders). Default true for this zone. */
+    interactive?: boolean;
+    /** Override style for the zone. */
+    style?: CSSProperties;
+    /** Additional CSS class. */
+    className?: string;
+    children?: ReactNode;
+}
+/**
+ * Positioned content zone inside a {@link HUD}. Nine anchors available
+ * (topLeft, topCenter, topRight, centerLeft, center, centerRight, bottomLeft,
+ * bottomCenter, bottomRight). Honors the parent HUD's padding and safe-area.
+ */
+declare function HUDZone({ position, direction, gap, interactive, style, className, children, }: HUDZoneProps): react_jsx_runtime.JSX.Element;
+interface HUDBarProps {
+    /** Current value. */
+    value: number;
+    /** Maximum value. */
+    max: number;
+    /** Optional label shown on top of the bar. */
+    label?: string;
+    /** Bar color. Default '#4fc3f7'. */
+    color?: string;
+    /** Track (empty) color. Default 'rgba(255,255,255,0.08)'. */
+    trackColor?: string;
+    /** Bar width in CSS pixels. Default 180. */
+    width?: number;
+    /** Bar height in CSS pixels. Default 14. */
+    height?: number;
+    /** Show numeric value as "value / max". Default true. */
+    showValue?: boolean;
+    /** Reverse direction: fills right→left. Default false. */
+    rtl?: boolean;
+    /** Round the bar corners. Default true. */
+    rounded?: boolean;
+    /** Smooth transition when value changes. Default true. */
+    animated?: boolean;
+    /** Additional style. */
+    style?: CSSProperties;
+}
+/**
+ * A simple value bar for HP, stamina, XP, progress, etc. Meant to be dropped
+ * inside a {@link HUDZone} without any extra styling. Animates smoothly by
+ * default; respects `prefers-reduced-motion` transparently via CSS.
+ *
+ * @example
+ * ```tsx
+ * <HUDZone position="topLeft">
+ *   <HUDBar value={hp} max={100} label="HP" color="#ef5350" />
+ *   <HUDBar value={mana} max={50} label="MP" color="#4fc3f7" />
+ * </HUDZone>
+ * ```
+ */
+declare function HUDBar({ value, max, label, color, trackColor, width, height, showValue, rtl, rounded, animated, style, }: HUDBarProps): react_jsx_runtime.JSX.Element;
+interface HUDCounterProps {
+    /** Numeric value to display. */
+    value: number;
+    /** Optional icon or emoji shown before the value. */
+    icon?: ReactNode;
+    /** Optional label shown after the value. */
+    label?: string;
+    /** Flash briefly when the value changes. Default true. */
+    pulse?: boolean;
+    /** Value color. Default '#fff'. */
+    color?: string;
+    /** Font size in CSS pixels. Default 18. */
+    fontSize?: number;
+    style?: CSSProperties;
+}
+/**
+ * A numeric counter widget for score, coins, ammo, etc.
+ *
+ * @example
+ * ```tsx
+ * <HUDZone position="topRight">
+ *   <HUDCounter icon="🪙" value={coins} />
+ * </HUDZone>
+ * ```
+ */
+declare function HUDCounter({ value, icon, label, pulse, color, fontSize, style, }: HUDCounterProps): react_jsx_runtime.JSX.Element;
+
 declare function playClip(world: ECSWorld, entityId: EntityId, clipName: string): void;
 declare function setAnimationState(world: ECSWorld, entityId: EntityId, stateName: string): void;
 declare function setAnimatorParam(world: ECSWorld, entityId: EntityId, name: string, value: AnimatorParamValue): void;
@@ -3206,4 +3576,4 @@ declare function useRemotePlayer(config: {
     opts?: RemotePlayerOptions;
 }): RemotePlayerControls;
 
-export { A11yNode, type A11yNodeProps, type AccessibilityControls, AnimatedSprite, type AnimatedSpriteProps, Animation, type AnimationSet, Animator, AssetLoader, type BoundInputMap, BoxCollider, Camera2D, type CameraControls, type CameraLookaheadOptions, CameraZone, CapsuleCollider, Checkpoint, Circle, CircleCollider, type ComboDetectorResult, CompoundCollider, ConvexCollider, type CoordinateHelpers, type CoroutineControls, type CoroutineFactory, type CoroutineYield, type DraggableControls, type DraggableOptions, type DroppableControls, type DroppableOptions, EditableText, type EditableTextProps, Entity, type ExportOptions, FocusRing, type FocusRingProps, type FocusableOptions, Game, type GameControls, type GamepadState, type GestureHandlers, type GestureOptions, Gradient, type GridCell, type GridControls, type GridOptions, type HMRControls, HalfSpaceCollider, HeightFieldCollider, type HistoryControls, type HistoryOptions, type HoverableControls, type HoverableOptions, type InputContextControls, Joint, type KeyboardFocusControls, Line, Mask, MovingPlatform, type NetworkSyncOptions, NineSlice, ParallaxLayer, ParticleEmitter, type ParticlePreset, type PauseControls, type PinchEvent, Polygon, type PreloadState, type ProfilerData, type RemotePlayerControls, type RemotePlayerOptions, RigidBody, type SceneManagerControls, type SceneSaveOptions, type SceneTransitionControls, SceneTransitionOverlay, ScreenFlash, type ScreenFlashHandle, Script, SegmentCollider, type SelectOptions, Selection, type SelectionControls, type SelectionProps, type SnapControls, type SnapOptions, type SnapResult, type SnapshotControls, Sprite, type SpriteAtlas, SquashStretch, type SquashStretchControls, Stage, type SwipeEvent, Text, type TiledLayer, type TiledObject, Tilemap, type TimerControls, type TouchControls, Trail, Transform, TransformHandles, type TransformHandlesProps, type TransitionEffect, TriMeshCollider, TriangleCollider, type TurnSystemControls, type TurnSystemOptions, VectorPath, type VectorPathProps, type VirtualInputState, VirtualJoystick, type VirtualJoystickProps, type Waypoint, World, createAtlas, defineAnimations, definePrefab, deleteSavedScene, downloadCanvas, exportToBlob, exportToDataURL, listSavedScenes, loadScene, loadSceneFromLocalStorage, playClip, saveScene, saveSceneToLocalStorage, setAnimationState, setAnimatorParam, useAccessibility, useAudioListener, useCamera, useCameraLookahead, useComboDetector, useCoordinates, useCoroutine, useDestroyEntity, useDraggable, useDroppable, useEntity, useEvent, useEvents, useFocusable, useGame, useGamepad, useGamepadHaptics, useGestures, useGrid, useHMR, useHistory, useHitstop, useHoverable, useInput, useInputBuffer, useInputContext, useInputMap, useInputRecorder, useKeyboardFocus, useLocalMultiplayer, useNetworkSync, useParent, usePause, usePlayerInput, usePostProcess, usePreload, useProfiler, useRemotePlayer, useSceneManager, useSceneTransition, useSelection, useSnap, useSnapshot, useSquashStretch, useTimer, useTouch, useTurnSystem, useVirtualInput, useWebGLPostProcess, useWorldQuery, wait, waitFrames, waitUntil };
+export { A11yNode, type A11yNodeProps, type AccessibilityControls, AnimatedSprite, type AnimatedSpriteProps, Animation, type AnimationSet, Animator, AssetLoader, type BoundInputMap, BoxCollider, Camera2D, type CameraBlendControls, type CameraControls, type CameraLookaheadOptions, CameraZone, CapsuleCollider, Checkpoint, type CinematicSequenceControls, type CinematicStep, Circle, CircleCollider, type ComboDetectorResult, CompoundCollider, ConvexCollider, type CoordinateHelpers, type CoroutineControls, type CoroutineFactory, type CoroutineYield, type DraggableControls, type DraggableOptions, type DroppableControls, type DroppableOptions, EditableText, type EditableTextProps, Entity, type ExportOptions, FocusRing, type FocusRingProps, type FocusableOptions, Game, type GameControls, type GamepadState, type GestureHandlers, type GestureOptions, Gradient, type GridCell, type GridControls, type GridOptions, type HMRControls, HUD, HUDBar, type HUDBarProps, HUDCounter, type HUDCounterProps, type HUDPosition, type HUDProps, HUDZone, type HUDZoneProps, HalfSpaceCollider, HeightFieldCollider, type HistoryControls, type HistoryOptions, type HoverableControls, type HoverableOptions, type InputContextControls, Joint, type KeyboardFocusControls, Line, Mask, MovingPlatform, type NetworkSyncOptions, NineSlice, PARTICLE_PRESETS, ParallaxLayer, ParticleEmitter, type ParticleEmitterConfig, type ParticlePreset, type PauseControls, type PinchEvent, Polygon, type PreloadState, type ProfilerData, type RemotePlayerControls, type RemotePlayerOptions, RigidBody, type SceneManagerControls, type SceneSaveOptions, type SceneTransitionControls, SceneTransitionOverlay, ScreenFlash, type ScreenFlashHandle, Script, SegmentCollider, type SelectOptions, Selection, type SelectionControls, type SelectionProps, type SnapControls, type SnapOptions, type SnapResult, type SnapshotControls, Sprite, type SpriteAtlas, SquashStretch, type SquashStretchControls, Stage, type SwipeEvent, Text, type TiledLayer, type TiledObject, Tilemap, type TimerControls, type TouchControls, Trail, Transform, TransformHandles, type TransformHandlesProps, type TransitionEffect, TriMeshCollider, TriangleCollider, type TurnSystemControls, type TurnSystemOptions, VectorPath, type VectorPathProps, VirtualCamera, type VirtualCameraConfig, type VirtualCameraProps, type VirtualInputState, VirtualJoystick, type VirtualJoystickProps, type Waypoint, World, createAtlas, defineAnimations, definePrefab, deleteSavedScene, downloadCanvas, exportToBlob, exportToDataURL, listSavedScenes, loadScene, loadSceneFromLocalStorage, playClip, saveScene, saveSceneToLocalStorage, setAnimationState, setAnimatorParam, useAccessibility, useAudioListener, useCamera, useCameraBlend, useCameraLookahead, useCinematicSequence, useComboDetector, useCoordinates, useCoroutine, useDestroyEntity, useDraggable, useDroppable, useEntity, useEvent, useEvents, useFocusable, useGame, useGamepad, useGamepadHaptics, useGestures, useGrid, useHMR, useHistory, useHitstop, useHoverable, useInput, useInputBuffer, useInputContext, useInputMap, useInputRecorder, useKeyboardFocus, useLocalMultiplayer, useNetworkSync, useParent, usePause, usePlayerInput, usePostProcess, usePreload, useProfiler, useRemotePlayer, useSceneManager, useSceneTransition, useSelection, useSnap, useSnapshot, useSquashStretch, useTimer, useTouch, useTurnSystem, useVirtualInput, useWebGLPostProcess, useWorldQuery, wait, waitFrames, waitUntil };