@holoscript/engine 6.0.3 → 6.0.4

package/dist/index-s9yOFU37.d.cts

@@ -0,0 +1,604 @@
+/**
+ * CameraConstraints.ts
+ *
+ * Camera constraints: bounds clamping, dead zones,
+ * soft limits, follow smoothing, and look-ahead.
+ *
+ * @module camera
+ */
+interface Bounds {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+}
+interface DeadZone {
+    width: number;
+    height: number;
+}
+interface SoftLimit {
+    distance: number;
+    stiffness: number;
+}
+declare class CameraConstraints {
+    private bounds;
+    private deadZone;
+    private softLimit;
+    private smoothing;
+    private lookAheadDistance;
+    private currentX;
+    private currentY;
+    setBounds(bounds: Bounds): void;
+    setDeadZone(dz: DeadZone): void;
+    setSoftLimit(sl: SoftLimit): void;
+    setSmoothing(factor: number): void;
+    setLookAhead(distance: number): void;
+    follow(targetX: number, targetY: number, velocityX?: number, velocityY?: number): {
+        x: number;
+        y: number;
+    };
+    private applySoftLimit;
+    getPosition(): {
+        x: number;
+        y: number;
+    };
+    setPosition(x: number, y: number): void;
+}
+
+/**
+ * CameraController.ts
+ *
+ * Camera modes: follow, orbit, free-look, top-down.
+ * Includes smoothing, dead zones, zoom, and bounds clamping.
+ *
+ * @module camera
+ */
+type CameraMode = 'follow' | 'orbit' | 'free' | 'topDown' | 'fixed';
+interface CameraState {
+    position: [number, number, number];
+    rotation: {
+        pitch: number;
+        yaw: number;
+        roll: number;
+    };
+    zoom: number;
+    fov: number;
+}
+interface CameraConfig {
+    mode: CameraMode;
+    smoothing: number;
+    followOffset: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    orbitDistance: number;
+    orbitMinDistance: number;
+    orbitMaxDistance: number;
+    orbitSpeed: number;
+    zoomSpeed: number;
+    minZoom: number;
+    maxZoom: number;
+    deadZone: {
+        x: number;
+        y: number;
+    };
+    bounds: {
+        min: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        max: {
+            x: number;
+            y: number;
+            z: number;
+        };
+    } | null;
+    fov: number;
+    freeSpeed: number;
+}
+/**
+ * Camera controller for managing various camera behaviors in 3D space.
+ *
+ * Supports multiple camera modes:
+ * - **follow**: Camera smoothly follows a target with configurable offset and dead zone
+ * - **orbit**: Camera orbits around a target point at configurable distance and speed
+ * - **free**: Camera movement controlled externally via moveCamera() calls
+ * - **topDown**: Camera maintains a top-down view of the target with smooth tracking
+ * - **fixed**: Camera remains stationary at its current position
+ *
+ * The controller handles smooth interpolation, zoom controls, boundary clamping,
+ * and provides a unified interface for camera state management across different modes.
+ *
+ * @example
+ * ```typescript
+ * const camera = new CameraController({
+ *   mode: 'orbit',
+ *   orbitDistance: 15,
+ *   smoothing: 0.1
+ * });
+ *
+ * camera.setTarget(5, 0, 5);
+ * camera.rotateOrbit(0.1, 0);
+ * camera.update(deltaTime);
+ *
+ * const state = camera.getState();
+ * console.log(state.position); // Current camera position
+ * ```
+ */
+declare class CameraController {
+    private config;
+    private state;
+    private target;
+    private orbitAngle;
+    private orbitPitch;
+    /**
+     * Creates a new camera controller with optional configuration.
+     *
+     * @param config - Optional camera configuration overrides. Merged with defaults.
+     * @example
+     * ```typescript
+     * const camera = new CameraController({
+     *   mode: 'follow',
+     *   smoothing: 0.2,
+     *   followOffset: { x: 0, y: 3, z: -8 }
+     * });
+     * ```
+     */
+    constructor(config?: Partial<CameraConfig>);
+    /**
+     * Updates camera position and rotation based on current mode and delta time.
+     *
+     * Call this every frame to animate camera movement. Different modes handle
+     * updates differently:
+     * - **follow**: Smoothly interpolates toward target + offset
+     * - **orbit**: Updates position based on orbit angle and pitch
+     * - **topDown**: Maintains overhead view with smooth target tracking
+     * - **free/fixed**: No automatic movement (controlled externally)
+     *
+     * @param dt - Delta time in seconds since last update
+     * @example
+     * ```typescript
+     * // In game loop
+     * const deltaTime = (now - lastTime) / 1000;
+     * camera.update(deltaTime);
+     * ```
+     */
+    update(dt: number): void;
+    private updateFollow;
+    private updateOrbit;
+    private updateTopDown;
+    private clampToBounds;
+    /**
+     * Sets the target point that the camera should focus on or track.
+     *
+     * Used by 'follow', 'orbit', and 'topDown' modes. In 'follow' mode, camera
+     * maintains offset from this target. In 'orbit' mode, camera rotates around
+     * this point. In 'topDown' mode, camera looks down at this location.
+     *
+     * @param x - Target X coordinate in world space
+     * @param y - Target Y coordinate in world space
+     * @param z - Target Z coordinate in world space
+     * @example
+     * ```typescript
+     * // Track a moving player
+     * camera.setTarget(player.x, player.y, player.z);
+     * ```
+     */
+    setTarget(x: number, y: number, z: number): void;
+    /**
+     * Gets the current target position.
+     *
+     * @returns Copy of the current target coordinates
+     */
+    getTarget(): {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /**
+     * Rotates the camera in orbit mode by the specified angles.
+     *
+     * Only affects camera behavior when mode is set to 'orbit'. Angles are
+     * clamped to prevent the camera from flipping or going too extreme.
+     *
+     * @param deltaAngle - Horizontal rotation change (yaw) in radians
+     * @param deltaPitch - Vertical rotation change (pitch) in radians, clamped to [-1.4, 1.4]
+     * @example
+     * ```typescript
+     * // Rotate based on mouse movement
+     * camera.rotateOrbit(mouseX * 0.01, mouseY * 0.01);
+     * ```
+     */
+    rotateOrbit(deltaAngle: number, deltaPitch: number): void;
+    /**
+     * Adjusts camera zoom by the specified delta amount.
+     *
+     * Zoom affects distance in 'orbit' mode, height in 'topDown' mode, and FOV scaling.
+     * Value is clamped between configured minZoom and maxZoom limits.
+     *
+     * @param delta - Amount to change zoom by (positive = zoom in, negative = zoom out)
+     * @example
+     * ```typescript
+     * // Zoom in on mouse wheel
+     * camera.zoom(-wheelDelta * 0.1);
+     * ```
+     */
+    zoom(delta: number): void;
+    /**
+     * Directly moves camera position by specified amounts.
+     *
+     * Primarily used in 'free' camera mode for manual camera control.
+     * Movement is scaled by the configured freeSpeed multiplier.
+     *
+     * @param dx - Change in X position (world units)
+     * @param dy - Change in Y position (world units)
+     * @param dz - Change in Z position (world units)
+     * @example
+     * ```typescript
+     * // WASD movement in free camera mode
+     * if (wPressed) camera.moveCamera(0, 0, 1);
+     * if (sPressed) camera.moveCamera(0, 0, -1);
+     * ```
+     */
+    moveCamera(dx: number, dy: number, dz: number): void;
+    /**
+     * Changes the camera's behavior mode.
+     *
+     * @param mode - New camera mode ('follow' | 'orbit' | 'free' | 'topDown' | 'fixed')
+     * @example
+     * ```typescript
+     * camera.setMode('orbit'); // Switch to orbital camera
+     * ```
+     */
+    setMode(mode: CameraMode): void;
+    /**
+     * Gets the current camera mode.
+     *
+     * @returns Current camera mode
+     */
+    getMode(): CameraMode;
+    /**
+     * Gets a copy of the current camera state.
+     *
+     * Returns position, rotation, zoom, and FOV values. All objects are cloned
+     * to prevent external modification of internal state.
+     *
+     * @returns Current camera state with position, rotation, zoom, and FOV
+     * @example
+     * ```typescript
+     * const state = camera.getState();
+     * renderer.setCamera(state.position, state.rotation);
+     * renderer.setFOV(state.fov);
+     * ```
+     */
+    getState(): CameraState;
+    /**
+     * Directly sets the camera zoom level.
+     *
+     * Unlike zoom(), this sets an absolute value rather than a delta.
+     * Value is clamped to configured min/max zoom limits.
+     *
+     * @param z - New zoom level (clamped to minZoom/maxZoom)
+     * @example
+     * ```typescript
+     * camera.setZoom(1.0); // Reset to default zoom
+     * ```
+     */
+    setZoom(z: number): void;
+    /**
+     * Sets the camera's field of view.
+     *
+     * @param fov - New field of view in degrees
+     * @example
+     * ```typescript
+     * camera.setFOV(90); // Wide angle
+     * camera.setFOV(30); // Telephoto
+     * ```
+     */
+    setFOV(fov: number): void;
+    /**
+     * Adjusts camera smoothing factor for interpolated movement modes.
+     *
+     * Affects 'follow' and 'topDown' modes. Higher values = more responsive,
+     * lower values = smoother but more delayed movement.
+     *
+     * @param s - Smoothing factor between 0.0 (no movement) and 1.0 (instant)
+     * @example
+     * ```typescript
+     * camera.setSmoothing(0.1); // Very smooth
+     * camera.setSmoothing(0.8); // Very responsive
+     * ```
+     */
+    setSmoothing(s: number): void;
+    private lerp;
+}
+
+/**
+ * CameraEffects.ts
+ *
+ * Post-camera effects: screen shake, zoom pulses, flash,
+ * letterbox, split-screen, and vignette overlays.
+ *
+ * @module camera
+ */
+type EffectType = 'shake' | 'zoom' | 'flash' | 'letterbox' | 'vignette' | 'fade';
+interface ActiveEffect {
+    id: string;
+    type: EffectType;
+    duration: number;
+    elapsed: number;
+    intensity: number;
+    params: Record<string, unknown>;
+    active: boolean;
+}
+interface ShakeParams {
+    frequency: number;
+    decay: number;
+}
+interface ZoomParams {
+    targetZoom: number;
+    easeBack: boolean;
+}
+interface FlashParams {
+    color: {
+        r: number;
+        g: number;
+        b: number;
+    };
+}
+interface LetterboxParams {
+    ratio: number;
+}
+interface FadeParams {
+    fadeIn: boolean;
+    color: {
+        r: number;
+        g: number;
+        b: number;
+    };
+}
+declare class CameraEffects {
+    private effects;
+    private shakeOffset;
+    private zoomMultiplier;
+    private flashAlpha;
+    private flashColor;
+    private letterboxAmount;
+    private vignetteIntensity;
+    private fadeAlpha;
+    shake(duration: number, intensity?: number, frequency?: number, decay?: number): string;
+    zoomPulse(duration: number, targetZoom?: number, easeBack?: boolean): string;
+    flash(duration?: number, color?: {
+        r: number;
+        g: number;
+        b: number;
+    }, intensity?: number): string;
+    letterbox(duration: number, ratio?: number): string;
+    vignette(duration: number, intensity?: number): string;
+    fade(duration: number, fadeIn?: boolean, color?: {
+        r: number;
+        g: number;
+        b: number;
+    }): string;
+    private addEffect;
+    update(dt: number): void;
+    getShakeOffset(): {
+        x: number;
+        y: number;
+    };
+    getZoomMultiplier(): number;
+    getFlashAlpha(): number;
+    getFlashColor(): {
+        r: number;
+        g: number;
+        b: number;
+    };
+    getLetterboxAmount(): number;
+    getVignetteIntensity(): number;
+    getFadeAlpha(): number;
+    getActiveEffectCount(): number;
+    cancelEffect(id: string): boolean;
+    cancelAll(): void;
+}
+
+/**
+ * CameraPath.ts
+ *
+ * Spline-based camera paths: Catmull-Rom interpolation,
+ * speed control, look-at targets, and looping.
+ *
+ * @module camera
+ */
+interface PathPoint {
+    x: number;
+    y: number;
+    z: number;
+    lookAtX?: number;
+    lookAtY?: number;
+    lookAtZ?: number;
+    speedMultiplier?: number;
+}
+declare class CameraPath {
+    private points;
+    private progress;
+    private speed;
+    private loop;
+    private playing;
+    setPoints(points: PathPoint[]): void;
+    addPoint(point: PathPoint): void;
+    clearPoints(): void;
+    setSpeed(speed: number): void;
+    setLoop(loop: boolean): void;
+    play(): void;
+    pause(): void;
+    resume(): void;
+    stop(): void;
+    update(dt: number): {
+        position: [number, number, number];
+        lookAt: {
+            x: number;
+            y: number;
+            z: number;
+        } | null;
+    } | null;
+    evaluate(t: number): {
+        position: [number, number, number];
+        lookAt: {
+            x: number;
+            y: number;
+            z: number;
+        } | null;
+    };
+    private catmullRom;
+    getProgress(): number;
+    isPlaying(): boolean;
+    getPointCount(): number;
+}
+
+/**
+ * CameraShake.ts
+ *
+ * Trauma-based camera shake: Perlin noise sampling,
+ * configurable decay, multi-layer shake, and intensity control.
+ *
+ * @module camera
+ */
+interface ShakeLayer {
+    id: string;
+    trauma: number;
+    decay: number;
+    frequency: number;
+    amplitude: number;
+    rotationAmount: number;
+}
+interface ShakeOutput {
+    offsetX: number;
+    offsetY: number;
+    rotation: number;
+}
+declare class CameraShake {
+    private layers;
+    private time;
+    addLayer(id: string, config?: Partial<ShakeLayer>): void;
+    removeLayer(id: string): void;
+    addTrauma(layerId: string, amount: number): void;
+    setTrauma(layerId: string, amount: number): void;
+    update(dt: number): ShakeOutput;
+    private noise;
+    getTrauma(layerId: string): number;
+    isShaking(): boolean;
+}
+
+/**
+ * CinematicTrack.ts
+ *
+ * Keyframe-based cinematic sequencer: position/rotation/fov
+ * keyframes, easing curves, playback control, and event cues.
+ *
+ * @module camera
+ */
+type EasingType = 'linear' | 'easeIn' | 'easeOut' | 'easeInOut' | 'smoothStep';
+interface CinematicKeyframe {
+    time: number;
+    position?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotation?: {
+        pitch: number;
+        yaw: number;
+        roll: number;
+    };
+    fov?: number;
+    zoom?: number;
+    easing: EasingType;
+}
+interface CinematicCue {
+    time: number;
+    event: string;
+    data: Record<string, unknown>;
+    fired: boolean;
+}
+interface CinematicState {
+    position: [number, number, number];
+    rotation: {
+        pitch: number;
+        yaw: number;
+        roll: number;
+    };
+    fov: number;
+    zoom: number;
+}
+declare class CinematicTrack {
+    private keyframes;
+    private cues;
+    private currentTime;
+    private duration;
+    private playing;
+    private looping;
+    private speed;
+    private cueListeners;
+    addKeyframe(keyframe: CinematicKeyframe): void;
+    addCue(time: number, event: string, data?: Record<string, unknown>): void;
+    removeKeyframesAt(time: number): number;
+    play(): void;
+    pause(): void;
+    stop(): void;
+    seek(time: number): void;
+    setSpeed(speed: number): void;
+    setLooping(loop: boolean): void;
+    isPlaying(): boolean;
+    getCurrentTime(): number;
+    getDuration(): number;
+    getProgress(): number;
+    update(dt: number): CinematicState | null;
+    evaluate(time: number): CinematicState;
+    private applyEasing;
+    onCue(listener: (event: string, data: Record<string, unknown>) => void): void;
+    private resetCues;
+    private recalcDuration;
+    getKeyframeCount(): number;
+    getCueCount(): number;
+    clear(): void;
+}
+
+type index_ActiveEffect = ActiveEffect;
+type index_Bounds = Bounds;
+type index_CameraConfig = CameraConfig;
+type index_CameraConstraints = CameraConstraints;
+declare const index_CameraConstraints: typeof CameraConstraints;
+type index_CameraController = CameraController;
+declare const index_CameraController: typeof CameraController;
+type index_CameraEffects = CameraEffects;
+declare const index_CameraEffects: typeof CameraEffects;
+type index_CameraMode = CameraMode;
+type index_CameraPath = CameraPath;
+declare const index_CameraPath: typeof CameraPath;
+type index_CameraShake = CameraShake;
+declare const index_CameraShake: typeof CameraShake;
+type index_CameraState = CameraState;
+type index_CinematicCue = CinematicCue;
+type index_CinematicKeyframe = CinematicKeyframe;
+type index_CinematicState = CinematicState;
+type index_CinematicTrack = CinematicTrack;
+declare const index_CinematicTrack: typeof CinematicTrack;
+type index_DeadZone = DeadZone;
+type index_EasingType = EasingType;
+type index_EffectType = EffectType;
+type index_FadeParams = FadeParams;
+type index_FlashParams = FlashParams;
+type index_LetterboxParams = LetterboxParams;
+type index_PathPoint = PathPoint;
+type index_ShakeLayer = ShakeLayer;
+type index_ShakeOutput = ShakeOutput;
+type index_ShakeParams = ShakeParams;
+type index_SoftLimit = SoftLimit;
+type index_ZoomParams = ZoomParams;
+declare namespace index {
+  export { type index_ActiveEffect as ActiveEffect, type index_Bounds as Bounds, type index_CameraConfig as CameraConfig, index_CameraConstraints as CameraConstraints, index_CameraController as CameraController, index_CameraEffects as CameraEffects, type index_CameraMode as CameraMode, index_CameraPath as CameraPath, index_CameraShake as CameraShake, type index_CameraState as CameraState, type index_CinematicCue as CinematicCue, type index_CinematicKeyframe as CinematicKeyframe, type index_CinematicState as CinematicState, index_CinematicTrack as CinematicTrack, type index_DeadZone as DeadZone, type index_EasingType as EasingType, type index_EffectType as EffectType, type index_FadeParams as FadeParams, type index_FlashParams as FlashParams, type index_LetterboxParams as LetterboxParams, type index_PathPoint as PathPoint, type index_ShakeLayer as ShakeLayer, type index_ShakeOutput as ShakeOutput, type index_ShakeParams as ShakeParams, type index_SoftLimit as SoftLimit, type index_ZoomParams as ZoomParams };
+}
+
+export { type ActiveEffect as A, type Bounds as B, type CameraConfig as C, type DeadZone as D, type EasingType as E, type FadeParams as F, type LetterboxParams as L, type PathPoint as P, type ShakeLayer as S, type ZoomParams as Z, CameraConstraints as a, CameraController as b, CameraEffects as c, type CameraMode as d, CameraPath as e, CameraShake as f, type CameraState as g, type CinematicCue as h, index as i, type CinematicKeyframe as j, type CinematicState as k, CinematicTrack as l, type EffectType as m, type FlashParams as n, type ShakeOutput as o, type ShakeParams as p, type SoftLimit as q };