cubeforge 0.6.0 → 0.6.2

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export { AxisLock, BoxColliderComponent, COLLISION_DYNAMIC_DYNAMIC, COLLISION_DY
 import { InputManager, ActionBindings, InputContextName, PlayerInput, InputRecorderControls, TouchPoint, InputBufferOptions, InputBuffer, ComboDefinition } from '@cubeforge/input';
 export { ActionBindings, AxisBinding, BufferedAction, ComboDefinition, ComboDetector, ComboDetectorOptions, InputBuffer, InputBufferOptions, InputContextName, InputManager, InputMap, InputRecorderControls, InputRecording, InputRecording as InputRecordingData, PlayerInput, TouchPoint, createInputMap, createInputRecorder, createPlayerInput, globalInputContext } from '@cubeforge/input';
 import { AnimationClip } from '@cubeforge/gameplay';
-export { AISteering, AnimationClip, AnimationControllerResult, BindingControls, CharacterControls, CutsceneControls, CutsceneStep, DialogueBox, DialogueBoxProps, DialogueBoxStyle, DialogueControls, DialogueLine, DialogueScript, ForceControls, GameState as GameStateDefinition, GameStateMachineResult, HealthControls, HealthOptions, IDBSaveControls, IDBSaveOptions, KinematicBodyControls, LevelTransitionControls, ObjectPool, PathfindingControls, PlatformerControllerOptions, RestartControls, SaveControls, SaveOptions, TopDownMovementOptions, TransitionOptions, TransitionType, TweenControls, useAISteering, useAnimationController, useCharacterController, useCutscene, useDamageZone, useDialogue, useDropThrough, useForces, useGameStateMachine, useGameStore, useHealth, useIDBSave, useKinematicBody, useLevelTransition, useObjectPool, usePathfinding, usePersistedBindings, usePlatformerController, useRestart, useSave, useTopDownMovement, useTween } from '@cubeforge/gameplay';
+export { AISteering, AnimationClip, AnimationControllerResult, BindingControls, CharacterControls, CutsceneControls, CutsceneStep, DialogueBox, DialogueBoxProps, DialogueBoxStyle, DialogueControls, DialogueLine, DialogueScript, ForceControls, GameState as GameStateDefinition, GameStateMachineResult, HealthControls, HealthOptions, IDBSaveControls, IDBSaveOptions, KinematicBodyControls, LevelTransitionControls, ObjectPool, PathfindingControls, PlatformerControllerOptions, RestartControls, SaveControls, SaveOptions, SaveSlot, SaveSlotMeta, SaveSlotsControls, SaveSlotsOptions, TopDownMovementOptions, TransitionOptions, TransitionType, TweenControls, useAISteering, useAnimationController, useCharacterController, useCutscene, useDamageZone, useDialogue, useDropThrough, useForces, useGameStateMachine, useGameStore, useHealth, useIDBSave, useKinematicBody, useLevelTransition, useObjectPool, usePathfinding, usePersistedBindings, usePlatformerController, useRestart, useSave, useSaveSlots, useTopDownMovement, useTween } from '@cubeforge/gameplay';
 import { EngineState } from '@cubeforge/context';
 export { ContactData, EngineState, useCircleEnter, useCircleExit, useCircleStay, useCollidingWith, useCollisionEnter, useCollisionExit, useCollisionStay, useTriggerEnter, useTriggerExit, useTriggerStay } from '@cubeforge/context';
 export { AudioAnalyserControls, AudioAnalyserOptions, AudioGroup, AudioSchedulerControls, AudioSchedulerOptions, BarHandler, BeatHandler, CompressorEffectOptions, DelayEffectOptions, FilterEffectOptions, GroupEffectOptions, MusicControls, MusicOptions, PreloadAudioResult, ReverbEffectOptions, SoundControls, SoundOptions, SpatialSoundControls, SpatialSoundOptions, StreamedMusicControls, StreamedMusicOptions, clearGroupEffect, duck, getGroupVolume, getListenerPosition, getMasterVolume, loadAudioSettings, saveAudioSettings, setGroupEffect, setGroupMute, setGroupVolume, setGroupVolumeFaded, setListenerPosition, setMasterVolume, stopGroup, useAudioAnalyser, useAudioScheduler, useMusic, usePreloadAudio, useSound, useSpatialSound, useStreamedMusic } from '@cubeforge/audio';
@@ -917,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;
@@ -1317,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.
@@ -1820,6 +2012,56 @@ declare function useGamepadHaptics(playerIndex?: number): {
     isSupported(): boolean;
 };
 
+/**
+ * Touch/mobile haptic feedback via the Web Vibration API.
+ *
+ * Falls back silently on desktop browsers and iOS (Safari does not support
+ * the Vibration API as of 2025).
+ *
+ * @example
+ * ```tsx
+ * function Player() {
+ *   const haptics = useTouchHaptics()
+ *
+ *   useCollisionEnter(() => haptics.impact())
+ *   // Or with a pattern:
+ *   haptics.pattern([50, 30, 50])  // vibrate-pause-vibrate
+ * }
+ * ```
+ */
+declare function useTouchHaptics(): TouchHapticsControls;
+interface TouchHapticsControls {
+    /**
+     * Short impact pulse — good for collisions, button taps.
+     * @param duration Vibration duration in ms. Default 30.
+     */
+    impact(duration?: number): void;
+    /**
+     * Medium notification pulse — good for pickups, level-up, checkpoint.
+     * Produces two short pulses separated by a brief pause.
+     */
+    notification(): void;
+    /**
+     * Heavy feedback burst — explosions, deaths, critical hits.
+     * @param duration Vibration duration in ms. Default 80.
+     */
+    heavy(duration?: number): void;
+    /**
+     * Custom vibration pattern: alternating vibrate/pause durations in ms.
+     * @param pattern Array of durations: [vibrate, pause, vibrate, ...].
+     *                A single number vibrates for that duration.
+     */
+    pattern(pattern: number | number[]): void;
+    /**
+     * Stop any in-progress vibration immediately.
+     */
+    cancel(): void;
+    /**
+     * Whether the current browser supports the Vibration API.
+     */
+    isSupported(): boolean;
+}
+
 interface TimerControls {
     /** Start/restart the timer */
     start(): void;
@@ -3384,4 +3626,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, 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, 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, type TouchHapticsControls, 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, useTouchHaptics, useTurnSystem, useVirtualInput, useWebGLPostProcess, useWorldQuery, wait, waitFrames, waitUntil };