@series-inc/rundot-3d-engine 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,1484 @@
+import { C as Component, A as AnimationCullingManager, G as GameObject, R as RigidBodyComponentThree, a as ComponentJSON, P as PrefabNode } from './ComponentRegistry-V_7WauAE.js';
+import * as THREE from 'three';
+export * from '@series-inc/rundot-game-sdk';
+export { default as RundotGameAPI } from '@series-inc/rundot-game-sdk/api';
+import '@dimforge/rapier3d';
+
+/**
+ * Component updater for Three.js components
+ * Handles the update loop for all registered components
+ */
+declare class ComponentUpdater {
+    private static updateableComponents;
+    private static lateUpdateableComponents;
+    private static updateCount;
+    /**
+     * Register a component for updates
+     * @internal Only called by Component class
+     */
+    static registerComponent(component: Component): void;
+    /**
+     * Unregister a component from updates
+     * @internal Only called by Component class
+     */
+    static unregisterComponent(component: Component): void;
+    /**
+     * Register a component for late updates
+     * @internal Only called by Component class
+     */
+    static registerLateUpdateComponent(component: Component): void;
+    /**
+     * Unregister a component from late updates
+     * @internal Only called by Component class
+     */
+    static unregisterLateUpdateComponent(component: Component): void;
+    /**
+     * Initialize the component updater
+     */
+    static initialize(scene: THREE.Scene): void;
+    /**
+     * Update all registered components
+     */
+    static update(deltaTime: number): void;
+    /**
+     * Late update all registered components
+     */
+    static lateUpdate(deltaTime: number): void;
+    /**
+     * Dispose all components
+     */
+    static dispose(): void;
+}
+
+/**
+ * Configuration interface for VenusGame.
+ * Override getConfig() in your game class to customize these settings.
+ */
+interface VenusGameConfig {
+    /** Background color as hex number (default: 0x000000) */
+    backgroundColor?: number;
+    /** Enable antialiasing for smoother edges (default: true) */
+    antialias?: boolean;
+    /** Enable shadow mapping (default: true) */
+    shadowMapEnabled?: boolean;
+    /** Shadow map type: 'vsm' for smoother shadows, 'pcf_soft' for softer edges (default: 'vsm') */
+    shadowMapType?: "vsm" | "pcf_soft";
+    /** Tone mapping: 'aces' for filmic, 'linear' for basic, 'none' to disable (default: 'aces') */
+    toneMapping?: "aces" | "linear" | "none";
+    /** Tone mapping exposure (default: 1.0) */
+    toneMappingExposure?: number;
+    /** Enable audio system and auto-create listener (default: true) */
+    audioEnabled?: boolean;
+}
+/**
+ * Three.js version of VenusGame
+ * Clean implementation without Babylon.js dependencies
+ */
+declare abstract class VenusGame {
+    private static _instance;
+    private static _scene;
+    private static _renderer;
+    private static _camera;
+    protected canvas: HTMLCanvasElement;
+    protected renderer: THREE.WebGLRenderer;
+    protected scene: THREE.Scene;
+    protected camera: THREE.PerspectiveCamera;
+    private resizeListener;
+    private isDisposed;
+    private animationId;
+    private clock;
+    private maxDeltaTime;
+    protected config: Required<VenusGameConfig>;
+    protected audioListener: THREE.AudioListener | null;
+    private animationCullingManager;
+    /**
+     * Get the current elapsed time (not delta time)
+     * NOTE: For delta time, use the parameter passed to preRender() method
+     * This prevents accidental multiple getDelta() calls which cause frame rate dependent behavior
+     */
+    protected getElapsedTime(): number;
+    /**
+     * Override this method to provide game-specific configuration.
+     * The returned config is merged with DEFAULT_CONFIG.
+     * @example
+     * protected getConfig(): VenusGameConfig {
+     *   return {
+     *     backgroundColor: 0x0077b6,
+     *     toneMapping: "aces",
+     *   }
+     * }
+     */
+    protected getConfig(): VenusGameConfig;
+    /**
+     * Get the active VenusGame instance
+     */
+    static get instance(): VenusGame;
+    /**
+     * Get the active Three.js scene
+     */
+    static get scene(): THREE.Scene;
+    /**
+     * Get the active Three.js renderer
+     */
+    static get renderer(): THREE.WebGLRenderer;
+    /**
+     * Get the active Three.js camera
+     */
+    static get camera(): THREE.PerspectiveCamera;
+    /**
+     * Set the camera used for animation frustum culling.
+     * When set, animation updates are skipped for characters outside the camera's view.
+     * @param camera The camera to use for culling (pass null to disable)
+     * @param frustumExpansion How much to expand the frustum (1.2 = 20% larger, avoids pop-in). Default: 1.2
+     */
+    static setAnimationCullingCamera(camera: THREE.Camera | null, frustumExpansion?: number): void;
+    /**
+     * Get the animation culling manager for advanced configuration.
+     * Use this to enable distance culling, add multiple cameras, adjust LOD settings, etc.
+     */
+    static getAnimationCulling(): AnimationCullingManager;
+    /**
+     * Static factory method to create, initialize and start a VenusGame instance
+     * @returns A fully initialized and running VenusGame instance
+     */
+    static create<T extends VenusGame>(this: new () => T): Promise<T>;
+    resume(): void;
+    pause(): void;
+    /**
+     * Create a new VenusGame
+     */
+    constructor();
+    /**
+     * Apply rendering configuration from config
+     */
+    private applyRenderingConfig;
+    /**
+     * Set up audio listener if enabled in config.
+     * Attaches listener to camera and sets AudioSystem.mainListener.
+     */
+    private setupAudioListener;
+    /**
+     * Check if running on an iPhone/iPad specifically
+     */
+    private isIPhone;
+    /**
+     * Check if running on a mobile device
+     */
+    private isMobileDevice;
+    private isPaused;
+    private prevMasterVolume;
+    /**
+     * Start the render loop
+     */
+    private startRenderLoop;
+    /**
+     * Setup visibility change handling to pause/resume delta time
+     */
+    private setupVisibilityHandling;
+    /**
+     * Render method. Can be overridden for custom rendering pipelines.
+     */
+    protected render(): void;
+    /**
+     * Abstract method that derived classes must implement for game-specific initialization
+     */
+    protected abstract onStart(): Promise<void>;
+    /**
+     * Abstract method called every frame before rendering
+     * @param deltaTime Time in seconds since last frame - use this for all time-based calculations
+     * IMPORTANT: Do NOT access this.clock.getDelta() directly - use the deltaTime parameter!
+     */
+    protected abstract preRender(deltaTime: number): void;
+    /**
+     * Abstract method that derived classes must implement for game cleanup
+     */
+    protected abstract onDispose(): Promise<void>;
+    /**
+     * Dispose of the game, cleaning up all resources
+     * This will stop the render loop and clean up any created resources
+     */
+    dispose(): Promise<void>;
+}
+
+/**
+ * Asset info for a loaded asset in Three.js
+ */
+interface AssetInfo {
+    path: string;
+    group?: THREE.Group;
+    gltf?: any;
+    isLoaded: boolean;
+    isLoading: boolean;
+    meshes: THREE.Mesh[];
+    materials: THREE.Material[];
+    animations: THREE.AnimationClip[];
+}
+/**
+ * GPU Instance batch for managing InstancedMesh objects
+ */
+interface GPUInstanceBatch {
+    instancedMesh: THREE.InstancedMesh;
+    assetPath: string;
+    material: THREE.Material;
+    instances: GPUInstanceData[];
+    maxInstances: number;
+    needsUpdate: boolean;
+    cullingRadius: number;
+    hasDynamicObjects: boolean;
+}
+/**
+ * Individual instance data within a GPU batch
+ */
+interface GPUInstanceData {
+    id: string;
+    gameObject: GameObject;
+    matrix: THREE.Matrix4;
+    isActive: boolean;
+    isStatic: boolean;
+}
+/**
+ * Instance tracking for debugging and performance monitoring
+ */
+interface InstanceStats$1 {
+    totalInstances: number;
+    sharedInstances: number;
+    clonedInstances: number;
+    brokenInstances: number;
+    gpuInstances: number;
+    gpuBatches: number;
+}
+/**
+ * Global instancing statistics for debug display
+ */
+interface GlobalInstanceStats {
+    totalAssets: number;
+    loadedAssets: number;
+    totalInstances: number;
+    sharedInstances: number;
+    clonedInstances: number;
+    brokenInstances: number;
+    gpuInstances: number;
+    gpuBatches: number;
+    geometryReuse: number;
+    materialReuse: number;
+}
+/**
+ * A Three.js asset manager optimized for preloading workflows
+ * Compatible API with the original Babylon.js AssetManager
+ *
+ * RECOMMENDED USAGE PATTERN:
+ * 1. Initialize: AssetManager.init(scene)
+ * 2. Preload all assets: await AssetManager.preloadAssets([...paths])
+ * 3. Use synchronously: AssetManager.getMesh() / getAssetGroup()
+ * 4. Create renderers: new ObjRendererThree() (now fully synchronous)
+ *
+ * SUPPORTED FORMATS:
+ * - .glb/.gltf (using GLTFLoader)
+ * - .obj (using OBJLoader)
+ * - .mtl (material files for OBJ)
+ * - .fbx (using FBXLoader)
+ * - .stow (using StowKitLoader)
+ */
+declare class AssetManager {
+    private static _scene;
+    private static _assets;
+    private static _instanceStats;
+    private static _gpuBatches;
+    private static _baseUrl;
+    private static _gltfLoader;
+    private static _objLoader;
+    private static _mtlLoader;
+    private static _fbxLoader;
+    private static _isPreloadingComplete;
+    private static _skeletonCache;
+    private static _frustumCullingPadding;
+    private static _frustumCullingEnabled;
+    /**
+     * Initialize the AssetManager with a scene
+     * @param scene The Three.js scene to use
+     * @param renderer Optional WebGL renderer for StowKit texture support
+     */
+    static init(scene: THREE.Scene, renderer?: THREE.WebGLRenderer): void;
+    /**
+     * Set base URL for resolving relative paths (optional - defaults to relative paths)
+     * @param baseUrl The base URL to use
+     */
+    static setBaseUrl(baseUrl: string): void;
+    /**
+     * Get the full path for an asset - automatically handles relative paths
+     */
+    static getFullPath(path: string): string;
+    /**
+     * Preload multiple assets in bulk - RECOMMENDED WORKFLOW
+     * Call this once at app startup, then use synchronous methods for the rest of the app
+     * @param assetPaths Array of asset paths to preload
+     * @param progressCallback Optional callback for overall progress (0-1)
+     * @returns Promise that resolves when all assets are loaded (or failed)
+     */
+    static preloadAssets(assetPaths: string[], progressCallback?: (progress: number, loadedCount: number, totalCount: number) => void): Promise<{
+        loaded: string[];
+        failed: string[];
+    }>;
+    /**
+     * Check if preloading workflow has been completed
+     * This doesn't guarantee all assets loaded successfully, just that preloading finished
+     */
+    static isPreloadingComplete(): boolean;
+    /**
+     * Load an asset by path (used internally by preloadAssets)
+     * @param path Path to the asset
+     * @param progressCallback Optional callback for loading progress
+     */
+    static loadAsset(path: string, progressCallback?: (progress: number) => void): Promise<boolean>;
+    /**
+     * Check if an asset is loaded and throw an error if not
+     * Use this for strict preloading workflows - RECOMMENDED for ObjRendererThree
+     * @param path Path to the asset
+     * @throws Error if asset is not preloaded
+     */
+    static requireAsset(path: string): AssetInfo;
+    /**
+     * Get a list of all preloaded asset paths
+     */
+    static getPreloadedAssets(): string[];
+    /**
+     * Get a list of all failed asset paths
+     */
+    static getFailedAssets(): string[];
+    /**
+     * Get preloading statistics
+     */
+    static getPreloadingStats(): {
+        total: number;
+        loaded: number;
+        failed: number;
+        loading: number;
+        completionPercentage: number;
+    };
+    /**
+     * Get GLTF data for a loaded GLTF/GLB asset - SYNCHRONOUS (use after preloading)
+     * @param path Path to the asset
+     * @returns GLTF data or null if not a GLTF asset
+     */
+    static getGLTF(path: string): any | null;
+    /**
+     * Load GLTF/GLB asset
+     * @private
+     */
+    private static loadGLTFAsset;
+    /**
+     * Load OBJ asset
+     * @private
+     */
+    private static loadOBJAsset;
+    /**
+     * Load OBJ with or without materials
+     * @private
+     */
+    private static loadOBJWithMaterials;
+    /**
+     * Load FBX asset
+     * @private
+     */
+    private static loadFBXAsset;
+    /**
+     * Get the asset group for a loaded asset - SYNCHRONOUS (use after preloading)
+     * @param path Path to the asset
+     * @returns The Group for the asset or null if not loaded
+     */
+    static getAssetGroup(path: string): THREE.Group | null;
+    /**
+     * Get the primary mesh from a loaded asset - SYNCHRONOUS (use after preloading)
+     * @param path Path to the asset
+     * @returns The primary Mesh from the asset or null if not found
+     */
+    static getMesh(path: string): THREE.Mesh | null;
+    /**
+     * Get all meshes from a loaded asset - SYNCHRONOUS (use after preloading)
+     * @param path Path to the asset
+     * @returns Array of meshes from the asset
+     */
+    static getMeshes(path: string): THREE.Mesh[];
+    /**
+     * Get all materials from a loaded asset - SYNCHRONOUS (use after preloading)
+     * @param path Path to the asset
+     * @returns Array of materials from the asset
+     */
+    static getMaterials(path: string): THREE.Material[];
+    /**
+     * Get all animations from a loaded asset - SYNCHRONOUS (use after preloading)
+     * @param path Path to the asset
+     * @returns Array of animation clips from the asset
+     */
+    static getAnimations(path: string): THREE.AnimationClip[];
+    /**
+     * Register a StowKit-loaded asset for compatibility with existing code
+     * Allows StowKit assets to be accessed via the same AssetManager.getAssetGroup() API
+     * @param path Virtual path to register the asset under (e.g. 'v2/restaurant_display_default.fbx')
+     * @param group The THREE.Group loaded from StowKit
+     */
+    static registerStowKitAsset(path: string, group: THREE.Group): void;
+    private static _stowkitTextures;
+    /**
+     * Register a StowKit-loaded texture for use by materials
+     * @param name Texture name/ID
+     * @param texture The THREE.Texture loaded from StowKit
+     */
+    static registerStowKitTexture(name: string, texture: THREE.Texture): void;
+    /**
+     * Get a StowKit-loaded texture by name
+     * @param name Texture name/ID
+     * @returns The texture or null if not found
+     */
+    static getStowKitTexture(name: string): THREE.Texture | null;
+    /**
+     * Unload an asset to free memory
+     * @param path Path to the asset
+     */
+    static unloadAsset(path: string): void;
+    /**
+     * Check if an asset is loaded
+     * @param path Path to the asset
+     */
+    static isLoaded(path: string): boolean;
+    /**
+     * Get the current base URL being used
+     */
+    static getBaseUrl(): string;
+    /**
+     * Reset to default relative path behavior
+     */
+    static useRelativePaths(): void;
+    /**
+     * Get loading progress for all assets
+     * @returns Object with loading statistics
+     * @deprecated Use getPreloadingStats() instead for better information
+     */
+    static getLoadingStats(): {
+        loaded: number;
+        loading: number;
+        total: number;
+    };
+    /**
+     * Track when a shared instance is converted to cloned (broken instancing)
+     * @param assetPath Path to the asset
+     */
+    static trackInstanceBroken(assetPath: string): void;
+    /**
+     * Get instance statistics for a specific asset
+     * @param assetPath Path to the asset
+     */
+    static getAssetInstanceStats(assetPath: string): InstanceStats$1;
+    /**
+     * Get global instancing statistics for debug display
+     */
+    static getGlobalInstanceStats(): GlobalInstanceStats;
+    /**
+     * Get detailed instancing report for debugging
+     */
+    static getInstanceReport(): string;
+    /**
+     * Create or get a GPU instance batch for an asset
+     * @param assetPath Path to the asset
+     * @param material Material to use for the batch
+     * @param maxInstances Maximum instances in this batch (default: 1000)
+     */
+    static getOrCreateGPUBatch(assetPath: string, material: THREE.Material, maxInstances?: number): GPUInstanceBatch | null;
+    /**
+     * Add a GPU instance to a batch
+     * @param assetPath Path to the asset
+     * @param gameObject GameObject to instance
+     * @param material Material to use
+     * @param isStatic Whether this instance is static (won't move after creation)
+     * @returns Instance ID or null if failed
+     */
+    static addGPUInstance(assetPath: string, gameObject: GameObject, material: THREE.Material, isStatic?: boolean): string | null;
+    /**
+     * Remove a GPU instance from its batch
+     * @param assetPath Path to the asset
+     * @param instanceId Instance ID to remove
+     */
+    static removeGPUInstance(assetPath: string, instanceId: string): void;
+    /**
+     * Set the visibility of a specific GPU instance
+     * @param assetPath Path to the asset
+     * @param instanceId Instance ID to show/hide
+     * @param visible Whether the instance should be visible
+     */
+    static setGPUInstanceVisible(assetPath: string, instanceId: string, visible: boolean): void;
+    /**
+     * Get the visibility of a specific GPU instance
+     * @param assetPath Path to the asset
+     * @param instanceId Instance ID to check
+     * @returns Whether the instance is visible
+     */
+    static getGPUInstanceVisible(assetPath: string, instanceId: string): boolean;
+    /**
+     * Convert a GPU instance to object-level instance (for scaling, etc.)
+     * @param assetPath Path to the asset
+     * @param instanceId Instance ID to convert
+     * @returns New GameObject with ObjRenderer or null if failed
+     */
+    static convertGPUToObjectLevel(assetPath: string, instanceId: string): any | null;
+    /**
+     * Update GPU batch matrices and upload to GPU
+     * @param batch GPU batch to update
+     * @param camera Optional camera for frustum culling
+     */
+    static updateGPUBatch(batch: GPUInstanceBatch, camera?: THREE.Camera): void;
+    /**
+     * Update GPU batch statistics
+     * @param assetPath Path to the asset
+     */
+    private static updateGPUBatchStats;
+    /**
+     * Track when an instance is created from an asset
+     * @param assetPath Path to the asset
+     * @param isShared Whether this is a shared instance (true) or cloned (false)
+     * @param isGPU Whether this is a GPU instance (true) or object-level (false)
+     */
+    static trackInstanceCreated(assetPath: string, isShared: boolean, isGPU?: boolean): void;
+    /**
+     * Track when an instance is destroyed
+     * @param assetPath Path to the asset
+     * @param wasShared Whether this was a shared instance
+     * @param wasGPU Whether this was a GPU instance
+     */
+    static trackInstanceDestroyed(assetPath: string, wasShared: boolean, wasGPU?: boolean): void;
+    /**
+     * Update all GPU batches with optional frustum culling
+     * Now uses separated static/dynamic logic for optimal performance
+     * @param camera Optional camera for frustum culling
+     * @param debug Whether to log frustum culling statistics (default: false)
+     */
+    static updateAllGPUBatches(camera?: THREE.Camera, debug?: boolean): void;
+    /**
+     * DEBUG: Force update all GPU batches
+     * Call this from console to manually trigger batch updates
+     */
+    static debugUpdateAllGPUBatches(): void;
+    /**
+     * Update only dynamic GPU batches (called every frame for immediate updates)
+     * @param camera Optional camera for frustum culling
+     * @param debug Whether to log statistics (default: false)
+     */
+    static updateDynamicGPUBatches(camera?: THREE.Camera, debug?: boolean): void;
+    /**
+     * DEBUG: Show static vs dynamic batch breakdown
+     */
+    static debugBatchTypes(): void;
+    /**
+     * Set frustum culling padding multiplier
+     * Higher values = less aggressive culling (fewer false positives)
+     * Lower values = more aggressive culling (more performance, more false positives)
+     * @param padding Padding multiplier (default: 1.2 = 20% padding)
+     */
+    static setFrustumCullingPadding(padding: number): void;
+    /**
+     * Get current frustum culling padding multiplier
+     */
+    static getFrustumCullingPadding(): number;
+    /**
+     * Enable or disable frustum culling globally
+     * @param enabled Whether frustum culling should be enabled
+     */
+    static setFrustumCullingEnabled(enabled: boolean): void;
+    /**
+     * Get current frustum culling enabled state
+     */
+    static isFrustumCullingEnabled(): boolean;
+    /**
+     * DEBUG: Test frustum culling by temporarily disabling it
+     * @param disabled Whether to disable frustum culling entirely (for testing)
+     */
+    static debugFrustumCulling(disabled?: boolean): void;
+    /**
+     * Preload a skeletal FBX model using SkeletonCache
+     * Use this for character models that need proper bone cloning
+     */
+    static preloadSkeletalModel(path: string): Promise<THREE.Object3D>;
+    /**
+     * Register a skeletal model directly (for StowKit or other loaders)
+     * Use this for character models loaded from StowKit
+     */
+    static registerSkeletalModel(path: string, object: THREE.Object3D): void;
+    /**
+     * Get a properly cloned skeletal model
+     * Uses SkeletonUtils.clone() to preserve bone relationships for animation
+     */
+    static getSkeletalClone(path: string): THREE.Object3D | null;
+    /**
+     * Check if a skeletal model is loaded
+     */
+    static isSkeletalModelLoaded(path: string): boolean;
+    /**
+     * Get the original skeletal model (for reference, not for use)
+     */
+    static getSkeletalOriginal(path: string): THREE.Object3D | null;
+    /**
+     * Clear all global state (for testing) - now includes skeleton cache
+     */
+    static reset(): void;
+}
+
+/**
+ * Instance-based cache system for skeletal/animated FBX models
+ * Uses SkeletonUtils.clone() for proper bone/animation preservation
+ * Used internally by AssetManager
+ */
+declare class SkeletonCache {
+    private loader;
+    private originals;
+    private loading;
+    isLoaded(path: string): boolean;
+    /**
+     * Preload a skeletal FBX model
+     */
+    preload(path: string): Promise<THREE.Object3D>;
+    /**
+     * Register a skeletal model directly (for StowKit or other loaders)
+     */
+    register(path: string, object: THREE.Object3D): void;
+    /**
+     * Get a properly cloned skeletal model
+     * Uses SkeletonUtils.clone() to preserve bone relationships
+     */
+    getClone(path: string): THREE.Object3D | null;
+    /**
+     * Get the original (non-cloned) model
+     */
+    getOriginal(path: string): THREE.Object3D | null;
+    /**
+     * Clear all cached models (for cleanup/testing)
+     */
+    clear(): void;
+    /**
+     * Get all cached paths
+     */
+    getCachedPaths(): string[];
+}
+
+/**
+ * Simple interaction zone using Rapier physics triggers
+ * Replaces the complex raycasting system with simple physics triggers
+ */
+declare class InteractionZone extends Component {
+    readonly id: string;
+    private active;
+    private onEnterCallback?;
+    private onExitCallback?;
+    private entitiesInZone;
+    private rigidBody;
+    private visualMesh;
+    private options;
+    constructor(onEnter?: (other: GameObject) => void, onExit?: (other: GameObject) => void, options?: InteractionZoneOptions);
+    /**
+     * Set interaction callbacks
+     */
+    setCallbacks(callbacks: {
+        onEnter?: (other: GameObject) => void;
+        onExit?: (other: GameObject) => void;
+    }): void;
+    /**
+     * Called when component is attached to GameObject
+     */
+    protected onCreate(): void;
+    onEnabled(): void;
+    /**
+     * Create the visual mesh for the interaction zone
+     */
+    private createVisualMesh;
+    /**
+     * Create the physics trigger collider
+     */
+    private createTriggerCollider;
+    /**
+     * Handle trigger enter event (to be called by physics system)
+     */
+    onTriggerEnter(other: GameObject): void;
+    /**
+     * Handle trigger exit event (to be called by physics system)
+     */
+    onTriggerExit(other: GameObject): void;
+    /**
+     * Get all entities currently in the zone
+     */
+    getEntitiesInZone(): GameObject[];
+    /**
+     * Check if a specific entity is in the zone
+     */
+    hasEntity(entity: GameObject): boolean;
+    /**
+     * Set active state
+     */
+    setActive(active: boolean): void;
+    /**
+     * Check if the interaction zone is active
+     */
+    isActive(): boolean;
+    /**
+     * Get the visual mesh
+     */
+    getVisualMesh(): THREE.Mesh | null;
+    /**
+     * Get the collider component
+     */
+    getCollider(): RigidBodyComponentThree | null;
+    /**
+     * Get the GameObject this zone is attached to
+     */
+    getGameObject(): GameObject;
+    /**
+     * Component cleanup
+     */
+    protected onCleanup(): void;
+}
+interface InteractionZoneOptions {
+    width?: number;
+    depth?: number;
+    active?: boolean;
+    centerOffset?: THREE.Vector2;
+    show?: boolean;
+}
+
+interface VirtualJoystickOptions {
+    size?: number;
+    knobSize?: number;
+    deadZone?: number;
+    maxDistance?: number;
+    color?: string;
+    visible?: boolean;
+    opacity?: number;
+}
+/**
+ * Virtual joystick component for mobile/touch input - Three.js version
+ * Shows on pointer down, hides on pointer up
+ * Provides normalized direction vector for movement
+ * Uses HTML/CSS for UI elements
+ */
+declare class VirtualJoystickThree extends Component {
+    private options;
+    private static isMobileDevice;
+    private joystickContainer;
+    private joystickBase;
+    private joystickKnob;
+    private mobileHint;
+    private isActive;
+    private startPosition;
+    private currentPosition;
+    private direction;
+    private magnitude;
+    private joystickPointerId;
+    private isDragging;
+    private joystickRadius;
+    private boundPointerDown;
+    private boundPointerMove;
+    private boundPointerUp;
+    private boundTouchStart;
+    private boundTouchMove;
+    private boundTouchEnd;
+    constructor(options?: VirtualJoystickOptions);
+    protected onCreate(): void;
+    protected onCleanup(): void;
+    /**
+     * Create the joystick UI elements using HTML/CSS
+     */
+    private createJoystickUI;
+    /**
+     * Create mobile hint for touch controls (only shows on mobile devices)
+     */
+    private createMobileHint;
+    /**
+     * Setup input handlers for pointer and touch events
+     */
+    private setupInputHandlers;
+    /**
+     * Remove input handlers
+     */
+    private removeInputHandlers;
+    /**
+     * Handle pointer down event
+     */
+    private onPointerDown;
+    /**
+     * Handle touch start event (fallback)
+     */
+    private onTouchStart;
+    /**
+     * Start the joystick at the given position
+     */
+    private startJoystick;
+    /**
+     * Handle pointer move event
+     */
+    private onPointerMove;
+    /**
+     * Handle touch move event (fallback)
+     */
+    private onTouchMove;
+    /**
+     * Update joystick position and direction
+     */
+    private updateJoystick;
+    /**
+     * Handle pointer up event
+     */
+    private onPointerUp;
+    /**
+     * Handle touch end event (fallback)
+     */
+    private onTouchEnd;
+    /**
+     * End the joystick interaction
+     */
+    private endJoystick;
+    /**
+     * Update knob position based on current pointer position
+     */
+    private updateKnobPosition;
+    /**
+     * Update direction vector based on knob position
+     */
+    private updateDirection;
+    /**
+     * Get the current input direction as a Vector3 (Y=0 for movement)
+     */
+    getDirection(): THREE.Vector3 | null;
+    /**
+     * Get the current input magnitude (0-1)
+     */
+    getMagnitude(): number;
+    /**
+     * Check if the joystick is currently active
+     */
+    isActiveJoystick(): boolean;
+    /**
+     * Toggle joystick visual visibility (joystick remains functional)
+     */
+    setVisible(visible: boolean): void;
+    /**
+     * Get current visibility state
+     */
+    isVisible(): boolean;
+    /**
+     * Set joystick opacity (0-1)
+     */
+    setOpacity(opacity: number): void;
+    /**
+     * Get current opacity
+     */
+    getOpacity(): number;
+    /**
+     * Clean up UI resources
+     */
+    private cleanupUI;
+}
+
+/**
+ * Three.js Movement controller component that handles physics-based movement and rotation
+ * Uses Rapier physics with rotation locking for smooth, controlled movement
+ * Can be used for player input, AI navigation, or any entity that needs to move
+ */
+declare class MovementController extends Component {
+    maxMoveSpeed: number;
+    acceleration: number;
+    turnSpeed: number;
+    private rigidBodyComponent;
+    private targetRotationY;
+    private currentRotationY;
+    private _currentVelocity;
+    /**
+     * Called when the component is created and attached to a GameObject
+     */
+    protected onCreate(): void;
+    /**
+     * Find the rigid body component on this GameObject
+     */
+    private findRigidBodyComponentThree;
+    /**
+     * Set the rigid body component this controller should manage
+     */
+    setRigidBodyComponentThree(rigidBodyComponent: RigidBodyComponentThree): void;
+    /**
+     * Move the entity based on input direction
+     * @param inputDirection Normalized direction vector (or null for no movement)
+     * @param deltaTime Time since last frame in seconds
+     */
+    move(inputDirection: THREE.Vector3 | null, deltaTime: number): void;
+    /**
+     * Calculate target velocity based on input direction
+     */
+    private calculateTargetVelocity;
+    /**
+     * Smooth velocity towards target using acceleration
+     */
+    private smoothVelocity;
+    /**
+     * Update rotation smoothly towards movement direction using quaternion slerp
+     */
+    private updateRotation;
+    /**
+     * Utility function to move a value towards a target at a given rate
+     */
+    private moveTowards;
+    /**
+     * Get current movement state for debugging
+     */
+    getMovementState(): any;
+    /**
+     * Clean up resources when the component is removed
+     */
+    protected onCleanup(): void;
+}
+
+/**
+ * Three.js Player Controller Component
+ * Handles WASD movement, mouse look, and basic interactions
+ */
+declare class PlayerControllerThree extends Component {
+    moveSpeed: number;
+    runSpeed: number;
+    rotationSpeed: number;
+    private controls;
+    private keys;
+    private mouseX;
+    private mouseY;
+    private mouseSensitivity;
+    private isPointerLocked;
+    private camera;
+    private cameraHeight;
+    private velocity;
+    private direction;
+    constructor(camera: THREE.PerspectiveCamera);
+    protected onCreate(): void;
+    /**
+     * Set up keyboard and mouse event listeners
+     */
+    private setupEventListeners;
+    /**
+     * Set up pointer lock for mouse look
+     */
+    private setupPointerLock;
+    /**
+     * Handle key down events
+     */
+    private onKeyDown;
+    /**
+     * Handle key up events
+     */
+    private onKeyUp;
+    /**
+     * Handle mouse movement for looking around
+     */
+    private onMouseMove;
+    /**
+     * Handle canvas clicks for pointer lock
+     */
+    private onClick;
+    /**
+     * Handle pointer lock state changes
+     */
+    private onPointerLockChange;
+    /**
+     * Handle interaction key press
+     */
+    private onInteract;
+    /**
+     * Update method - called every frame
+     */
+    update(deltaTime: number): void;
+    /**
+     * Update player movement based on input
+     */
+    private updateMovement;
+    /**
+     * Update camera position to follow player
+     */
+    private updateCameraPosition;
+    /**
+     * Get current movement state for debugging
+     */
+    getMovementState(): {
+        position: THREE.Vector3;
+        isMoving: boolean;
+        isRunning: boolean;
+        lookDirection: THREE.Vector3;
+    };
+    /**
+     * Set player position
+     */
+    setPosition(position: THREE.Vector3): void;
+    /**
+     * Clean up event listeners
+     */
+    protected onCleanup(): void;
+}
+
+/**
+ * Three.js Skeletal renderer for animated FBX models
+ * - Uses AssetManager for preloading coordination
+ * - Uses SkeletonCache for proper skeletal cloning
+ * - Specifically designed for animated characters
+ * - Always cloned, always has shadows, never static
+ */
+declare class SkeletalRenderer extends Component {
+    private _group;
+    private _assetPath;
+    private _material;
+    private _skeletalModel;
+    constructor(assetPath: string, material?: THREE.Material);
+    protected onCreate(): void;
+    private createSkeletalMesh;
+    private applyShadowsToGroup;
+    /**
+     * Get the wrapper group (attached to GameObject)
+     */
+    getGroup(): THREE.Group | null;
+    /**
+     * Get the skeletal model (for animation setup)
+     */
+    getSkeletalModel(): THREE.Object3D | null;
+    /**
+     * Get the asset path being rendered
+     */
+    getAssetPath(): string;
+    /**
+     * Enable or disable visibility
+     */
+    setVisible(visible: boolean): void;
+    /**
+     * Get visibility state
+     */
+    isVisible(): boolean;
+    protected onCleanup(): void;
+    onEnabled(): void;
+    onDisabled(): void;
+}
+
+/**
+ * Per-instance data stored in a batch
+ */
+interface InstanceData {
+    id: string;
+    gameObject: GameObject;
+    matrix: THREE.Matrix4;
+    isActive: boolean;
+    isDynamic: boolean;
+    isDirty: boolean;
+}
+/**
+ * A batch of instances sharing the same geometry and material
+ */
+interface InstanceBatch {
+    batchKey: string;
+    instancedMesh: THREE.InstancedMesh;
+    dynamicInstances: InstanceData[];
+    staticInstances: InstanceData[];
+    instanceMap: Map<string, InstanceData>;
+    maxInstances: number;
+    geometry: THREE.BufferGeometry;
+    material: THREE.Material;
+    needsRebuild: boolean;
+    hasStaticDirty: boolean;
+}
+/**
+ * Statistics for debugging
+ */
+interface InstanceStats {
+    batchKeys: string[];
+    totalInstances: number;
+    batchCount: number;
+    instancesPerBatch: Map<string, number>;
+}
+/**
+ * Singleton manager for GPU-instanced meshes.
+ *
+ * This is a generic instancing system that works with any geometry + material combination.
+ * Games provide the geometry and material when creating a batch, and the manager handles
+ * the THREE.InstancedMesh creation and per-frame matrix updates.
+ *
+ * Performance optimizations:
+ * - Reuses temporary Vector3/Quaternion/Matrix4 objects (no per-frame allocations)
+ * - Uses Map for O(1) instance lookups
+ * - Only updates GPU when batch is marked dirty
+ * - Uses instancedMesh.count instead of writing zero-matrices
+ *
+ * Usage pattern:
+ * ```typescript
+ * // 1. Initialize (once, during game setup)
+ * InstancedMeshManager.getInstance().initialize(scene)
+ *
+ * // 2. Register a batch (once per unique mesh type)
+ * manager.getOrCreateBatch("burger", burgerGeometry, burgerMaterial)
+ *
+ * // 3. Add instances (via InstancedRenderer component or directly)
+ * const instanceId = manager.addInstance("burger", gameObject)
+ *
+ * // 4. Update every frame
+ * manager.updateAllBatches()
+ * ```
+ */
+declare class InstancedMeshManager {
+    private static _instance;
+    private scene;
+    private batches;
+    private isInitialized;
+    private static readonly INITIAL_CAPACITY;
+    private static readonly GROWTH_FACTOR;
+    private readonly _tempPosition;
+    private readonly _tempQuaternion;
+    private readonly _tempScale;
+    private constructor();
+    /**
+     * Get the singleton instance
+     */
+    static getInstance(): InstancedMeshManager;
+    /**
+     * Initialize the manager with a scene reference.
+     * Must be called before creating batches.
+     * @param scene The THREE.Scene to add InstancedMesh objects to
+     */
+    initialize(scene: THREE.Scene): void;
+    /**
+     * Check if the manager is initialized
+     */
+    isReady(): boolean;
+    /**
+     * Get or create a batch for a given key.
+     * If the batch already exists, returns it (geometry/material params are ignored).
+     * If not, creates a new batch with the provided geometry and material.
+     *
+     * @param batchKey Unique identifier for this batch (e.g., "burger", "tree_pine")
+     * @param geometry BufferGeometry to use for all instances
+     * @param material Material to use for all instances
+     * @param castShadow Whether instances cast shadows (default: false)
+     * @param receiveShadow Whether instances receive shadows (default: false)
+     * @param initialCapacity Starting capacity (will grow automatically). Default: 16
+     * @returns The batch, or null if manager not initialized
+     */
+    getOrCreateBatch(batchKey: string, geometry: THREE.BufferGeometry, material: THREE.Material, castShadow?: boolean, receiveShadow?: boolean, initialCapacity?: number): InstanceBatch | null;
+    /**
+     * Create a batch automatically from a GameObject's mesh.
+     * Extracts geometry and material from the first Mesh found in the GameObject.
+     */
+    getOrCreateBatchFromGameObject(batchKey: string, gameObject: GameObject, castShadow?: boolean, receiveShadow?: boolean, initialCapacity?: number): InstanceBatch | null;
+    /**
+     * Round up to the next power of 2
+     */
+    private nextPowerOf2;
+    /**
+     * Resize a batch to a new capacity (must be larger than current)
+     */
+    private resizeBatch;
+    /**
+     * Check if a batch exists for the given key
+     */
+    hasBatch(batchKey: string): boolean;
+    /**
+     * Get a batch by key (without creating it)
+     */
+    getBatch(batchKey: string): InstanceBatch | null;
+    /**
+     * Get total instance count for a batch
+     */
+    private getTotalInstanceCount;
+    /**
+     * Options for adding an instance
+     */
+    static readonly AddInstanceOptions: {
+        isDynamic: boolean;
+        castShadow: boolean;
+        receiveShadow: boolean;
+        initialCapacity: number | undefined;
+    };
+    /**
+     * Add an instance to a batch.
+     * If no batch exists, creates one automatically from the GameObject's mesh.
+     * If batch is full, automatically resizes to accommodate more instances.
+     *
+     * @param batchKey The batch to add to
+     * @param gameObject The GameObject whose transform will be used
+     * @param options Configuration options (isDynamic, castShadow, receiveShadow, initialCapacity)
+     * @returns Instance ID, or null if failed
+     */
+    addInstance(batchKey: string, gameObject: GameObject, options?: {
+        isDynamic?: boolean;
+        castShadow?: boolean;
+        receiveShadow?: boolean;
+        initialCapacity?: number;
+    }): string | null;
+    /**
+     * Remove an instance from a batch
+     * @param batchKey The batch to remove from
+     * @param instanceId The instance ID to remove
+     */
+    removeInstance(batchKey: string, instanceId: string): void;
+    /**
+     * Set the visibility of a specific instance
+     * @param batchKey The batch containing the instance
+     * @param instanceId The instance ID
+     * @param visible Whether the instance should be visible
+     */
+    setInstanceVisible(batchKey: string, instanceId: string, visible: boolean): void;
+    /**
+     * Get the visibility of a specific instance
+     */
+    getInstanceVisible(batchKey: string, instanceId: string): boolean;
+    /**
+     * Mark a static instance as dirty (needs matrix update next frame).
+     * Call this when a static instance's transform changes.
+     * No-op for dynamic instances (they update every frame anyway).
+     */
+    markInstanceDirty(batchKey: string, instanceId: string): void;
+    /**
+     * Set whether an instance is dynamic (updates every frame) or static (only when dirty).
+     * Use this when an item transitions between moving and stationary states.
+     */
+    setInstanceDynamic(batchKey: string, instanceId: string, isDynamic: boolean): void;
+    /**
+     * Update the matrix for a single instance from its GameObject.
+     * Uses reusable temp objects to avoid per-frame allocations.
+     */
+    private updateInstanceMatrix;
+    /**
+     * Update a single batch - sync matrices and upload to GPU.
+     * Optimized to only update what's necessary:
+     * - Dynamic instances: always update matrix
+     * - Static instances: only update if marked dirty
+     * - GPU upload: only if anything changed
+     */
+    private updateBatch;
+    /**
+     * Update all batches - call this every frame.
+     * Optimized to skip batches with no changes.
+     */
+    updateAllBatches(): void;
+    /**
+     * Get statistics for debugging
+     */
+    getStats(): InstanceStats;
+    /**
+     * Print a debug report to console
+     */
+    debugReport(): void;
+    /**
+     * Remove a batch entirely
+     */
+    removeBatch(batchKey: string): void;
+    /**
+     * Dispose of all batches and reset the manager
+     */
+    dispose(): void;
+    /**
+     * Reset the singleton (for testing)
+     */
+    static reset(): void;
+}
+
+/**
+ * Options for InstancedRenderer
+ */
+interface InstancedRendererOptions {
+    /** If true (default), matrix updates every frame. If false, only updates when markDirty() is called. */
+    isDynamic?: boolean;
+    /** Whether instances cast shadows (default: false). Only used if batch is auto-created. */
+    castShadow?: boolean;
+    /** Whether instances receive shadows (default: false). Only used if batch is auto-created. */
+    receiveShadow?: boolean;
+    /** Initial batch capacity (default: 16, grows automatically). Only used if batch is auto-created. */
+    initialCapacity?: number;
+}
+/**
+ * Component for rendering objects using GPU instancing.
+ *
+ * Transform is controlled by the GameObject - the manager syncs matrices every frame.
+ * If no batch exists for the key, one is created automatically from the GameObject's mesh.
+ *
+ * Performance modes:
+ * - Dynamic (default): Matrix updates every frame. Use for moving objects.
+ * - Static: Matrix only updates when markDirty() is called. Use for stationary objects.
+ *
+ * Usage:
+ * ```typescript
+ * // Simple - batch auto-creates from GameObject's mesh
+ * gameObject.addComponent(new InstancedRenderer("burger"))
+ *
+ * // With options
+ * gameObject.addComponent(new InstancedRenderer("burger", {
+ *   isDynamic: false,
+ *   castShadow: true
+ * }))
+ *
+ * // For stationary objects, switch to static mode
+ * renderer.setDynamic(false)
+ *
+ * // When a static object moves, mark it dirty
+ * renderer.markDirty()
+ * ```
+ *
+ * Key differences from mesh-based renderers (ObjRenderer, etc.):
+ * - No getMesh() - instances don't have their own THREE.Object3D
+ * - No getBounds() - can query the batch geometry if needed
+ * - All instances share the same geometry and material
+ */
+declare class InstancedRenderer extends Component {
+    private readonly batchKey;
+    private readonly options;
+    private instanceId;
+    /**
+     * Create an InstancedRenderer
+     * @param batchKey The batch key to register with. If no batch exists, one is auto-created.
+     * @param options Configuration options (or just pass `true`/`false` for isDynamic)
+     */
+    constructor(batchKey: string, options?: InstancedRendererOptions | boolean);
+    /**
+     * Register with the batch when the component is created.
+     * If no batch exists, one will be created automatically from this GameObject's mesh.
+     */
+    protected onCreate(): void;
+    /**
+     * Set the visibility of this instance
+     */
+    setVisible(visible: boolean): void;
+    /**
+     * Get the visibility of this instance
+     */
+    getVisible(): boolean;
+    /**
+     * Show the instance (convenience method)
+     */
+    show(): void;
+    /**
+     * Hide the instance (convenience method)
+     */
+    hide(): void;
+    /**
+     * Get the batch key this renderer is registered with
+     */
+    getBatchKey(): string;
+    /**
+     * Check if this renderer is successfully registered with a batch
+     */
+    isRegistered(): boolean;
+    /**
+     * Get the instance ID (for debugging)
+     */
+    getInstanceId(): string | null;
+    /**
+     * Mark this instance as needing a matrix update.
+     * Only relevant for static instances - dynamic instances update every frame anyway.
+     * Call this when the transform of a static instance changes.
+     */
+    markDirty(): void;
+    /**
+     * Set whether this instance is dynamic (updates every frame) or static (only when marked dirty).
+     * Use this to optimize performance when items transition between moving and stationary states.
+     * @param isDynamic If true, updates every frame. If false, only updates when markDirty() is called.
+     */
+    setDynamic(isDynamic: boolean): void;
+    /**
+     * Called when the GameObject becomes enabled
+     */
+    onEnabled(): void;
+    /**
+     * Called when the GameObject becomes disabled
+     */
+    onDisabled(): void;
+    /**
+     * Unregister from the batch when the component is cleaned up
+     */
+    protected onCleanup(): void;
+}
+
+interface StowMeshJSON extends ComponentJSON {
+    type: "stow_mesh";
+    mesh: {
+        pack: string;
+        assetId: string;
+    };
+    castShadow?: boolean;
+    receiveShadow?: boolean;
+}
+/**
+ * MeshRenderer - Component for rendering a mesh from StowKitSystem.
+ *
+ * This is a non-instanced renderer - each instance is a separate draw call.
+ * Use InstancedRenderer for many instances of the same mesh (better performance).
+ *
+ * Usage:
+ * ```typescript
+ * const env = new GameObject("Environment")
+ * env.addComponent(new MeshRenderer("restaurant_display_common"))
+ * ```
+ */
+declare class MeshRenderer extends Component {
+    static fromPrefabJSON(json: StowMeshJSON, _node: PrefabNode): MeshRenderer;
+    private mesh;
+    private readonly meshName;
+    private readonly castShadow;
+    private readonly receiveShadow;
+    private _isStatic;
+    private isMeshLoaded;
+    private materialOverride;
+    /**
+     * @param meshName The name of the mesh in the StowKit pack
+     * @param castShadow Whether meshes should cast shadows (default: true)
+     * @param receiveShadow Whether meshes should receive shadows (default: true)
+     * @param isStatic Whether this mesh is static (default: false). Static meshes have matrixAutoUpdate disabled for better performance.
+     * @param materialOverride Optional material to use instead of the default StowKit material
+     */
+    constructor(meshName: string, castShadow?: boolean, receiveShadow?: boolean, isStatic?: boolean, materialOverride?: THREE.Material | null);
+    protected onCreate(): void;
+    update(_deltaTime: number): void;
+    private addMesh;
+    /**
+     * Apply the material override to all meshes
+     */
+    private applyMaterialOverride;
+    /**
+     * Set a material override for all meshes in this renderer.
+     * Call this after the mesh is loaded, or pass it in the constructor.
+     */
+    setMaterial(material: THREE.Material): void;
+    /**
+     * Check if this mesh is currently static (no automatic matrix updates)
+     */
+    get isStatic(): boolean;
+    /**
+     * Set whether this mesh is static (no automatic matrix updates).
+     * Static meshes save CPU by not recalculating transforms every frame.
+     * Call forceMatrixUpdate() after moving a static mesh.
+     */
+    setStatic(isStatic: boolean): void;
+    /**
+     * Force a one-time matrix update. Call this after moving a static mesh.
+     * Does not change the static/dynamic state.
+     */
+    forceMatrixUpdate(): void;
+    /**
+     * Get the mesh group (null if not yet loaded)
+     */
+    getMesh(): THREE.Group | null;
+    /**
+     * Get the name of the mesh this component is managing
+     */
+    getMeshName(): string;
+    /**
+     * Check if the mesh was successfully loaded
+     */
+    isLoaded(): boolean;
+    /**
+     * Set the visibility of the mesh
+     */
+    setVisible(visible: boolean): void;
+    /**
+     * Get bounds of the mesh (useful for physics)
+     */
+    getBounds(): THREE.Vector3 | null;
+    /**
+     * Cleanup - remove mesh from scene and dispose of resources
+     */
+    protected onCleanup(): void;
+}
+
+export { AssetManager, Component, ComponentUpdater, GameObject, InstancedMeshManager, InstancedRenderer, type InstancedRendererOptions, InteractionZone, type InteractionZoneOptions, MeshRenderer, MovementController, PlayerControllerThree, SkeletalRenderer, SkeletonCache, VenusGame, type VenusGameConfig, type VirtualJoystickOptions, VirtualJoystickThree };