@needle-tools/engine
Version:
Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.
337 lines • 16.4 kB
JavaScript
/**
* The Engine Core API is the main entry point for Needle Engine functionality.
* It provides a unified interface for building interactive 3D web experiences
* with features spanning rendering, physics, networking, XR, and more.
*
* ## Quick Start
* ```typescript
* import { Context, Behaviour, serializable } from "@needle-tools/engine";
*
* class MyComponent extends Behaviour {
* @serializable()
* speed: number = 1;
*
* update() {
* this.gameObject.rotateY(this.context.time.deltaTime * this.speed);
* }
* }
* ```
*
* ## Module Categories
*
* ### Context & Application
* The {@link Context} class is the central hub that manages the scene, renderer, camera,
* and all engine systems. Access it via `this.context` in any component.
* - {@link Context} - Main engine context managing scene, renderer, and systems
* - {@link ContextRegistry} - Registry for multiple engine contexts
* - {@link Application} - Application-level utilities and state
*
* ### Components & GameObjects
* Needle Engine uses a component-based architecture similar to Unity.
* Components are attached to three.js Object3D instances (GameObjects).
* - {@link addComponent}, {@link getComponent}, {@link removeComponent} - Component management
* - {@link findObjectOfType}, {@link findObjectsOfType} - Scene queries
* - {@link instantiate}, {@link destroy} - Object lifecycle
* @see {@link https://engine.needle.tools/docs/scripting.html | Scripting Documentation}
*
* ### Asset Loading
* Load glTF/GLB files, textures, and other assets at runtime.
* - {@link loadSync}, {@link parseSync} - Load glTF/GLB assets
* - {@link AssetDatabase} - Asset reference management
* - {@link Addressables} - Addressable asset system
* @see {@link https://engine.needle.tools/docs/addressables.html | Addressables Documentation}
*
* ### Input System
* Unified input handling for mouse, touch, keyboard, and XR controllers.
* Access via `this.context.input` in components.
* - {@link Input} - Unified input manager
* - {@link NEPointerEvent} - Cross-platform pointer events
* - {@link InputEvents} - Event types for input listeners
* @see {@link https://engine.needle.tools/docs/input.html | Input Documentation}
*
* ### Physics & Raycasting
* Rapier-based physics engine with collision detection and raycasting.
* - {@link Physics} - Physics world access and raycasting
* - {@link RaycastOptions} - Configure raycast behavior
* - {@link Collision}, {@link ContactPoint} - Collision data types
* @see {@link https://engine.needle.tools/docs/physics.html | Physics Documentation}
*
* ### Networking
* Real-time multiplayer networking with automatic state synchronization.
* - {@link NetworkConnection} - WebSocket connection management
* - {@link RoomEvents} - Room join/leave events
* - {@link syncField} - Decorator for automatic field synchronization
* - {@link PeerNetworking} - WebRTC peer-to-peer connections
* @see {@link https://engine.needle.tools/docs/networking.html | Networking Documentation}
*
* ### XR (AR/VR)
* WebXR support for augmented and virtual reality experiences.
* - {@link NeedleXRSession} - XR session management
* - {@link NeedleXRController} - XR controller input and tracking
* - {@link XRRig} - XR camera rig configuration
* @see {@link https://engine.needle.tools/docs/xr.html | XR Documentation}
*
* ### Time & Animation
* Frame timing and animation utilities.
* - {@link Time} - Delta time, frame count, time scale
* - {@link AnimationUtils} - Animation playback helpers
* - Coroutines via {@link startCoroutine} for async sequences
*
* ### Debugging & Gizmos
* Visual debugging tools for development.
* - {@link Gizmos} - Draw debug shapes (lines, spheres, boxes)
* - {@link showBalloonMessage}, {@link showBalloonWarning} - On-screen messages
* - {@link isDevEnvironment} - Check if running in development mode
*
* ### Utilities
* Helper functions for common operations.
* - {@link getParam} - URL parameter parsing
* - {@link delay} - Promise-based delay
* - {@link generateQRCode} - QR code generation
* - Math utilities: {@link Mathf}, vector operations
*
* @module Engine Core
* @see {@link https://engine.needle.tools/docs/ | Needle Engine Documentation}
*/
// ============================================================================
// DEBUGGING & DEVELOPMENT
// Debugging utilities, gizmos, and development tools.
// ============================================================================
export * from "./debug/index.js";
// ============================================================================
// ASSET LOADING & MANAGEMENT
// Systems for loading, managing, and referencing assets at runtime.
// ============================================================================
/** Addressable asset system for loading assets by address/label */
export * from "./engine_addressables.js";
/** Animation playback and control utilities */
export { AnimationUtils } from "./engine_animation.js";
/** Application-level state and utilities */
export { Application } from "./engine_application.js";
/** Asset database for managing asset references */
export * from "./engine_assetdatabase.js";
// ============================================================================
// CAMERA & RENDERING
// Camera control, rendering utilities, and visual effects.
// ============================================================================
/** Camera fitting utilities for framing objects */
export * from "./engine_camera.fit.js";
/** Camera controller management and auto-fit configuration */
export { getCameraController, setAutoFitEnabled, setCameraController, useForAutoFit } from "./engine_camera.js";
// ============================================================================
// COMPONENTS & GAMEOBJECTS
// Component-based architecture for building interactive 3D content.
// Functions for adding, removing, and querying components on objects.
// ============================================================================
/**
* Component management functions: addComponent, getComponent, removeComponent, etc.
* @see {@link https://engine.needle.tools/docs/scripting.html | Scripting Documentation}
*/
export * from "./engine_components.js";
/** Internal component lifecycle events and management */
export * from "./engine_components_internal.js";
/** Engine constants and configuration values */
export * from "./engine_constants.js";
// ============================================================================
// CONTEXT & LIFECYCLE
// Core engine context and application lifecycle management.
// ============================================================================
/**
* Main engine context class - the central hub for all engine systems.
* Provides access to scene, renderer, camera, input, physics, networking, and more.
* @see {@link https://engine.needle.tools/docs/scripting.html#context | Context Documentation}
*/
export * from "./engine_context.js";
/** Registry for managing multiple engine contexts */
export * from "./engine_context_registry.js";
/**
* Coroutine system for async sequences in components.
* Use startCoroutine() for frame-based async operations.
*/
export * from "./engine_coroutine.js";
/** Factory functions for creating primitives and objects */
export * from "./engine_create_objects.js";
/** Feature flags for enabling/disabling engine features */
export * from "./engine_feature_flags.js";
/**
* GameObject utilities: instantiate, destroy, find, traverse.
* @see {@link https://engine.needle.tools/docs/scripting.html#finding-objects | Finding Objects}
*/
export * from "./engine_gameobject.js";
/**
* Visual debugging with Gizmos - draw lines, spheres, boxes for debugging.
* @see {@link https://engine.needle.tools/docs/debugging.html | Debugging Documentation}
*/
export { Gizmos } from "./engine_gizmos.js";
/** glTF/GLB loader registration and management */
export * from "./engine_gltf.js";
/** Hot reload support for development */
export * from "./engine_hot_reload.js";
// ============================================================================
// INPUT SYSTEM
// Unified input handling for mouse, touch, keyboard, and XR controllers.
// ============================================================================
/**
* Unified input system supporting mouse, touch, keyboard, and XR controllers.
* Access via this.context.input in components.
* @see {@link https://engine.needle.tools/docs/input.html | Input Documentation}
*/
export * from "./engine_input.js";
// ============================================================================
// INSTANCING & PERFORMANCE
// GPU instancing and performance optimization utilities.
// ============================================================================
/** GPU instancing utilities for rendering many similar objects efficiently */
export { InstancingUtil } from "./engine_instancing.js";
/** License checking utilities */
export { hasCommercialLicense, hasIndieLicense, hasProLicense } from "./engine_license.js";
// ============================================================================
// LIFECYCLE & LOADING
// Component lifecycle hooks and asset loading systems.
// ============================================================================
/** Lifecycle API for registering global callbacks */
export * from "./engine_lifecycle_api.js";
/** Model loader callbacks for customizing load behavior */
export { NeedleEngineModelLoader } from "./engine_loaders.callbacks.js";
/**
* Asset loading functions: loadSync, parseSync for glTF/GLB files.
* @see {@link https://engine.needle.tools/docs/addressables.html | Loading Assets}
*/
export { loadAsset, loadSync, parseSync } from "./engine_loaders.js";
// ============================================================================
// MATERIALS & RENDERING
// Material utilities and rendering helpers.
// ============================================================================
/** MaterialPropertyBlock for efficient material property overrides per-instance */
export { MaterialPropertyBlock } from "./engine_materialpropertyblock.js";
/** Math utilities: Mathf, interpolation, easing functions */
export * from "./engine_math.js";
/** Engine modules registry */
export { MODULES as NEEDLE_ENGINE_MODULES } from "./engine_modules.js";
// ============================================================================
// NETWORKING
// Real-time multiplayer networking with WebSocket and WebRTC support.
// ============================================================================
/**
* Core networking: NetworkConnection, RoomEvents, OwnershipEvent.
* @see {@link https://engine.needle.tools/docs/networking.html | Networking Documentation}
*/
export * from "./engine_networking.js";
/**
* @syncField decorator for automatic field synchronization across clients.
* @see {@link https://engine.needle.tools/docs/networking.html#synced-variables | Synced Variables}
*/
export { syncField } from "./engine_networking_auto.js";
/** Blob/binary data transfer over network */
export * from "./engine_networking_blob.js";
/** File transfer utilities for networking */
export * from "./engine_networking_files.js";
/**
* Network instantiation for spawning synced objects.
* @see {@link https://engine.needle.tools/docs/networking.html#spawning-objects | Spawning Objects}
*/
export * from "./engine_networking_instantiate.js";
/** WebRTC peer-to-peer networking for direct client connections */
export * from "./engine_networking_peer.js";
/** Media streaming utilities (audio/video) */
export * from "./engine_networking_streams.js";
/** Networking type definitions and interfaces */
export * from "./engine_networking_types.js";
/** Networking utility functions */
export * from "./engine_networking_utils.js";
// ============================================================================
// PHYSICS & RAYCASTING
// Rapier-based physics simulation and raycasting.
// ============================================================================
/** Object patching utilities */
export * from "./engine_patcher.js";
/**
* Physics system: raycasting, collision queries, physics world access.
* @see {@link https://engine.needle.tools/docs/physics.html | Physics Documentation}
*/
export * from "./engine_physics.js";
/** Physics type definitions: RaycastOptions, Collision, ContactPoint */
export * from "./engine_physics.types.js";
/** Rapier physics engine integration */
export * from "./engine_physics_rapier.js";
// ============================================================================
// PLAYER & VIEW MANAGEMENT
// Multi-player view management and scene lighting.
// ============================================================================
/** Player view management for multi-user scenarios */
export * from "./engine_playerview.js";
/** PMREM (Prefiltered Mipmapped Radiance Environment Map) loading */
export { loadPMREM } from "./engine_pmrem.js";
/** Scene lighting data and environment configuration */
export * from "./engine_scenelighting.js";
// ============================================================================
// SERIALIZATION
// Component serialization for saving/loading and networking.
// ============================================================================
/**
* Serialization utilities for components and objects.
* @see {@link https://engine.needle.tools/docs/scripting.html#serialization | Serialization Documentation}
*/
export * from "./engine_serialization.js";
// ============================================================================
// UTILITIES & HELPERS
// General-purpose utility functions and helpers.
// ============================================================================
/** Texture utilities and processing */
export * from "./engine_texture.js";
/** Three.js helper utilities: getWorldPosition, getTempVector, etc. */
export * from "./engine_three_utils.js";
/**
* Time class: deltaTime, time, frameCount, timeScale.
* Access via this.context.time in components.
*/
export * from "./engine_time.js";
/** Time-related utility functions */
export * from "./engine_time_utils.js";
/** Core type definitions and interfaces */
export * from "./engine_types.js";
/** Type registration for component discovery */
export { registerType, TypeStore } from "./engine_typestore.js";
/** Decorator utilities: @prefix, @validate */
export { prefix, validate } from "./engine_util_decorator.js";
/** General utilities: getParam, delay, DeviceUtilities, etc. */
export * from "./engine_utils.js";
/** Formatting utilities for strings and numbers */
export * from "./engine_utils_format.js";
/** QR code generation utility */
export { generateQRCode } from "./engine_utils_qrcode.js";
/** Screenshot capture utilities */
export * from "./engine_utils_screenshot.js";
// ============================================================================
// EXTENSIONS & INTEGRATIONS
// glTF extensions and JavaScript object extensions.
// ============================================================================
/** Export utilities and formats */
export * from "./export/index.js";
/** glTF extension implementations (NEEDLE_components, etc.) */
export * from "./extensions/index.js";
/** JavaScript object extensions for three.js objects */
export * from "./js-extensions/index.js";
// ============================================================================
// WEB COMPONENTS
// Custom HTML elements for embedding Needle Engine.
// ============================================================================
/** Web component API utilities */
export * from "./webcomponents/api.js";
/**
* <needle-engine> web component for embedding 3D scenes.
* @see {@link https://engine.needle.tools/docs/html.html | HTML Integration}
*/
export * from "./webcomponents/needle-engine.js";
/** Loading screen and progress indicators */
export * from "./webcomponents/needle-engine.loading.js";
// ============================================================================
// XR (AR/VR)
// WebXR support for augmented and virtual reality experiences.
// ============================================================================
/**
* XR API: NeedleXRSession, NeedleXRController, XRRig.
* @see {@link https://engine.needle.tools/docs/xr.html | XR Documentation}
*/
export * from "./xr/api.js";
//# sourceMappingURL=api.js.map