@needle-tools/engine 4.11.5 → 4.12.0-beta.1

package/src/engine-components/export/usdz/extensions/behavior/BehaviourComponents.ts

@@ -31,6 +31,8 @@ function ensureRaycaster(obj: GameObject) {
 }
 
 /**
+ * Make the object move to the target object's transform when clicked.
+ * @summary Moves an object to a target transform upon click
  * @category Everywhere Actions
  * @group Components
  */
@@ -176,6 +178,8 @@ export class ChangeTransformOnClick extends Behaviour implements IPointerClickHa
 }
 
 /**
+ * Change the material of objects when clicked.
+ * @summary Changes the material of objects when clicked
  * @category Everywhere Actions
  * @group Components
  */
@@ -366,6 +370,8 @@ export class ChangeMaterialOnClick extends Behaviour implements IPointerClickHan
 }
 
 /**
+ * Set the active state of an object when clicked.
+ * @summary Sets the active state of an object when clicked
  * @category Everywhere Actions
  * @group Components
  */
@@ -604,6 +610,8 @@ export class SetActiveOnClick extends Behaviour implements IPointerClickHandler,
 }
 
 /**
+ * Hides the object on scene start.
+ * @summary Hides the object on scene start
  * @category Everywhere Actions
  * @group Components
  */
@@ -651,6 +659,8 @@ export class HideOnStart extends Behaviour implements UsdzBehaviour {
 }
 
 /**
+ * Emphasize the target object when clicked.
+ * @summary Emphasizes the target object when clicked
  * @category Everywhere Actions
  * @group Components
  */
@@ -683,6 +693,8 @@ export class EmphasizeOnClick extends Behaviour implements UsdzBehaviour {
 }
 
 /**
+ * Plays an audio clip when clicked.
+ * @summary Plays an audio clip when clicked
  * @category Everywhere Actions
  * @group Components
  */
@@ -808,6 +820,8 @@ export class PlayAudioOnClick extends Behaviour implements IPointerClickHandler,
 }
 
 /**
+ * Plays an animation when clicked.
+ * @summary Plays an animation when clicked
  * @category Everywhere Actions
  * @group Components
  */
@@ -1216,6 +1230,8 @@ export class PreliminaryTrigger extends Behaviour {
 }
 
 /**
+ * Hides or shows the object when clicked.
+ * @summary Hides or shows the object when clicked
  * @category Everywhere Actions
  * @group Components
  */
@@ -1241,6 +1257,8 @@ export class VisibilityAction extends PreliminaryAction {
 }
 
 /**
+ * Triggers an action when the object is tapped/clicked.
+ * @summary Triggers an action when the object is tapped/clicked
  * @category Everywhere Actions
  * @group Components
  */

package/src/engine-components/particlesystem/ParticleSystem.ts

@@ -692,6 +692,7 @@ class ParticlesEmissionState implements EmissionState {
  * 
  * Needle Engine uses [three.quarks](https://github.com/Alchemist0823/three.quarks) under the hood to handle particles.
  * 
+ * @summary Handles the motion and rendering of many individual particles
  * @category Rendering
  * @group Components
  */

package/src/engine-components/physics/Attractor.ts

@@ -14,6 +14,9 @@ import { Rigidbody } from "../RigidBody.js";
  * attractor.strength = 5; // positive value to attract
  * attractor.radius = 10; // only attract within 10 units
  * attractor.targets.push(rigidbody); // add the Rigidbody to be attracted
+ * @summary Attract Rigidbodies towards the position of this component
+ * @category Physics
+ * @group Components
  */
 export class Attractor extends Behaviour {
 

package/src/engine-components/postprocessing/Effects/BloomEffect.ts

@@ -19,6 +19,7 @@ import { registerCustomEffectType } from "../VolumeProfile.js";
  * volume.add(bloom);
  * ```
  * 
+ * @summary Bloom Post-Processing Effect
  * @category Effects
  * @group Components
  */

package/src/engine-components/postprocessing/Effects/ChromaticAberration.ts

@@ -7,6 +7,10 @@ import { VolumeParameter } from "../VolumeParameter.js";
 import { registerCustomEffectType, VolumeProfile } from "../VolumeProfile.js";
 
 /**
+ * Chromatic Aberration effect simulates the color fringing effect seen in real-world cameras.  
+ * It offsets the red, green, and blue color channels to create a distorted, colorful edge around objects.  
+ * This effect can enhance the visual appeal of scenes by adding a subtle or pronounced chromatic distortion.
+ * @summary Chromatic Aberration Post-Processing Effect
  * @category Effects
  * @group Components
  */

package/src/engine-components/postprocessing/Effects/ColorAdjustments.ts

@@ -8,6 +8,9 @@ import { registerCustomEffectType } from "../VolumeProfile.js";
 import { ToneMappingEffect } from "./Tonemapping.js";
 
 /**
+ * Color Adjustments effect allows you to modify the overall color properties of the rendered scene, including post-exposure, contrast, hue shift, and saturation.  
+ * These adjustments can be used to enhance the visual aesthetics of the scene or to achieve specific artistic effects.
+ * @summary Color Adjustments Post-Processing Effect
  * @category Effects
  * @group Components
  */

package/src/engine-components/postprocessing/Effects/DepthOfField.ts

@@ -17,6 +17,10 @@ export enum DepthOfFieldMode {
 const debug = getParam("debugpost");
 
 /**
+ * Depth of Field effect simulates the focusing behavior of real-world cameras by blurring objects that are outside the focal plane.  
+ * This effect enhances the sense of depth in a scene by mimicking how cameras focus on subjects at varying distances, creating a more immersive visual experience.  
+ * It can be adjusted to achieve different artistic effects, from subtle background blurring to pronounced bokeh effects.
+ * @summary Depth of Field Post-Processing Effect
  * @category Effects
  * @group Components
  */

package/src/engine-components/postprocessing/Effects/EffectWrapper.ts

@@ -3,6 +3,7 @@ import type { Effect } from "postprocessing";
 import { EffectProviderResult, PostProcessingEffect } from "../PostProcessingEffect.js";
 
 /**
+ *
  * @category Effects
  * @group Components
  */

package/src/engine-components/postprocessing/Effects/Pixelation.ts

@@ -7,6 +7,9 @@ import { VolumeParameter } from "../VolumeParameter.js";
 import { registerCustomEffectType } from "../VolumeProfile.js";
 
 /**
+ * Pixelation effect simulates a pixelated look by enlarging pixels in the rendered scene.  
+ * This effect can be used to achieve a retro or stylized visual aesthetic, reminiscent of early video games or low-resolution graphics.
+ * @summary Pixelation Post-Processing Effect
  * @category Effects
  * @group Components
  */

package/src/engine-components/postprocessing/Effects/ScreenspaceAmbientOcclusionN8.ts

@@ -23,6 +23,10 @@ export enum ScreenSpaceAmbientOcclusionN8QualityMode {
 }
 
 /** Screen Space Ambient Occlusion (SSAO) effect.  
+ * Ambient Occlusion is a shading method used to calculate how exposed each point in a scene is to ambient lighting.  
+ * The effect enhances the depth and realism of 3D scenes by simulating the soft shadows that occur in crevices, corners, and areas where objects are close to each other.  
+ * This implementation uses the N8AO library to provide high-quality SSAO with various quality settings.
+ * @summary Screen Space Ambient Occlusion (SSAO) Post-Processing Effect
  * @category Effects
  * @group Components
  * @link [N8AO documentation](https://github.com/N8python/n8ao)

package/src/engine-components/postprocessing/Effects/Sharpening.ts

@@ -14,6 +14,10 @@ import { PostProcessingEffectOrder } from "../utils.js";
 // }
 
 /**
+ * Sharpening effect enhances the details and edges in the rendered scene by increasing the contrast between adjacent pixels.
+ * This effect can make textures and fine details appear clearer and more defined, improving the overall visual quality of the scene.  
+ * It is particularly useful in scenes where details may be lost due to blurriness or low resolution.
+ * @summary Sharpening Post-Processing Effect
  * @category Effects
  * @group Components
  */

package/src/engine-components/postprocessing/Effects/TiltShiftEffect.ts

@@ -5,6 +5,10 @@ import { VolumeParameter } from "../VolumeParameter.js";
 import { registerCustomEffectType } from "../VolumeProfile.js";
 
 /**
+ * Tilt Shift effect simulates a miniature scene by applying a selective focus blur to the rendered image.  
+ * This effect creates a shallow depth of field, making real-world scenes appear as if they are small-scale models.  
+ * It is often used in photography and cinematography to draw attention to specific areas of the scene while blurring out the rest.
+ * @summary Tilt Shift Post-Processing Effect
  * @category Effects
  * @group Components
  */

package/src/engine-components/postprocessing/Effects/Tonemapping.ts

@@ -14,6 +14,10 @@ const debug = getParam("debugpost");
 
 
 /**
+ * Tonemapping effect adjusts the brightness and contrast of the rendered scene to map high dynamic range (HDR) colors to a displayable range.  
+ * This effect is essential for achieving realistic lighting and color representation in 3D scenes, as it helps to preserve details in both bright and dark areas.  
+ * Various tonemapping algorithms can be applied to achieve different visual styles and effects.
+ * @summary Tonemapping Post-Processing Effect
  * @category Effects
  * @group Components
  */

package/src/engine-components/postprocessing/Effects/Vignette.ts

@@ -7,6 +7,10 @@ import { VolumeParameter } from "../VolumeParameter.js";
 import { registerCustomEffectType } from "../VolumeProfile.js";
 
 /**
+ * Vignette effect darkens the edges of the rendered scene to draw attention to the center.  
+ * This effect simulates the natural vignetting that occurs in photography and cinematography, where the corners of an image are darker than the center.  
+ * It can be used to enhance the visual focus on the main subject of the scene and create a more immersive viewing experience.
+ * @summary Vignette Post-Processing Effect
  * @category Effects
  * @group Components
  */

package/src/engine-components/postprocessing/Volume.ts

@@ -41,6 +41,7 @@ const debug = getParam("debugpost");
  * volume.addEffect(pixelation);
  * ```
  * 
+ * @summary Manage Post-Processing Effects
  * @category Rendering
  * @category Effects
  * @group Components

package/src/engine-components/splines/Spline.ts

@@ -37,6 +37,7 @@ export class SplineData {
  * 
  * You can create a SplineContainer from an array of points using the static method 'createFromPoints'.
  * 
+ * @summary Holds spline data and generates a spline curve.
  * @category Splines
  * @group Components
  */

package/src/engine-components/splines/SplineWalker.ts

@@ -12,6 +12,7 @@ import { SplineContainer } from "./Spline.js";
  * 
  * - Example http://samples.needle.tools/splines
  * 
+ * @summary Moves an object along a spline
  * @category Splines
  * @group Components
  */

package/src/engine-components/timeline/PlayableDirector.ts

@@ -56,6 +56,7 @@ export type CreateTrackFunction = (director: PlayableDirector, track: Models.Tra
  * The PlayableDirector component is the main component to control timelines in needle engine.
  * It is used to play, pause, stop and evaluate timelines.  
  * Assign a TimelineAsset to the `playableAsset` property to start playing a timeline.
+ * @summary Controls and plays TimelineAssets
  * @category Animation and Sequencing
  * @group Components
  */

package/src/engine-components/timeline/SignalAsset.ts

@@ -29,6 +29,7 @@ export class SignalReceiverEvent {
 /** SignalReceiver is a component that listens for signals and invokes a reaction when a signal is received. 
  * Signals can be added to a signal track on a {@link PlayableDirector}
  * 
+ * @summary Receives signals and invokes reactions
  * @category Sequencing and Timelines
  * @group Components
  */

package/src/engine-components/ui/Button.ts

@@ -61,6 +61,10 @@ class AnimationTriggers {
 }
 
 /**
+ * Button is a UI component that can be clicked by the user to perform an action.  
+ * It supports different visual states such as normal, highlighted, pressed, and disabled.  
+ * You can customize the button's appearance using colors or animations for each state.
+ * @summary UI Button that can be clicked to perform actions
  * @category User Interface
  * @group Components
  */

package/src/engine-components/ui/Canvas.ts

@@ -25,6 +25,11 @@ export enum RenderMode {
 const debugLayout = getParam("debuguilayout");
 
 /**
+ * Canvas is the root component for all UI elements in a scene.  
+ * It defines the area where UI elements are rendered and manages their layout and rendering settings.  
+ * Canvases can be set to render in world space or screen space (overlay or camera).  
+ * Multiple canvases can exist in a scene, each with its own settings and hierarchy of UI elements.
+ * @summary Root component for UI elements, managing layout and rendering settings
  * @category User Interface
  * @group Components
  */

package/src/engine-components/ui/CanvasGroup.ts

@@ -7,6 +7,10 @@ import { type ICanvasGroup, type IHasAlphaFactor } from "./Interfaces.js";
 
 
 /**
+ * CanvasGroup is a UI component that allows you to control the transparency and interactivity of a group of UI elements.  
+ * By adjusting the alpha property, you can fade in or out all child UI elements simultaneously.  
+ * The interactable and blocksRaycasts properties let you enable or disable user interaction for the entire group.
+ * @summary Group UI elements to control transparency and interactivity
  * @category User Interface
  * @group Components
  */

package/src/engine-components/ui/EventSystem.ts

@@ -36,6 +36,8 @@ onInitialized((ctx) => {
 })
 
 /**
+ * The EventSystem is responsible for managing and dispatching input events to UI components within the scene.
+ * @summary Manages and dispatches input events to UI components
  * @category User Interface
  * @group Components
  */

package/src/engine-components/ui/Image.ts

@@ -12,6 +12,10 @@ class Sprite {
 }
 
 /**
+ * Image is a UI component that displays a sprite (2D image) in the user interface.  
+ * You can set the image property to assign a texture to be displayed.  
+ * The sprite can be customized with various properties such as color tinting and pixel density.
+ * @summary Display a 2D image in the UI
  * @category User Interface
  * @group Components
  */

package/src/engine-components/ui/InputField.ts

@@ -10,6 +10,10 @@ import { tryGetUIComponent } from "./Utils.js";
 const debug = getParam("debuginputfield");
 
 /**
+ * InputField is a UI component that allows users to enter and edit text.  
+ * It provides a text input area where users can type, delete, and modify text.  
+ * The InputField supports placeholder text, events for value changes, and end edit actions.
+ * @summary Text field for user input
  * @category User Interface
  * @group Components
  */

package/src/engine-components/ui/Outline.ts

@@ -4,6 +4,13 @@ import { serializable } from "../../engine/engine_serialization.js";
 import { RGBAColor } from "../../engine/js-extensions/index.js";
 import { Behaviour } from "../Component.js";
 
+/**
+ * Outline is a UI component that adds an outline effect to UI elements.  
+ * You can customize the outline color and distance to create a visual border around the UI element.
+ * @summary Add an outline effect to UI elements
+ * @category User Interface
+ * @group Components
+ */
 export class Outline extends Behaviour {
 
     @serializable(RGBAColor)

package/src/engine-components/ui/SpatialHtml.ts

@@ -6,6 +6,13 @@ import { serializable } from '../../engine/engine_serialization.js';
 import { getWorldRotation, setWorldRotationXYZ } from '../../engine/engine_three_utils.js';
 import { Behaviour } from '../Component.js';
 
+/**
+ * SpatialHtml is a component that allows you to integrate HTML elements into a 3D scene.  
+ * By specifying the ID of an existing HTML element, you can render it as a 3D object within the scene.
+ * @summary Render HTML elements as 3D objects in the scene
+ * @category User Interface
+ * @group Components
+ */
 export class SpatialHtml extends Behaviour {
 
     @serializable()

package/src/engine-components/ui/Text.ts

@@ -40,6 +40,9 @@ export enum FontStyle {
 }
 
 /**
+ * Text is a UI component that displays text in the user interface.
+ * 
+ * @summary Display text in the UI
  * @category User Interface
  * @group Components
  */

package/src/engine-components/utils/LookAt.ts

@@ -12,6 +12,7 @@ import { Behaviour } from "../Component.js";
  * LookAt behaviour makes the object look at a target object or the camera.  
  * It can also invert the forward direction and keep the up direction.
  * 
+ * @summary Makes the object look at a target object or the camera
  * @category Interactivity, Everywhere Actions
  * @group Components
  */

package/src/engine-components/web/Clickthrough.ts

@@ -32,7 +32,7 @@ onStart(ctx => {
  * - Alternatively, add the `clickthrough` attribute to the `<needle-engine>` HTML element (e.g. `<needle-engine clickthrough></needle-engine>`).
  * 
  * - Example https://stackblitz.com/~/github.com/needle-engine/sample-3d-over-html
- * 
+ * @summary Allows pointer events to "click through" the 3D canvas to HTML elements behind it.
  * @category Web
  * @group Components
  * @component

package/src/engine-components/web/CursorFollow.ts

@@ -14,12 +14,16 @@ const debug = getParam("debugcursor");
  * 
  * - Example: [Look At Cursor sample](https://engine.needle.tools/samples/look-at-cursor-interactive-3d-header/). This sample combines the CursorFollow component with a LookAt component to create an interactive 3D header that looks at the cursor.
  * 
+ * @summary Makes the object follow the cursor position on screen
  * @category Web
  * @group Components
  * @component
  */
 export class CursorFollow extends Behaviour {
 
+    // testing this for compilation
+    static readonly NAME = "CursorFollow";
+
     /**
      * Damping for the movement, set to 0 for instant movement
      * @default 0

package/src/engine-components/web/HoverAnimation.ts

@@ -13,6 +13,7 @@ import { Behaviour } from "../Component.js";
  * 
  * By default, a simple scale-up animation is used. You can customize the hover and idle animations by providing your own animation clips.
  * 
+ * @summary Hover Animation on Pointer Enter/Exit
  * @category Web
  * @group Components
  */

package/src/engine-components/web/ScrollFollow.ts

@@ -34,6 +34,7 @@ type ScrollFollowEvent = {
 
 /**
  * The ScrollFollow component allows you to link the scroll position of the page (or a specific element) to one or more target objects.  
+ 
  * This can be used to create scroll-based animations, audio playback, or other effects. For example you can link the scroll position to a timeline (PlayableDirector) to create scroll-based storytelling effects or to an Animator component to change the animation state based on scroll.
  * 
  * Assign {@link target} objects to the component to have them updated based on the current scroll position (check the 'target' property for supported types).
@@ -60,6 +61,7 @@ type ScrollFollowEvent = {
  *   <div data-timeline-marker="1.0">End of Timeline</div>
  * ```
  * 
+ * @summary Links scroll position to target objects
  * @category Web
  * @group Components
  * @component

package/src/engine-components/web/ViewBox.ts

@@ -31,6 +31,7 @@ export type ViewBoxMode = "continuous" | "once";
   scene.add(viewBox);
  * ```
   
+ * @summary Automatically fits a box area into the camera view
  * @category Camera
  * @group Components
  * @component

package/src/engine-components/webxr/Avatar.ts

@@ -18,6 +18,11 @@ const debug = getParam("debugwebxr");
 const flipForwardQuaternion = new Quaternion().setFromAxisAngle(new Vector3(0, 1, 0), Math.PI);
 
 /**
+ * Avatar component to setup a WebXR avatar with head and hand objects.  
+ * 
+ * The avatar will automatically synchronize the head and hand objects with the XR rig when entering an XR session.
+ * 
+ * @summary WebXR Avatar component for head and hands synchronization
  * @category XR
  * @category Networking
  * @group Components

package/src/engine-components/webxr/WebARCameraBackground.ts

@@ -26,6 +26,7 @@ const debug = getParam("debugarcamera");
  * 
  * - Example: https://samples.needle.tools/ar-camera-background
  * 
+ * @summary Displays the camera feed as background in WebAR sessions
  * @category XR
  * @group Components
  */

package/src/engine-components/webxr/WebARSessionRoot.ts

@@ -29,6 +29,7 @@ const invertForwardMatrix = new Matrix4().makeRotationY(Math.PI);
  * });
  * ```
  * 
+ * @summary Root object for WebAR sessions, managing scene placement and user scaling in AR.
  * @category XR
  * @group Components
  */

package/src/engine-components/webxr/WebXR.ts

@@ -51,7 +51,7 @@ const debugQuicklook = getParam("debugusdz");
  * });
  * ```
  * 
- * 
+ * @summary WebXR Component for VR and AR support
  * @category XR
  * @group Components
  */
@@ -331,6 +331,10 @@ export class WebXR extends Behaviour {
             console.warn(`WebXR: another WebXR component is already active (${WebXR.activeWebXRComponent?.name}). This is ignored: ${this.name}`);
             return;
         }
+        if (this.activeAndEnabled === false || this.destroyed) {
+            console.debug("[WebXR] onBeforeXR called on disabled or destroyed component");
+            return;
+        }
         WebXR.activeWebXRComponent = this;
 
         if (_mode == "immersive-ar" && this.useDepthSensing) {

package/src/engine-components/webxr/controllers/XRControllerFollow.ts

@@ -21,6 +21,7 @@ import { Behaviour } from "../../Component.js";
  * });
  * ```
  * 
+ * @summary Makes the object follow a specific XR controller or hand
  * @category XR
  * @group Components
  * */

package/src/engine-components/webxr/controllers/XRControllerModel.ts

@@ -27,6 +27,10 @@ const renderingUpdateTimings = new Array<number>();
  * It automatically loads the appropriate model for the connected controller or hand.  
  * 
  * You can configure if controller models or hand models should be created.
+ * 
+ * @summary Displays controller or hand models in XR
+ * @category XR
+ * @group Components
  */
 export class XRControllerModel extends Behaviour {
 

package/src/engine-components/webxr/controllers/XRControllerMovement.ts

@@ -30,6 +30,7 @@ declare type HitPointObject = Object3D & { material: Material & { opacity: numbe
  * It also visualizes controller rays and hit points in the scene.
  * 
  * 
+ * @summary Move the XR rig using controller input
  * @category XR
  * @group Components
  */

package/src/engine-components-experimental/networking/PlayerSync.ts

@@ -18,7 +18,9 @@ declare type PlayerSyncWithAsset = PlayerSync & Required<Pick<PlayerSync, "asset
 /**
  * This component instantiates an asset for each player that joins a networked room. The asset will be destroyed when the player leaves the room.
  * The asset should have a PlayerState component, and can have other components like SyncedTransform, custom components, etc.
+ * @summary Instantiates and manages player assets in a networked room
  * @category Networking
+ * @group Components
  */
 export class PlayerSync extends Behaviour {
 

package/src/needle-engine.ts

@@ -7,7 +7,7 @@ export * from "./engine-components-experimental/api.js";
 export * from "./engine-schemes/api.js";
 
 // make accessible for external javascript
-import { Context, loadAsset, NeedleXRSession, onAfterRender, onBeforeRender, onClear, onDestroy, onInitialized, onStart, onUpdate, VERSION } from "./engine/api.js";
+import { Context, loadAsset, NeedleXRSession, onAfterRender, onBeforeRender, onClear, onDestroy, onInitialized, onStart, onUpdate, TypeStore, VERSION } from "./engine/api.js";
 const Needle = {
     VERSION: VERSION,
     Context: Context,
@@ -15,6 +15,7 @@ const Needle = {
     assets: {
         loadFromURL: loadAsset,
     },
+    types: TypeStore,
     onStart: onStart,
     onUpdate: onUpdate,
     onBeforeRender: onBeforeRender,
@@ -22,7 +23,8 @@ const Needle = {
     onInitializedContext: onInitialized,
     onDestroyContext: onDestroy,
     onClearContext: onClear,
-};
+} as const;
+
 if (globalThis["Needle"]?.VERSION !== undefined) {
     console.warn(`Needle Engine is already imported: ${globalThis["Needle"].VERSION}`);
 }