@needle-tools/engine 4.11.5 → 4.12.0-beta

package/src/engine-components/Skybox.ts

@@ -1,16 +1,14 @@
-import { CompressedCubeTexture, CubeRefractionMapping, CubeTexture, CubeUVReflectionMapping, EquirectangularRefractionMapping, SRGBColorSpace, Texture, TextureLoader } from "three"
-import { EXRLoader } from "three/examples/jsm/loaders/EXRLoader.js";
-import { KTX2Loader } from "three/examples/jsm/loaders/KTX2Loader.js";
-import { RGBELoader } from 'three/examples/jsm/loaders/RGBELoader.js';
+import { CompressedCubeTexture, CubeTexture, CubeUVReflectionMapping, EquirectangularRefractionMapping, Texture } from "three"
 
+import { isDevEnvironment } from "../engine/debug/debug.js";
 import { ContextEvent, ContextRegistry } from "../engine/engine_context_registry.js";
 import { syncField } from "../engine/engine_networking_auto.js";
 import { loadPMREM } from "../engine/engine_pmrem.js";
 import { serializable } from "../engine/engine_serialization_decorator.js";
 import { type IContext } from "../engine/engine_types.js";
-import { addAttributeChangeCallback, getParam, PromiseAllWithErrors, removeAttributeChangeCallback, toSourceId } from "../engine/engine_utils.js";
+import { addAttributeChangeCallback, getParam, removeAttributeChangeCallback, toSourceId } from "../engine/engine_utils.js";
 import { registerObservableAttribute } from "../engine/webcomponents/needle-engine.extras.js";
-import { Camera, ClearFlags } from "./Camera.js";
+import { Camera } from "./Camera.js";
 import { Behaviour, GameObject } from "./Component.js";
 
 const debug = getParam("debugskybox");
@@ -18,6 +16,29 @@ const debug = getParam("debugskybox");
 registerObservableAttribute("background-image");
 registerObservableAttribute("environment-image");
 
+
+type MagicSkyboxName = "studio" | "blurred-skybox" | "quicklook-ar" | "quicklook";
+const MagicSkyboxNames: Record<MagicSkyboxName, { url: string, url_low: string }> = {
+    "studio": {
+        url: "https://cdn.needle.tools/static/skybox/modelviewer-Neutral.pmrem4x4.ktx2?pmrem",
+        url_low: "https://cdn.needle.tools/static/skybox/modelviewer-Neutral-small.pmrem4x4.ktx2?pmrem"
+    },
+    "blurred-skybox": {
+        url: "https://cdn.needle.tools/static/skybox/blurred-skybox.pmrem4x4.ktx2?pmrem",
+        url_low: "https://cdn.needle.tools/static/skybox/blurred-skybox-small.pmrem4x4.ktx2?pmrem"
+    },
+    "quicklook-ar": {
+        url: "https://cdn.needle.tools/static/skybox/QuickLook-ARMode.pmrem4x4.ktx2?pmrem",
+        url_low: "https://cdn.needle.tools/static/skybox/QuickLook-ARMode-small.pmrem4x4.ktx2?pmrem"
+    },
+    "quicklook": {
+        url: "https://cdn.needle.tools/static/skybox/QuickLook-ObjectMode.pmrem4x4.ktx2?pmrem",
+        url_low: "https://cdn.needle.tools/static/skybox/QuickLook-ObjectMode-small.pmrem4x4.ktx2?pmrem"
+    }
+} as const;
+type AnyString = string & { _brand?: never };
+
+
 function createRemoteSkyboxComponent(context: IContext, url: string, skybox: boolean, environment: boolean, attribute: "background-image" | "environment-image") {
 
     // when the user sets the attribute to a color we can not handle it as a skybox url.
@@ -91,8 +112,9 @@ ContextRegistry.registerCallback(ContextEvent.ContextCreationStart, () => {
 });
 
 
+
 /**
- * RemoteSkybox is a component that allows you to set the skybox of a scene from a URL or a local file.  
+ * RemoteSkybox is a component that allows you to set the skybox or environment texture of a scene from a URL, a local file or a static skybox name.  
  * It supports .hdr, .exr, .jpg, .png files.
  * 
  * ### Events
@@ -121,14 +143,20 @@ ContextRegistry.registerCallback(ContextEvent.ContextCreationStart, () => {
  * skybox.setSkybox("https://example.com/skybox.hdr");
  * ```
  * 
+ * @summary Sets the skybox or environment texture of a scene
  * @category Rendering
  * @group Components
  */
 export class RemoteSkybox extends Behaviour {
 
     /**
-     * URL to a remote skybox. This value can also use a magic skybox name. Options are "quicklook", "quicklook-ar", "studio", "blurred-skybox".  
-     * To update the skybox/environment map use `setSkybox(url)`
+     * URL to a remote skybox.   
+     * To update the skybox/environment map use `setSkybox(url)`. 
+     * 
+     * The url can also be set to a magic skybox name.   
+     * Magic name options are: "quicklook", "quicklook-ar", "studio", "blurred-skybox".     
+     * These will resolve to built-in skyboxes hosted on the Needle CDN that are static, optimized for the web and will never change.  
+     * 
      * @example
      * ```ts
      * skybox.url = "https://example.com/skybox.hdr";
@@ -136,7 +164,7 @@ export class RemoteSkybox extends Behaviour {
      */
     @syncField(RemoteSkybox.prototype.urlChangedSyncField)
     @serializable(URL)
-    url?: string;
+    url: MagicSkyboxName | AnyString = "studio";
 
     /**
      * When enabled a user can drop a link to a skybox image on the scene to set the skybox.
@@ -208,7 +236,7 @@ export class RemoteSkybox extends Behaviour {
      * @param name Define name of the file with extension if it isn't apart of the url
      * @returns Whether the skybox was successfully set
      */
-    async setSkybox(url: string | undefined | null, name?: string) {
+    async setSkybox(url: MagicSkyboxName | AnyString | undefined | null, name?: string) {
         if (!this.activeAndEnabled) return false;
 
         url = tryParseMagicSkyboxName(url, this.environment, this.background);
@@ -404,38 +432,22 @@ export class RemoteSkybox extends Behaviour {
 
 
 
-
 function tryParseMagicSkyboxName(str: string | null | undefined, environment: boolean, background: boolean): string | null {
 
     if (str === null || str === undefined) return null;
 
     const useLowRes = environment && !background;
 
-    switch (str.toLowerCase()) {
-        case "studio":
-            if (useLowRes) {
-                return "https://cdn.needle.tools/static/skybox/modelviewer-Neutral-small.pmrem4x4.ktx2?pmrem";
-            }
-            return "https://cdn.needle.tools/static/skybox/modelviewer-Neutral.pmrem4x4.ktx2?pmrem";
-
-        case "blurred-skybox":
-            if (useLowRes) {
-                return "https://cdn.needle.tools/static/skybox/blurred-skybox-small.pmrem4x4.ktx2?pmrem";
-            }
-            return "https://cdn.needle.tools/static/skybox/blurred-skybox.pmrem4x4.ktx2?pmrem";
-        case "quicklook-ar":
-            if (useLowRes) {
-                return "https://cdn.needle.tools/static/skybox/QuickLook-ARMode-small.pmrem4x4.ktx2?pmrem";
-            }
-            return "https://cdn.needle.tools/static/skybox/QuickLook-ARMode.pmrem4x4.ktx2?pmrem";
-        case "quicklook":
-            if (useLowRes) {
-                return "https://cdn.needle.tools/static/skybox/QuickLook-ObjectMode-small.pmrem4x4.ktx2?pmrem";
-            }
-            return "https://cdn.needle.tools/static/skybox/QuickLook-ObjectMode.pmrem4x4.ktx2?pmrem";
+    const value = MagicSkyboxNames[str.toLowerCase() as MagicSkyboxName];
+    if (value) {
+        return useLowRes ? value.url_low : value.url;
+    }
+    else if (typeof str === "string" && str?.length && (isDevEnvironment() || debug)) {
+        const noUrlOrFile = !str.startsWith("http") && !str.startsWith("file:") && !str.startsWith("blob:") && !str.startsWith("data:");
+        if(noUrlOrFile) {
+            console.warn(`RemoteSkybox: Unknown magic skybox name "${str}". Valid names are: ${Object.keys(MagicSkyboxNames).map(n => `"${n}"`).join(", ")}`);
+        }
     }
-
-
 
     return str;
 }

package/src/engine-components/SmoothFollow.ts

@@ -9,6 +9,7 @@ import { Behaviour } from "./Component.js";
 /**
  * SmoothFollow makes the {@link Object3D} (`GameObject`) smoothly follow another target {@link Object3D}.  
  * It can follow the target's position, rotation, or both.   
+ * @summary Smoothly follows a target object
  * @category Interactivity
  * @group Components
  */

package/src/engine-components/SpatialTrigger.ts

@@ -26,6 +26,7 @@ function testMask(mask1, mask2) {
 /**
  * Component that receives and responds to spatial events, like entering or exiting a trigger zone.
  * Used in conjunction with {@link SpatialTrigger} to create interactive spatial events.
+ * @summary Receives spatial trigger events
  * @category Interactivity
  * @group Components
  */

package/src/engine-components/SpectatorCamera.ts

@@ -35,6 +35,7 @@ const debug = getParam("debugspectator");
  * 
  * Debug mode can be enabled with the URL parameter `?debugspectator`, which provides additional console output.
  * 
+ * @summary Follow other users in a networked room
  * @category Networking
  * @group Components
  */

package/src/engine-components/SpriteRenderer.ts

@@ -86,6 +86,7 @@ function updateTextureIfNecessary(tex: Texture) {
 
 /**
  * A sprite is a mesh that represents a 2D image. Used by the {@link SpriteRenderer} to render 2D images in the scene.
+ * @summary 2D image renderer 
  * @category Rendering
  * @group Components
  */

package/src/engine-components/SyncedCamera.ts

@@ -63,6 +63,8 @@ declare type UserCamInfo = {
 /**
  * SyncedCamera is a component that syncs the camera position and rotation of all users in the room.  
  * A prefab can be set to represent the remote cameras visually in the scene.
+ * 
+ * @summary Syncs camera position and rotation of users in a networked room
  * @category Networking
  * @group Components
  */

package/src/engine-components/SyncedRoom.ts

@@ -33,6 +33,7 @@ const debug = utils.getParam("debugsyncedroom");
  * myObject.addComponent(SyncedRoom, { joinRandomRoom: true, roomPrefix: "myApp_" });
  * ```
  * 
+ * @summary Joins a networked room based on URL parameters or a random room
  * @category Networking
  * @group Components
  */

package/src/engine-components/SyncedTransform.ts

@@ -57,6 +57,8 @@ onUpdate((ctx) => {
 /**
  * SyncedTransform synchronizes the position and rotation of a game object over the network.
  * It handles ownership transfer, interpolation, and network state updates automatically.
+ * 
+ * @summary Synchronizes object transform over the network with ownership management
  * @category Networking
  * @group Components
  */

package/src/engine-components/TransformGizmo.ts

@@ -10,6 +10,8 @@ import { SyncedTransform } from "./SyncedTransform.js";
 /**
  * TransformGizmo displays manipulation controls for translating, rotating, and scaling objects in the scene.
  * It wraps three.js {@link TransformControls} and provides keyboard shortcuts for changing modes and settings.
+ * 
+ * @summary Object manipulation gizmo for translating, rotating, and scaling
  * @category Helpers
  * @group Components
  */

package/src/engine-components/VideoPlayer.ts

@@ -54,6 +54,7 @@ export enum VideoRenderMode {
  *    playOnAwake: true,
  * });
  * ```
+ * @summary Plays video clips from URLs or streams
  * @category Multimedia
  * @group Components
  */

package/src/engine-components/Voip.ts

@@ -14,6 +14,7 @@ const debugParam = getParam("debugvoip");
 /**
  * The Voice over IP component (VoIP) allows you to send and receive audio streams to other users in the same networked room.  
  * It requires a networking connection to be working (e.g. by having an active SyncedRoom component in the scene or by connecting to a room manually).  
+ * @summary Voice over IP (VoIP) for networked audio communication
  * @category Networking
  * @group Components
  */

package/src/engine-components/export/usdz/USDZExporter.ts

@@ -1,5 +1,5 @@
 import { NEEDLE_progressive } from "@needle-tools/gltf-progressive";
-import { Euler, EventDispatcher, Matrix4, Mesh, Object3D, Quaternion, Vector3 } from "three";
+import { Euler, Material, Matrix4, Mesh, Object3D, Quaternion, Vector3 } from "three";
 
 import { isDevEnvironment, showBalloonMessage, showBalloonWarning } from "../../../engine/debug/index.js";
 import { hasProLicense } from "../../../engine/engine_license.js";
@@ -53,6 +53,23 @@ export class CustomBranding {
     callToActionURL?: string;
 }
 
+type BeforeLODExportArguments = {
+    readonly exporter: USDZExporter;
+    /** The type of LOD being exported, either a texture or a mesh */
+    readonly type: "texture" | "mesh";
+    /** The Renderer gameobject */
+    readonly object: Object3D;
+    /** The mesh being exported, if applicable */
+    readonly mesh?: Mesh;
+    /** The material being exported, if applicable */
+    readonly material?: Material;
+    /** By default LOD 0 will be exported (highest quality). 
+     * Set to a different LOD level if needed. 
+     * Set to -1 to disable LOD export and simply export the current version.
+    */
+    overrideLevel?: number;
+}
+
 /**
  * Exports the current scene or a specific object as USDZ file and opens it in QuickLook on iOS/iPadOS/visionOS.  
  * The USDZ file is generated using the Needle Engine ThreeUSDZExporter.  
@@ -72,8 +89,12 @@ export class CustomBranding {
  */
 export class USDZExporter extends Behaviour {
 
-    static readonly beforeExport = new EventList<{ exporter: USDZExporter }>();
-    static readonly afterExport = new EventList<{ exporter: USDZExporter }>();
+    /** Called before the USDZ file is exported */
+    static readonly beforeExport = new EventList<{ readonly exporter: USDZExporter }>();
+    /** Called after the USDZ file has been exported */
+    static readonly afterExport = new EventList<{ readonly exporter: USDZExporter }>();
+    /** Called before LOD level are exported. Can be used to override the LOD export settings */
+    static readonly beforeLODExport = new EventList<BeforeLODExportArguments>();
 
     /**
      * Assign the object to export as USDZ file. If undefined or null, the whole scene will be exported.
@@ -329,7 +350,20 @@ export class USDZExporter extends Behaviour {
         for (const rend of renderers) {
             for (const mesh of rend.sharedMeshes) {
                 if (mesh) {
-                    const task = NEEDLE_progressive.assignMeshLOD(mesh, 0);
+                    let lodLevel = 0;
+                    const args: BeforeLODExportArguments = { exporter: this, type: "mesh" as const, object: rend.gameObject, mesh: mesh, };
+                    USDZExporter.beforeLODExport.invoke(args);
+                    if (args.overrideLevel !== undefined) {
+                        if (args.overrideLevel === -1) {
+                            if (debug) console.warn("Skipping LOD export for mesh due to overrideLevel -1", rend.gameObject, mesh);
+                            continue; // skip LOD assignment
+                        }
+                        else if (args.overrideLevel >= 0) {
+                            lodLevel = args.overrideLevel;
+                            if (debug) console.log("Overriding LOD level for mesh export to level " + lodLevel + " " + mesh.name);
+                        }
+                    }
+                    const task = NEEDLE_progressive.assignMeshLOD(mesh, lodLevel);
                     if (task instanceof Promise)
                         progressiveLoading.push(new Promise<void>((resolve, reject) => {
                             task.then(() => {
@@ -342,7 +376,20 @@ export class USDZExporter extends Behaviour {
             }
             for (const mat of rend.sharedMaterials) {
                 if (mat) {
-                    const task = NEEDLE_progressive.assignTextureLOD(mat, 0);
+                    let lodLevel = 0;
+                    const args: BeforeLODExportArguments = { exporter: this, type: "texture" as const, object: rend.gameObject, material: mat };
+                    USDZExporter.beforeLODExport.invoke(args);
+                    if (args.overrideLevel !== undefined) {
+                        if (args.overrideLevel === -1) {
+                            if (debug) console.warn("Skipping LOD assignment due to overrideLevel -1", rend.gameObject, mat);
+                            continue; // skip LOD assignment
+                        }
+                        else if (args.overrideLevel >= 0) {
+                            lodLevel = args.overrideLevel;
+                            if (debug) console.log("Overriding LOD level for texture export to level " + lodLevel + " " + mat.name);
+                        }
+                    }
+                    const task = NEEDLE_progressive.assignTextureLOD(mat, lodLevel);
                     if (task instanceof Promise)
                         progressiveLoading.push(new Promise<void>((resolve, reject) => {
                             task.then(() => {

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 Particle System
  * @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 Button UI Component
  * @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 Canvas UI Component
  * @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 CanvasGroup UI Component
  * @category User Interface
  * @group Components
  */