storysplat-viewer 0.1.0

package/dist/types/types/viewerOptions.d.ts

@@ -0,0 +1,245 @@
+import { UIType } from "./dataTypes";
+import { Waypoint } from "./navigationTypes";
+import { SceneLightConfig, ParticleSystemConfig, CustomMeshConfig } from "./sceneFeatures";
+/** Defines the available camera control modes. */
+export type CameraMode = 'explore' | 'walk' | 'tour' | 'hybrid';
+/** Defines the available XR modes. */
+export type XRMode = 'none' | 'ar' | 'vr';
+/** Placeholder for AR specific options. Define based on src/types/SceneTypes.ts if needed. */
+export interface AROptions {
+    enableHitTest?: boolean;
+    enablePlaneDetection?: boolean;
+    enableAnchors?: boolean;
+    enableBackgroundRemoval?: boolean;
+}
+/** Configuration for background audio. */
+export interface BackgroundAudioConfig {
+    /** Unique identifier for the background audio track. */
+    id?: string;
+    /** URL of the audio file. */
+    url: string;
+    /** Volume level (0.0 to 1.0). Defaults to 1. */
+    volume?: number;
+    /** Whether the audio should loop. Defaults to true. */
+    loop?: boolean;
+}
+/** Configuration options related to audio playback. */
+export interface AudioOptions {
+    /** Configuration for the background audio track. */
+    backgroundAudio?: BackgroundAudioConfig;
+    /** Show the mute/unmute button in the UI. Defaults to false. */
+    showMuteButton?: boolean;
+}
+/** Defines the UI configuration options. */
+export interface UIOptions {
+    /** Position of waypoint information display ('popup' or 'controls'). */
+    infoPosition?: 'popup' | 'controls';
+    /** Layout of scroll buttons ('inline' or 'below'). */
+    buttonPosition?: "inline" | "below";
+    /** Show a 'Start Experience' button before loading. */
+    showStartExperience?: boolean;
+    /** Enable Babylon.js debug layer (Ctrl+I). */
+    debugMode?: boolean;
+    /** Overall UI theme/layout. */
+    uiType?: UIType | string;
+    /** Hide the StorySplat watermark. */
+    hideWatermark?: boolean;
+    /** Custom text for the watermark. */
+    watermarkText?: string;
+    /** Custom link URL for the watermark. */
+    watermarkLink?: string;
+}
+/** Configuration options for the preloader UI element. */
+export interface PreloaderConfig {
+    /** URL for a custom image logo in the preloader. */
+    imageUrl?: string;
+    /** URL for a custom Lottie animation JSON in the preloader. */
+    lottieUrl?: string;
+    /** Override the default UI color specifically for the preloader elements (e.g., progress bar). Defaults to the main `uiColor` option if not set. */
+    uiColor?: string;
+    /** Set to false to completely disable the preloader UI. Defaults to true. */
+    enabled?: boolean;
+}
+/**
+ * Configuration options for the analytics tracking system.
+ */
+export interface ViewerAnalyticsOptions {
+    /** Enable or disable analytics tracking. Defaults to false. */
+    enabled?: boolean;
+    /**
+     * Callback function invoked for each tracked event.
+     * The consuming application should implement this to send data to their analytics backend.
+     * @param {string} eventName - The name of the event (e.g., 'waypoint_reached').
+     * @param {Record<string, any>} eventData - An object containing event details and metadata.
+     */
+    onTrackEvent?: (eventName: string, eventData: Record<string, any>) => void;
+    /** Optional identifier for the scene being viewed. */
+    sceneId?: string;
+    /** Optional name for the scene being viewed. */
+    sceneName?: string;
+    /** Optional identifier for the current user. */
+    userId?: string;
+    /** Optional name of the scene creator. */
+    creatorName?: string;
+}
+export interface ViewerOptions {
+    /** Configuration for the preloader UI. */
+    preloaderConfig?: PreloaderConfig;
+    /** Show the help button and panel. Defaults to false. */
+    showHelpButton?: boolean;
+    /** Show the "Start Experience" button overlay. Defaults to false. */
+    showStartExperience?: boolean;
+    /** Override the default background color of the scene. */
+    backgroundColor?: {
+        r: number;
+        g: number;
+        b: number;
+        a?: number;
+    };
+    /** The initial camera mode when the viewer loads. Defaults to 'explore'. */
+    defaultCameraMode?: CameraMode;
+    /** An array of camera modes the user is allowed to switch between. If undefined or empty, all modes defined in the data/defaults are potentially usable. */
+    allowedCameraModes?: CameraMode[];
+    /** Enable or disable camera controls entirely (overrides mode settings). Defaults to true. */
+    cameraControls?: boolean;
+    /** Enable keyboard controls (WASD/Arrows) for Explore/Walk modes. Defaults to true if cameraControls is true. */
+    enableKeyboardControls?: boolean;
+    /** Enable mouse/touch look controls for Explore/Walk modes. Defaults to true if cameraControls is true. */
+    enableMouseControls?: boolean;
+    /** Enable the mobile joystick UI for Explore/Walk modes. Defaults to false. */
+    enableMobileJoystick?: boolean;
+    /** Override default camera movement speed (units per second). */
+    cameraSpeed?: number;
+    /** Override default camera rotation inertia (0-1, higher means more smoothing). */
+    cameraInertia?: number;
+    /** Override default camera mouse rotation sensitivity. Higher is slower. */
+    cameraAngularSensibility?: number;
+    /** Override default camera touch rotation sensitivity. Higher is slower. */
+    cameraTouchAngularSensibility?: number;
+    /** Override default camera mouse wheel zoom speed percentage. Affects how much camera.radius changes per wheel event. */
+    cameraWheelDeltaPercentage?: number;
+    /** Override default camera minimum Z distance (near clipping plane). */
+    cameraMinZ?: number;
+    /** Override default camera maximum Z distance (far clipping plane). */
+    cameraMaxZ?: number;
+    /** Override the default gravity strength applied in 'walk' mode (negative value for downward gravity). */
+    gravity?: number;
+    /** Override the default camera collision ellipsoid dimensions {x, y, z}. */
+    cameraEllipsoid?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Enable collisions in 'explore' mode. Defaults to false. */
+    exploreCollisions?: boolean;
+    /** Enable collisions in 'walk' mode. Defaults to true. */
+    walkCollisions?: boolean;
+    /** Apply gravity in 'walk' mode. Defaults to true. */
+    walkApplyGravity?: boolean;
+    /** Array of mesh names to enable collision against in 'walk' mode (and optionally 'explore' if exploreCollisions is true). */
+    collisionMeshesData?: string[];
+    /** Speed factor for scroll-based navigation in 'hybrid' or 'tour' mode. (Currently handled by next/prev waypoint logic). */
+    scrollSpeed?: number;
+    /** Multiplier affecting how much the camera moves per scroll wheel event in tour/hybrid modes. Higher values mean faster scrolling. Defaults to 0.001. */
+    scrollSpeedFactor?: number;
+    /** Default duration (in milliseconds) for camera transitions between waypoints. Also used as a speed factor in the render loop (higher = faster interpolation). */
+    transitionSpeed?: number;
+    /** Enable or disable hotspot functionality. Defaults to true if hotspots exist in data. */
+    enableHotspots?: boolean;
+    /** Enable or disable waypoint navigation functionality. Defaults to true if waypoints exist in data. */
+    enableNavigation?: boolean;
+    /** Enable or disable particle systems. Defaults to true if particle systems exist in data. */
+    enableParticles?: boolean;
+    /** Custom class name to add to the viewer's container element. */
+    className?: string;
+    /** Force disable WebGPU and use WebGL2. Defaults to false. */
+    disableWebGPU?: boolean;
+    /** Primary UI color (e.g., for buttons, progress bar). Hex string like "#FF0000". */
+    uiColor?: string;
+    /** Determines the behavior of next/previous scroll buttons ('percentage' or 'waypoint'). */
+    scrollButtonMode?: "percentage" | "waypoint";
+    /** The amount to scroll when using 'percentage' mode (0-100). */
+    scrollAmount?: number;
+    /** Whether the waypoint tour should loop back to the start after reaching the end. */
+    loopMode?: boolean;
+    /** Enable automatic progression through waypoints. */
+    autoPlayEnabled?: boolean;
+    /** Speed factor for autoplay (1 is normal speed). */
+    autoPlaySpeed?: number;
+    /** Invert the camera's rotation controls (useful for some control schemes). */
+    invertCameraRotation?: boolean;
+    /** Height of the camera in 'walk' mode (in meters). */
+    playerHeight?: number;
+    /** UI specific configuration options. */
+    uiOptions?: UIOptions;
+    /** Configuration for WebXR (AR/VR) features. */
+    xr?: {
+        /** Enable WebXR functionality. Requires HTTPS. Defaults to false. */
+        enabled: boolean;
+        /** Default XR mode to attempt initialization ('AR' or 'VR'). */
+        mode: 'AR' | 'VR';
+        /** Specific options for AR mode. */
+        arOptions?: AROptions;
+        /** Show the default "Enter XR" button provided by Babylon.js. Defaults to true if enabled. */
+        showEnterXRButton?: boolean;
+    };
+    /** URL of the cube texture file (.env, .dds, or pre-filtered .babylon) for the scene skybox. */
+    activeSkyboxUrl?: string | null;
+    /** Array of light configurations to add to the scene. */
+    lights?: SceneLightConfig[];
+    /** Array of particle system configurations to create in the scene. */
+    particleSystems?: ParticleSystemConfig[];
+    /** Array of custom mesh configurations to load into the scene. */
+    customMeshes?: CustomMeshConfig[];
+    /** Array of waypoints defining the navigation path. */
+    waypoints?: Waypoint[];
+    /** Default navigation mode if waypoints exist ('tour', 'hybrid'). */
+    /** Speed factor for camera transitions between waypoints. */
+    /** Smoothing factor for camera movement during navigation (0-1). */
+    cameraDampening?: number;
+    /** Multiplier for scroll-based navigation speed. */
+    /** Behavior of next/previous buttons ('percentage' or 'waypoint'). */
+    /** Amount to scroll in 'percentage' mode (0-1). */
+    /** Whether the waypoint tour loops. */
+    /** Enable automatic playback of the tour. */
+    /** Speed factor for automatic playback. */
+    /** Show the navigation progress bar UI element. */
+    showProgressBar?: boolean;
+    /** Show the previous/next navigation button UI elements. */
+    showNavButtons?: boolean;
+    /** Show UI buttons for switching between all allowed camera modes. Defaults to true if multiple modes are allowed. */
+    showCameraModeToggle?: boolean;
+    /** Show UI buttons specifically for toggling between 'Explore' (Drone) and 'Walk' modes. Defaults to true if both are allowed. */
+    showWalkExploreToggle?: boolean;
+    onSceneReady?: (scene: import("@babylonjs/core/scene").Scene) => void;
+    /** Callback function triggered when a hotspot mesh is clicked or activated. */
+    onHotspotClicked?: (hotspotId: string | number, hotspotData: import("./hotspotTypes").Hotspot) => void;
+    /** Callback function triggered when the pointer enters a hotspot mesh (if hover interactions are enabled). */
+    onHotspotHover?: (hotspotId: string | number, hotspotData: import("./hotspotTypes").Hotspot) => void;
+    /** Callback function triggered when the pointer leaves a hotspot mesh (if hover interactions are enabled). */
+    onHotspotLeave?: (hotspotId: string | number, hotspotData: import("./hotspotTypes").Hotspot) => void;
+    onWaypointReached?: (waypointName: string, index: number) => void;
+    onCameraModeChanged?: (newMode: CameraMode) => void;
+    /** Configuration for audio features. */
+    audio?: AudioOptions;
+    /** @deprecated Use cameraAngularSensibility instead. */
+    cameraAngularSensibilityX?: number;
+    /** @deprecated Use cameraAngularSensibility instead. */
+    cameraAngularSensibilityY?: number;
+    /** @deprecated ArcRotateCamera specific, not used by UniversalCamera. */
+    cameraLowerRadiusLimit?: number | null;
+    /** @deprecated ArcRotateCamera specific, not used by UniversalCamera. */
+    cameraUpperRadiusLimit?: number | null;
+    /** @deprecated ArcRotateCamera specific, not used by UniversalCamera. */
+    cameraLowerBetaLimit?: number;
+    /** @deprecated ArcRotateCamera specific, not used by UniversalCamera. */
+    cameraUpperBetaLimit?: number;
+    /** @deprecated ArcRotateCamera specific, not used by UniversalCamera. */
+    cameraPanningSensibility?: number;
+    /** @deprecated Use cameraWheelDeltaPercentage instead. */
+    cameraWheelPrecision?: number;
+    /** @deprecated Use cameraTouchAngularSensibility instead. */
+    cameraTouchMoveSensibility?: number;
+    /** Configuration for the analytics tracking system. */
+    analytics?: ViewerAnalyticsOptions;
+}

package/dist/types/types.d.ts

@@ -0,0 +1,106 @@
+export interface Vector3 {
+    x: number;
+    y: number;
+    z: number;
+}
+export interface Quaternion {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+}
+export interface WaypointInteraction {
+    id: string;
+    type: string;
+    data: any;
+}
+export interface Waypoint {
+    x: number;
+    y: number;
+    z: number;
+    rotation: {
+        x: number;
+        y: number;
+        z: number;
+        w: number;
+    };
+    name?: string;
+    interactions?: WaypointInteraction[];
+    triggerDistance?: number;
+}
+export type NavigationMode = 'tour' | 'hybrid' | 'explore' | 'walk';
+export type CameraMode = 'explore' | 'walk' | 'tour' | 'hybrid';
+export interface CameraState {
+    position: Vector3;
+    rotation: Quaternion;
+}
+export interface ViewerOptions {
+    splatUrl?: string;
+    containerId?: string;
+    initialCameraPosition?: Vector3;
+    initialCameraRotation?: Quaternion;
+    backgroundColor?: {
+        r: number;
+        g: number;
+        b: number;
+        a?: number;
+    };
+    fov?: number;
+    minClipPlane?: number;
+    maxClipPlane?: number;
+    invertCameraRotation?: boolean;
+    invertXScale?: boolean;
+    invertYScale?: boolean;
+    splatScale?: number;
+    showStartExperience?: boolean;
+    showHelpButton?: boolean;
+    enableMobileJoystick?: boolean;
+    uiColor?: string;
+    waypoints?: Waypoint[];
+    allowedCameraModes?: CameraMode[];
+    enableNavigation?: boolean;
+    defaultMode?: NavigationMode;
+    allowedModes?: NavigationMode[];
+    transitionSpeed?: number;
+    cameraDampening?: number;
+    scrollSpeed?: number;
+    scrollButtonMode?: 'percentage' | 'waypoint';
+    scrollAmount?: number;
+    loopMode?: boolean;
+    autoPlayEnabled?: boolean;
+    autoPlaySpeed?: number;
+    showProgressBar?: boolean;
+    showNavButtons?: boolean;
+    onWaypointReached?: (waypointName: string, index: number) => void;
+    uiOptions?: UIOptions;
+}
+/** Defines the UI configuration options. */
+export interface UIOptions {
+    /** Position of waypoint information display ('popup' or 'controls'). */
+    infoPosition?: 'popup' | 'controls';
+    /** Layout of scroll buttons ('inline' or 'below'). */
+    buttonPosition?: "inline" | "below";
+    /** Show a 'Start Experience' button before loading. */
+    showStartExperience?: boolean;
+    /** Enable Babylon.js debug layer (Ctrl+I). */
+    debugMode?: boolean;
+    /** Overall UI theme/layout type (e.g., 'default', 'minimal'). */
+    uiType?: string;
+    /** Hide the StorySplat watermark. */
+    hideWatermark?: boolean;
+    /** Custom text for the watermark. */
+    watermarkText?: string;
+    /** Custom link URL for the watermark. */
+    watermarkLink?: string;
+}
+/** Configuration options for the preloader UI element. */
+export interface PreloaderConfig {
+    /** URL for a custom image logo in the preloader. */
+    imageUrl?: string;
+    /** URL for a custom Lottie animation JSON in the preloader. */
+    lottieUrl?: string;
+    /** Override the default UI color specifically for the preloader elements (e.g., progress bar). Defaults to the main `uiColor` option if not set. */
+    uiColor?: string;
+    /** Set to false to completely disable the preloader UI. Defaults to true. */
+    enabled?: boolean;
+}

package/dist/types/ui/helpPanel.d.ts

@@ -0,0 +1,32 @@
+import { ViewerOptions } from "../types";
+/**
+ * Manages the Help Button and Panel UI.
+ */
+export declare class HelpPanelUI {
+    private container;
+    private options;
+    private helpButton?;
+    private helpPanel?;
+    private isVisible;
+    constructor(container: HTMLElement, options: ViewerOptions);
+    /**
+     * Creates the help button and panel if the option is enabled.
+     */
+    create(): void;
+    /**
+     * Populates the help panel's innerHTML based on viewer options.
+     */
+    private populateHelpContent;
+    /**
+     * Toggles the visibility of the help panel.
+     */
+    private toggleHelp;
+    /**
+     * Closes the help panel if a click occurs outside of it.
+     */
+    private handleOutsideClick;
+    /**
+     * Removes elements and event listeners.
+     */
+    dispose(): void;
+}

package/dist/types/ui/muteButton.d.ts

@@ -0,0 +1,30 @@
+import { ViewerOptions } from '../types/viewerOptions';
+import { AudioManager } from '../features/audioManager';
+/**
+ * Manages the creation and interaction of the Mute/Unmute button UI element.
+ */
+export declare class MuteButtonUI {
+    private targetElement;
+    private options;
+    private audioManager;
+    private buttonElement;
+    constructor(targetElement: HTMLElement, options: ViewerOptions, audioManager: AudioManager);
+    /**
+     * Creates the mute button element and adds it to the target container.
+     */
+    create(): void;
+    /**
+     * Handles the click event on the mute button.
+     */
+    private handleMuteToggle;
+    /**
+     * Updates the button's text/icon based on the mute state.
+     * This method is bound and potentially called by AudioManager.
+     * @param isMuted The current mute state.
+     */
+    updateButtonState(isMuted: boolean): void;
+    /**
+     * Removes the mute button element and cleans up event listeners.
+     */
+    dispose(): void;
+}

package/dist/types/ui/preloader.d.ts

@@ -0,0 +1,40 @@
+import { PreloaderConfig } from "../types";
+/**
+ * Manages the preloader UI element.
+ */
+export declare class PreloaderUI {
+    private container;
+    private config;
+    private preloaderElement?;
+    private progressBarElement?;
+    private progressTextElement?;
+    private logoElement?;
+    constructor(container: HTMLElement, config: PreloaderConfig);
+    /**
+     * Creates and appends the preloader HTML structure to the container.
+     */
+    create(): void;
+    /**
+     * Updates the progress bar percentage and the accompanying text.
+     * @param percentage - The progress percentage (0-100).
+     * @param text - Optional text to display (e.g., "Loading assets..."). Defaults to "Loading... X%".
+     */
+    updateProgress(percentage: number, text?: string): void;
+    /**
+     * Shows the preloader element. If it doesn't exist (e.g., after being hidden/disposed),
+     * it recreates it.
+     */
+    show(): void;
+    /**
+      * Hides the preloader with a fade-out animation and removes it from the DOM.
+      */
+    hide(): void;
+    /**
+     * Removes the preloader element from the DOM immediately.
+     */
+    dispose(): void;
+    /**
+     * Ensures the lottie-player script is loaded for lottie animations
+     */
+    private ensureLottiePlayerScript;
+}

package/dist/types/ui/startButton.d.ts

@@ -0,0 +1,29 @@
+import { ViewerOptions } from "../types";
+/**
+ * Manages the "Start Experience" button overlay UI.
+ */
+export declare class StartButtonUI {
+    private container;
+    private options;
+    private startButtonContainer?;
+    private startButton?;
+    private onStartCallback?;
+    constructor(container: HTMLElement, options: ViewerOptions, onStartCallback?: () => void);
+    /**
+     * Creates and appends the start button overlay if the option is enabled.
+     */
+    create(): void;
+    /**
+     * Handles the click event on the start button.
+     * Hides the overlay and triggers the callback.
+     */
+    private handleStartClick;
+    /**
+     * Hides the start button overlay with a fade-out animation and removes it.
+     */
+    hide(): void;
+    /**
+     * Removes the start button elements from the DOM immediately.
+     */
+    dispose(): void;
+}

package/dist/types/ui/uiManager.d.ts

@@ -0,0 +1,97 @@
+import { Scene } from "@babylonjs/core/scene";
+import { ViewerOptions } from "../types/viewerOptions";
+import { Interaction } from "../types/dataTypes";
+import { CameraManager } from "../core/cameraManager";
+import { NavigationManager } from "../features/navigationManager";
+import { AudioManager } from "../features/audioManager";
+import { StorySplatData, Waypoint } from "../types/dataTypes";
+/**
+ * Manages the creation, update, and interaction of HTML UI elements
+ * for the StorySplat viewer, based on the provided UIOptions.
+ */
+export declare class UIManager {
+    private targetElement;
+    private canvas;
+    private scene;
+    private options;
+    private data;
+    private uiOptions;
+    private cameraManager;
+    private navigationManager;
+    private audioManager;
+    private preloaderContainer?;
+    private startButtonContainer?;
+    private startButton?;
+    private fullscreenButton?;
+    private expandIcon?;
+    private compressIcon?;
+    private scrollControlsContainer?;
+    private scrollControlsContent?;
+    private scrollPercentageDisplay?;
+    private progressBarContainer?;
+    private progressBar?;
+    private scrollButtonsContainer?;
+    private prevButton?;
+    private nextButton?;
+    private playPauseButton?;
+    private waypointInfoDisplay?;
+    private modeToggleContainer?;
+    private modeToggleButtonGroup?;
+    private exploreToggleContainer?;
+    private droneToggleButton?;
+    private walkToggleButton?;
+    private muteButton?;
+    private helpButton?;
+    private helpPanel?;
+    private watermarkElement?;
+    private isMuted;
+    private helpVisible;
+    constructor(targetElement: HTMLElement, canvas: HTMLCanvasElement, scene: Scene, options: ViewerOptions, data: StorySplatData, cameraManager: CameraManager, navigationManager: NavigationManager | null, audioManager: AudioManager | null);
+    /** Creates the core UI elements based on options. */
+    private createBaseUI;
+    /** Sets up event listeners for UI interactions. */
+    private setupEventListeners;
+    private createFullscreenButton;
+    private createPreloader;
+    private createStartButton;
+    private createScrollControls;
+    private _styleScrollButton;
+    private _styleAutoplayButton;
+    private createModeToggles;
+    private createExploreWalkToggles;
+    private _styleExploreWalkButton;
+    private createMuteButton;
+    private createHelpButtonAndPanel;
+    private createWatermark;
+    private handlePrevWaypoint;
+    private handleNextWaypoint;
+    private handleModeChange;
+    private handleDroneToggle;
+    private handleWalkToggle;
+    private handleStartExperience;
+    private toggleFullscreen;
+    private handleMuteToggle;
+    private handleHelpToggle;
+    private handleDocumentClickForHelp;
+    /** Updates the preloader progress display. */
+    updateProgress(percentage: number, text?: string): void;
+    /** Hides the preloader element. */
+    hidePreloader(): void;
+    /** Updates the fullscreen button icons based on the current state. */
+    updateFullscreenIcons: () => void;
+    /** Cleans up UI elements and event listeners. */
+    dispose(): void;
+    /** Updates the visual state of the mode toggle buttons. */
+    updateModeToggleButtons(): void;
+    /** Updates the visual state of the explore/walk toggle buttons. */
+    updateExploreWalkToggleButtons(): void;
+    /** Shows or hides the scroll controls based on the current camera mode. */
+    updateScrollControlsVisibility(): void;
+    /** Updates the scroll progress bar and percentage display. */
+    updateScrollProgress(percentage: number): void;
+    /** Displays information about the current waypoint. */
+    showWaypointInfo(waypoint: Waypoint | null): void;
+    /** Displays information from a triggered interaction. */
+    showInteractionInfo(interaction: Interaction | null): void;
+    private _applyBasicStyles;
+}

package/dist/types/ui/watermark.d.ts

@@ -0,0 +1,18 @@
+import { ViewerOptions } from "../types";
+/**
+ * Manages the watermark UI element.
+ */
+export declare class WatermarkUI {
+    private container;
+    private options;
+    private watermarkElement?;
+    constructor(container: HTMLElement, options: ViewerOptions);
+    /**
+     * Creates and appends the watermark element if not hidden in options.
+     */
+    create(): void;
+    /**
+     * Removes the watermark element from the DOM.
+     */
+    dispose(): void;
+}

package/dist/types/utils/helpers.d.ts

@@ -0,0 +1,81 @@
+import { Quaternion } from "@babylonjs/core/Maths/math.vector";
+import { Color3, Color4, Vector3 } from "@babylonjs/core/Maths/math";
+/**
+ * Adjusts the brightness of a hex color string.
+ * @param color - The hex color string (e.g., "#RRGGBB").
+ * @param percent - The percentage to adjust brightness by (positive for lighter, negative for darker).
+ * @returns The adjusted hex color string.
+ */
+export declare const adjustColorBrightness: (color: string, percent: number) => string;
+/**
+ * Basic check if the current environment appears to be a mobile device based on user agent.
+ * Note: User agent sniffing is generally unreliable; consider feature detection instead if possible.
+ * This function might return false positives or negatives.
+ * @returns True if the user agent string matches common mobile patterns, false otherwise.
+ */
+export declare const isMobileDevice: () => boolean;
+/**
+ * Converts a simple {r, g, b} object to a BabylonJS Color3 object.
+ * Handles potential undefined input.
+ * @param colorObj - The color object { r, g, b } (values 0-1).
+ * @param defaultColor - The default Color3 to return if input is invalid.
+ * @returns A BabylonJS Color3 object.
+ */
+export declare const toColor3: (colorObj?: {
+    r: number;
+    g: number;
+    b: number;
+}, defaultColor?: Color3) => Color3;
+/**
+ * Converts a simple {r, g, b, a} object to a BabylonJS Color4 object.
+ * Handles potential undefined input. Alpha defaults to 1 if not provided.
+ * @param colorObj - The color object { r, g, b, a? } (values 0-1).
+ * @param defaultColor - The default Color4 to return if input is invalid.
+ * @returns A BabylonJS Color4 object.
+ */
+export declare const toColor4: (colorObj?: {
+    r: number;
+    g: number;
+    b: number;
+    a?: number;
+}, defaultColor?: Color4) => Color4;
+/**
+ * Converts a simple {x, y, z} object to a BabylonJS Vector3 object.
+ * Handles potential undefined input.
+ * @param vecObj - The vector object { x, y, z }.
+ * @param defaultVector - The default Vector3 to return if input is invalid.
+ * @returns A BabylonJS Vector3 object.
+ */
+export declare const toVector3: (vecObj?: {
+    x: number;
+    y: number;
+    z: number;
+}, defaultVector?: Vector3) => Vector3;
+/**
+ * Converts a simple {_x, _y, _z, _w} object to a BabylonJS Quaternion object.
+ * Handles potential undefined input.
+ * @param quatObj - The quaternion object { _x, _y, _z, _w }.
+ * @param defaultQuaternion - The default Quaternion to return if input is invalid.
+ * @returns A BabylonJS Quaternion object.
+ */
+export declare const toQuaternion: (quatObj?: {
+    _x: number;
+    _y: number;
+    _z: number;
+    _w: number;
+}, defaultQuaternion?: Quaternion) => Quaternion;
+/**
+ * Converts a hex color string (e.g., "#RRGGBB") to a BabylonJS Color3 object.
+ * Handles potential undefined or invalid input.
+ * @param hex - The hex color string.
+ * @param defaultColor - The default Color3 to return if input is invalid.
+ * @returns A BabylonJS Color3 object.
+ */
+export declare const hexToColor3: (hex?: string, defaultColor?: Color3) => Color3;
+/**
+ * Applies opacity to a mesh and its children's materials.
+ * Handles StandardMaterial and potentially PBRMaterial alpha/transparencyMode.
+ * @param mesh - The root mesh to apply opacity to.
+ * @param opacity - The opacity value (0-1).
+ */
+export declare function applyOpacityToMeshAndChildren(mesh: import("@babylonjs/core/Meshes/abstractMesh").AbstractMesh | null, opacity: number): void;