@needle-tools/engine 4.13.1-beta → 4.13.1

package/src/engine/engine_physics_rapier.ts

@@ -3,7 +3,9 @@ import { BufferAttribute, BufferGeometry, InterleavedBufferAttribute, LineBasicM
 import * as BufferGeometryUtils from 'three/examples/jsm/utils/BufferGeometryUtils.js'
 
 import { CollisionDetectionMode, PhysicsMaterialCombine } from '../engine/engine_physics.types.js';
+import type { Collider as NeedleCollider } from '../engine-components/Collider.js';
 import { MeshCollider } from '../engine-components/Collider.js';
+import type { Rigidbody as NeedleRigidbody } from '../engine-components/RigidBody.js';
 import { isDevEnvironment } from './debug/debug.js';
 import { ContextEvent, ContextRegistry } from './engine_context_registry.js';
 import { foreachComponent } from './engine_gameobject.js';
@@ -132,10 +134,12 @@ declare type PhysicsBody = {
  *   const colliderDesc = MODULES.RAPIER_PHYSICS.MODULE.ColliderDesc.ball(1.0);
  * }
  * ```
- * @see {@link Physics} for general raycasting and physics utilities  
- * @see {@link MODULES.RAPIER_PHYSICS} for direct access to the Rapier module  
- * @link https://rapier.rs/docs/ for Rapier documentation  
- * @link https://engine.needle.tools/docs/reference/components.html#physics  
+ * @see {@link Rigidbody} for physics simulation component
+ * @see {@link Collider} for collision detection component
+ * @see {@link Physics} for general raycasting and physics utilities
+ * @see {@link MODULES.RAPIER_PHYSICS} for direct access to the Rapier module
+ * @link https://rapier.rs/docs/ for Rapier documentation
+ * @link https://engine.needle.tools/docs/reference/components.html#physics
  * @link https://engine.needle.tools/docs/how-to-guides/scripting/use-physics.html
  */
 export class RapierPhysics implements IPhysicsEngine {

package/src/engine-components/ContactShadows.ts

@@ -13,6 +13,9 @@ import { HideFlags, IGameObject, Vec3 } from "../engine/engine_types.js";
 import { getParam } from "../engine/engine_utils.js"
 import { setCustomVisibility } from "../engine/js-extensions/Layers.js";
 import { Behaviour, GameObject } from "./Component.js";
+import type { ShadowCatcher } from "./ShadowCatcher.js";
+import type { Light } from "./Light.js";
+import type { Renderer } from "./Renderer.js";
 
 const debug = getParam("debugcontactshadows");
 
@@ -45,7 +48,8 @@ type FitParameters = {
 
 /**
  * [ContactShadows](https://engine.needle.tools/docs/api/ContactShadows) renders proximity-based soft shadows on flat surfaces.
- * Ideal for products or objects that need visual grounding without real-time shadows.    
+ * Ideal for products or objects that need visual grounding without real-time shadows.  
+ * Produces soft, blurred shadows that hug the ground, giving a sense of contact and depth.     
  * 
  * ![](https://cloud.needle.tools/-/media/87bPTNXHcsbV-An-oSEvHQ.gif)
  *
@@ -72,6 +76,7 @@ type FitParameters = {
  * @summary Display contact shadows on the ground
  * @category Rendering
  * @group Components
+ * @see {@link ShadowCatcher} for real-time shadows from lights (more accurate, higher performance cost)
  * @see {@link Light} for real-time shadow casting
  * @see {@link Renderer} for material/rendering control
  * @link https://engine.needle.tools/samples/contact-shadows for a demo of contact shadows

package/src/engine-components/EventList.ts

@@ -175,10 +175,10 @@ export class EventList<TArgs extends any = any> implements IEventList {
                         // remap the arguments to the new instance (e.g. if an object is passed as an argument to the event list and this object has been cloned we want to remap it to the clone)
                         const newArguments = method.arguments?.map(arg => {
                             if (arg instanceof Object && arg.uuid) {
-                                return ctx[arg.uuid];
+                                return ctx[arg.uuid].clone;
                             }
                             else if ((arg as IComponent)?.isComponent) {
-                                return ctx[(arg as IComponent).guid];
+                                return ctx[(arg as IComponent).guid].clone;
                             }
                             return arg;
                         });

package/src/engine-components/Renderer.ts

@@ -200,22 +200,24 @@ class SharedMaterialArray implements ISharedMaterials {
 }
 
 /**
- * [Renderer](https://engine.needle.tools/docs/api/Renderer) controls rendering properties of meshes including materials,
- * lightmaps, reflection probes, and GPU instancing.
+ * The [Renderer](https://engine.needle.tools/docs/api/Renderer) component controls rendering properties of meshes including materials,  
+ * lightmaps, reflection probes, and GPU instancing.  
  *
- * **Materials:**
- * Access materials via `sharedMaterials` array. Changes affect all instances.
- * Use material cloning for per-instance variations.
+ * **Materials:**  
+ * Access materials via `sharedMaterials` array. Changes affect all instances.  
+ * Use material cloning for per-instance variations.  
  *
- * **Instancing:**
- * Enable GPU instancing for improved performance with many identical objects.
- * Use `Renderer.setInstanced(obj, true)` or `enableInstancing` property.
+ * **Instancing:**  
+ * Enable GPU instancing for improved performance with many identical objects.  
+ * Use `Renderer.setInstanced(obj, true)` or `enableInstancing` property.  
  *
- * **Lightmaps:**
- * Baked lighting is automatically applied when exported from Unity.
- * Access via the associated {@link RendererLightmap} component.
+ * **Lightmaps:**  
+ * Baked lighting is automatically applied when exported from Unity or Blender.  
+ * Access via the associated {@link RendererLightmap} component.    
+ * 
+ * [![](https://cloud.needle.tools/-/media/Vk944XVswtPEuxlNPLMxPQ.gif)](https://engine.needle.tools/samples/multiple-lightmaps/)
  *
- * **Debug options:**
+ * **Debug options:**  
  * - `?debugrenderer` - Log renderer info
  * - `?wireframe` - Show wireframe rendering
  * - `?noinstancing` - Disable GPU instancing
@@ -235,7 +237,6 @@ class SharedMaterialArray implements ISharedMaterials {
  * @group Components
  * @see {@link ReflectionProbe} for environment reflections
  * @see {@link Light} for scene lighting
- * @see {@link LODGroup} for level of detail
  */
 export class Renderer extends Behaviour implements IRenderer {
 

package/src/engine-components/RigidBody.ts

@@ -2,14 +2,18 @@ import { Matrix4, Object3D, Quaternion, Vector3, Vector3Like } from "three";
 
 import { isDevEnvironment } from "../engine/debug/index.js";
 import { MODULES } from "../engine/engine_modules.js";
+import type { Physics } from "../engine/engine_physics.js";
 import { CollisionDetectionMode, RigidbodyConstraints } from "../engine/engine_physics.types.js";
+import type { RapierPhysics } from "../engine/engine_physics_rapier.js";
 import { serializable } from "../engine/engine_serialization_decorator.js";
 import { Context, FrameEvent } from "../engine/engine_setup.js";
-import { getWorldPosition } from "../engine/engine_three_utils.js";
 import type { IRigidbody, Vec3 } from "../engine/engine_types.js";
 import { validate } from "../engine/engine_util_decorator.js";
 import { delayForFrames, Watch } from "../engine/engine_utils.js";
+import type { CharacterController } from "./CharacterController.js";
+import type { BoxCollider, CapsuleCollider, Collider,MeshCollider, SphereCollider } from "./Collider.js";
 import { Behaviour } from "./Component.js";
+import type { Joint } from "./Joints.js";
 
 class TransformWatch {
 
@@ -134,15 +138,67 @@ class TransformWatch {
 }
 
 /**
- * A Rigidbody is used together with a Collider to create physical interactions between objects in the scene.   
+ * Rigidbody component for realistic physics simulation and dynamic interactions.  
+ * Used together with a {@link Collider} to enable physical behavior like gravity, collisions,  
+ * forces, and constraints. Powered by the Rapier physics engine.    
  * 
- * - Example: https://samples.needle.tools/physics-basic
- * - Example: https://samples.needle.tools/physics-playground
- * - Example: https://samples.needle.tools/physics-&-animation
- * 
- * @summary Rigidbody for physical interactions
- * @category Physics 
+ * ![](https://cloud.needle.tools/-/media/slYWnXyaxdlrCqu8GP_lFQ.gif)
+ *
+ * **Key features:**
+ * - Dynamic, kinematic, or static body types
+ * - Automatic or manual mass calculation
+ * - Gravity, drag, and angular drag control
+ * - Position and rotation constraints (locking axes)
+ * - Force, impulse, and velocity manipulation
+ * - Sleep/wake optimization for performance
+ * - Continuous collision detection (CCD) support
+ *
+ * @example Basic dynamic rigidbody
+ * ```ts
+ * const rb = this.gameObject.getComponent(Rigidbody);
+ * rb.useGravity = true;
+ * rb.mass = 2.0;
+ * rb.drag = 0.5;
+ * ```
+ *
+ * @example Apply force to move object
+ * ```ts
+ * const rb = this.gameObject.getComponent(Rigidbody);
+ * rb.applyForce(new Vector3(0, 10, 0)); // Upward force
+ * rb.applyImpulse(new Vector3(5, 0, 0)); // Instant velocity change
+ * ```
+ *
+ * @example Kinematic rigidbody (manually controlled)
+ * ```ts
+ * const rb = this.gameObject.getComponent(Rigidbody);
+ * rb.isKinematic = true; // Not affected by forces
+ * rb.teleport({ x: 0, y: 5, z: 0 }); // Move without physics
+ * ```
+ *
+ * @example Lock rotation on Y axis (useful for characters)
+ * ```ts
+ * const rb = this.gameObject.getComponent(Rigidbody);
+ * rb.lockRotationY = true;
+ * // Or use constraints for multiple axes:
+ * rb.constraints = RigidbodyConstraints.FreezeRotationY | RigidbodyConstraints.FreezePositionZ;
+ * ```
+ *
+ * @summary Enables physics simulation with forces, gravity, and collisions
+ * @category Physics
  * @group Components
+ * @see {@link BoxCollider} for box-shaped colliders
+ * @see {@link SphereCollider} for sphere-shaped colliders
+ * @see {@link CapsuleCollider} for capsule-shaped colliders
+ * @see {@link MeshCollider} for mesh-based colliders
+ * @see {@link Collider} for collider base class
+ * @see {@link CharacterController} for character movement
+ * @see {@link Joint} for connecting bodies
+ * @see {@link RapierPhysics} for physics engine implementation
+ * @see {@link Physics} for raycasting and physics utilities
+ * @link https://engine.needle.tools/samples/physics-basic/
+ * @link https://engine.needle.tools/samples/physics-playground/
+ * @link https://engine.needle.tools/samples/physics-&-animation/
+ * @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies
  */
 export class Rigidbody extends Behaviour implements IRigidbody {
 

package/src/engine-components/ScreenCapture.ts

@@ -100,6 +100,7 @@ export declare type ScreenCaptureOptions = {
  *
  * @summary Share screen, camera or microphone in a networked room
  * @category Networking
+ * @category Multimedia
  * @group Components
  * @see {@link VideoPlayer} for displaying the received stream
  * @see {@link Voip} for voice-only communication

package/src/engine-components/SeeThrough.ts

@@ -10,6 +10,8 @@ import { Behaviour } from "./Component.js";
 import { IUSDExporterExtension } from "./export/usdz/Extension.js";
 import { USDZExporter } from "./export/usdz/USDZExporter.js";
 import { Renderer } from "./Renderer.js";
+import type { Camera } from "./Camera.js";
+import type { OrbitControls } from "./OrbitControls.js";
 
 const debugSeeThrough = getParam("debugseethrough");
 
@@ -32,17 +34,82 @@ let i = 0;
 
 
 /**
- * Makes the object fade out when it is obscuring the reference point from the camera. This component can be put on any object in the scene. It will affect all Renderer components on the same object and child objects. 
- * 
- * Useful for e.g. making walls transparent when the camera is outside or hiding object's that would otherwise block the view.  
- * 
- * Requires a Renderer component on the same object or a child object.
- * 
- * - Example https://see-through-walls-z23hmxbz1kjfjn.needle.run/
- * 
- * @summary Makes objects fade out when obscuring a reference point from the camera
+ * Automatically fades objects to transparent when they obscure a reference point from the camera's view.  
+ * Perfect for architectural visualization, third-person games, or any scenario where objects should  
+ * become see-through when blocking the view of important content.  
+ *
+ * [![](https://cloud.needle.tools/-/media/1gbMOJLgTlXOug_g6xeKfg.gif)](https://engine.needle.tools/samples/see-through)
+ *
+ * **How it works:**  
+ * - Monitors the angle between the camera, this object, and a reference point
+ * - When the object blocks the view to the reference point, it fades out
+ * - Automatically affects all {@link Renderer} components on this object and children
+ * - Supports both transparent fading and alpha hash (dithered) fading
+ *
+ * **Key Features:**  
+ * - Smooth fade transitions with configurable duration
+ * - Optional alpha hash for maintaining opaque rendering (better performance)
+ * - Automatic or manual update modes
+ * - Disables raycasting when faded (objects become click-through)
+ * - Preserves original material properties when re-enabled
+ *
+ * **Configuration:**
+ * - `referencePoint` - Object to keep visible (defaults to scene root)
+ * - `fadeDuration` - Transition speed (default: 0.05 seconds)
+ * - `minAlpha` - Minimum opacity when faded (default: 0 = fully transparent)
+ * - `useAlphaHash` - Use dithered transparency instead of true transparency (default: true)
+ *
+ * **Performance:**
+ * - Materials are cloned once per renderer to avoid affecting shared materials
+ * - Updates direction calculation every 20 frames by default (configurable via `autoUpdate`)
+ * - Use `needsUpdate = true` to force immediate recalculation
+ *
+ * **Requirements:**
+ * Requires at least one {@link Renderer} component on the same object or child objects.
+ *
+ * @example Make walls transparent when blocking view
+ * ```ts
+ * // Add to walls or obstacles
+ * const seeThrough = wall.addComponent(SeeThrough);
+ * seeThrough.referencePoint = player; // Keep player visible
+ * seeThrough.fadeDuration = 0.2; // Smooth fade
+ * seeThrough.minAlpha = 0.2; // Slightly visible when faded
+ * ```
+ *
+ * @example Third-person camera with see-through objects
+ * ```ts
+ * const character = GameObject.findByName("Character");
+ * const obstacles = GameObject.findByTag("Obstacle");
+ *
+ * for (const obstacle of obstacles) {
+ *   const st = obstacle.addComponent(SeeThrough);
+ *   st.referencePoint = character;
+ *   st.useAlphaHash = true; // Better performance
+ * }
+ * ```
+ *
+ * @example Manual control of see-through effect
+ * ```ts
+ * const seeThrough = this.gameObject.getComponent(SeeThrough);
+ * if (seeThrough) {
+ *   seeThrough.autoUpdate = false; // Disable automatic fading
+ *
+ *   // Manually control transparency
+ *   seeThrough.updateAlpha(0.5, 0.3); // Fade to 50% over 0.3 seconds
+ *
+ *   // Or use override for precise control
+ *   seeThrough.overrideAlpha = 0.8; // Force 80% opacity
+ * }
+ * ```
+ *
+ * @summary Fades objects when they obscure the camera's view of a reference point
  * @category Rendering
  * @group Components
+ * @see {@link Renderer} for material/rendering control (required)
+ * @see {@link Camera} for camera setup and configuration
+ * @see {@link OrbitControls} for camera controls in similar use cases
+ * @link https://see-through-walls-z23hmxbz1kjfjn.needle.run/ for live demo
+ * @link https://engine.needle.tools/samples/see-through for sample project
  */
 export class SeeThrough extends Behaviour {
 

package/src/engine-components/ShadowCatcher.ts

@@ -4,6 +4,9 @@ import { ObjectUtils, PrimitiveType } from "../engine/engine_create_objects.js";
 import { serializable } from "../engine/engine_serialization_decorator.js";
 import { RGBAColor } from "../engine/js-extensions/index.js";
 import { Behaviour } from "./Component.js";
+import type { ContactShadows } from "./ContactShadows.js";
+import type { Light } from "./Light.js";
+import type { Renderer } from "./Renderer.js";
 
 /**
  * The mode of the ShadowCatcher.  
@@ -18,14 +21,66 @@ enum ShadowMode {
 }
 
 /**
- * ShadowCatcher can be added to an Object3D to make it render shadows (or light) in the scene. It can also be used to create a shadow mask, or to occlude light.    
- * If the GameObject is a Mesh, it will apply a shadow-catching material to it - otherwise it will create a quad with the shadow-catching material.  
- * 
- * Note that ShadowCatcher meshes are not raycastable by default; if you want them to be raycastable, change the layers in `onEnable()`.
- * 
- * @summary Creates a shadow mask or a light occluder 
+ * ShadowCatcher renders real-time shadows cast by lights onto a mesh surface.  
+ * Captures actual shadow data from the scene's lighting system (directional lights, point lights, spot lights).  
+ *
+ * If the GameObject is a Mesh, it applies a shadow-catching material to it.  
+ * Otherwise, it creates a quad mesh with the shadow-catching material automatically.  
+ *
+ * [![](https://cloud.needle.tools/-/media/pFXPchA4vynNKOjgG_KucQ.gif)](https://engine.needle.tools/samples/shadow-catcher/)   
+ * *Additive ShadowCatcher mode with point light shadows*  
+ *
+ * [![](https://cloud.needle.tools/-/media/oIWgEU49rEA0xJ2TrbzVlg.gif)](https://engine.needle.tools/samples/transmission/)   
+ * *ShadowCatcher with directional light shadows*
+ *
+ * **Shadow Modes:**  
+ * - `ShadowMask` - Only renders shadows (works best with directional lights)  
+ * - `Additive` - Renders light additively (works best with point/spot lights)
+ * - `Occluder` - Occludes light without rendering shadows
+ *
+ * **ShadowCatcher vs ContactShadows:**
+ * - **ShadowCatcher**: Real-time shadows from actual lights. Accurate directional shadows that match light sources. Requires lights with shadows enabled. Updates every frame.
+ * - **{@link ContactShadows}**: Proximity-based ambient occlusion-style shadows. Extremely soft and diffuse, ideal for subtle grounding. Better performance, works without lights.
+ *
+ * **When to use ShadowCatcher:**
+ * - You need accurate shadows that match specific light directions
+ * - Scene has real-time lighting with shadow-casting lights
+ * - Shadows need to follow light attenuation and angles
+ * - AR/VR scenarios where light estimation is available
+ * - Hard or semi-hard shadow edges are desired
+ *
+ * **When to use ContactShadows instead:**
+ * - You want very soft, ambient occlusion-style ground shadows
+ * - Performance is critical (no per-frame shadow rendering)
+ * - Scene doesn't have shadow-casting lights
+ * - Product visualization or configurators (subtle grounding effect)
+ * - Soft, diffuse shadows are more visually appealing than accurate ones
+ *
+ * **Note:** ShadowCatcher meshes are not raycastable by default (layer 2). Change layers in `onEnable()` if raycasting is needed.
+ *
+ * @example Basic shadow catcher plane
+ * ```ts
+ * const plane = new Object3D();
+ * const catcher = addComponent(plane, ShadowCatcher);
+ * catcher.mode = ShadowMode.ShadowMask;
+ * catcher.shadowColor = new RGBAColor(0, 0, 0, 0.8);
+ * ```
+ *
+ * @example Apply to existing mesh
+ * ```ts
+ * const mesh = this.gameObject.getComponent(Mesh);
+ * const catcher = addComponent(mesh, ShadowCatcher);
+ * // The mesh will now catch shadows from scene lights
+ * ```
+ *
+ * @summary Renders real-time shadows from lights onto surfaces
  * @category Rendering
  * @group Components
+ * @see {@link ContactShadows} for proximity-based fake shadows (better performance)
+ * @see {@link Light} for shadow-casting light configuration
+ * @see {@link Renderer} for shadow receiving settings
+ * @link https://engine.needle.tools/samples/shadow-catcher/
+ * @link https://engine.needle.tools/samples/transmission/
  */
 export class ShadowCatcher extends Behaviour {
 

package/src/engine-components/Skybox.ts

@@ -114,20 +114,52 @@ ContextRegistry.registerCallback(ContextEvent.ContextCreationStart, () => {
 
 
 /**
- * [RemoteSkybox](https://engine.needle.tools/docs/api/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.
- * 
+ * The [RemoteSkybox](https://engine.needle.tools/docs/api/RemoteSkybox) component 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, and .ktx2 files.
+ *
+ * **HTML Attributes:**
+ * You can control skybox and environment from HTML using `<needle-engine>` attributes:
+ * - `background-image`: Sets the scene background/skybox image
+ * - `environment-image`: Sets the scene environment map (for reflections and lighting)
+ *
+ * These attributes accept URLs or magic skybox names (see examples below).
+ *
+ * **Magic Skybox Names:**
+ * Built-in optimized skyboxes hosted on Needle CDN:
+ * - `"studio"` - Neutral studio lighting (default)
+ * - `"blurred-skybox"` - Blurred environment
+ * - `"quicklook"` - Apple QuickLook object mode style
+ * - `"quicklook-ar"` - Apple QuickLook AR mode style
+ *
  * ### Events
  * - `dropped-unknown-url`: Emitted when a file is dropped on the scene. The event detail contains the sender, the url and a function to apply the url.
- * 
- * @example adding a skybox
+ *
+ * @example Using HTML attributes
+ * ```html
+ * <needle-engine
+ *   background-image="https://example.com/skybox.hdr"
+ *   environment-image="studio">
+ * </needle-engine>
+ * ```
+ *
+ * @example Using magic skybox names
+ * ```html
+ * <needle-engine background-image="studio"></needle-engine>
+ * <needle-engine environment-image="quicklook"></needle-engine>
+ * ```
+ *
+ * @example Adding via code
  * ```ts
- * GameObject.addComponent(gameObject, Skybox, { url: "https://example.com/skybox.hdr", background: true, environment: true });
+ * GameObject.addComponent(gameObject, RemoteSkybox, {
+ *   url: "https://example.com/skybox.hdr",
+ *   background: true,
+ *   environment: true
+ * });
  * ```
- * 
- * @example handle custom url
+ *
+ * @example Handle custom dropped URL
  * ```ts
- * const skybox = GameObject.addComponent(gameObject, Skybox);
+ * const skybox = GameObject.addComponent(gameObject, RemoteSkybox);
  * skybox.addEventListener("dropped-unknown-url", (evt) => {
  *    let url = evt.detail.url;
  *    console.log("User dropped file", url);
@@ -137,15 +169,19 @@ ContextRegistry.registerCallback(ContextEvent.ContextCreationStart, () => {
  *    evt.detail.apply(url);
  * });
  * ```
- * 
- * @example update skybox url
+ *
+ * @example Update skybox at runtime
  * ```ts
  * skybox.setSkybox("https://example.com/skybox.hdr");
+ * // Or use a magic name:
+ * skybox.setSkybox("studio");
  * ```
- * 
+ *
  * @summary Sets the skybox or environment texture of a scene
  * @category Rendering
  * @group Components
+ * @see {@link Camera} for clearFlags and background control
+ * @link https://engine.needle.tools/docs/html.html#needle-engine-element
  */
 export class RemoteSkybox extends Behaviour {
 

package/src/engine-components/VideoPlayer.ts

@@ -53,7 +53,7 @@ export enum VideoRenderMode {
  * - Media streams (from webcam, screen capture, etc.)
  * - HLS playlists (m3u8) for livestreaming  
  * 
- * ![](https://cloud.needle.tools/-/media/w1uHur5yu3Ni7qFaKIFX-g.gif)
+ * [![](https://cloud.needle.tools/-/media/w1uHur5yu3Ni7qFaKIFX-g.gif)](https://engine.needle.tools/samples/video-playback/)
  *
  * **Rendering modes:**  
  * Video can be rendered to a material texture, render texture, or camera planes.  

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

@@ -50,7 +50,10 @@ export type CreateTrackFunction = (director: PlayableDirector, track: Models.Tra
 /**
  * PlayableDirector is the main component for controlling timelines in Needle Engine.  
  * It orchestrates playback of TimelineAssets containing animation, audio, signal,  
- * control, and activation tracks.  
+ * control, and activation tracks.    
+ * 
+ * ![](https://cloud.needle.tools/-/media/CkJal5dIBwFe6erA-MmiGw.webp)  
+ * *Screenshot: Timeline in Unity*
  *
  * **Supported track types:**  
  * - Animation tracks - animate objects using AnimationClips
@@ -94,6 +97,7 @@ export type CreateTrackFunction = (director: PlayableDirector, track: Models.Tra
  * @see {@link SignalReceiver} for handling timeline signals
  * @link https://engine.needle.tools/samples/?overlay=samples&tag=animation
  * @link https://app.songsofcultures.com/  
+ * @link https://engine.needle.tools/docs/blender/animation.html Blender timeline and animation export
  */
 export class PlayableDirector extends Behaviour {
 

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

@@ -8,7 +8,7 @@ const debug = getParam("debugsignals")
 
 
 /**
- * Used to reference a signal asset in a SignalReceiver. This is internally used by the {@link SignalReceiverEvent}.
+ * Used to reference a signal asset in a SignalReceiver. This is internally used by the {@link SignalReceiverEvent}.  
  */
 export class SignalAsset {
     @serializable()

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

@@ -1,7 +1,10 @@
-import { AnimationClip, Object3D, Quaternion, Vector3 } from "three";
+import { AnimationClip, Object3D, Quaternion, Vector3 } from "three";  
+
+import type { PlayableDirector } from "./PlayableDirector";
 
 /**
  * @category Animation and Sequencing
+ * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
  */
 export declare type TimelineAssetModel = {
     name: string;
@@ -10,6 +13,8 @@ export declare type TimelineAssetModel = {
 
 /**
  * @category Animation and Sequencing
+ * @see {@link TimelineAssetModel} for the data structure of a timeline asset, which can be played using the PlayableDirector component.
+ * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
  */
 export enum TrackType {
     Activation = "ActivationTrack",
@@ -21,7 +26,9 @@ export enum TrackType {
 }
 
 /**
- * @category Animation and Sequencing
+ * @category Animation and Sequencing   
+ * @see {@link TimelineAssetModel} for the data structure of a timeline asset, which can be played using the PlayableDirector component.
+ * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
  */
 export enum ClipExtrapolation {
     None = 0,
@@ -33,6 +40,7 @@ export enum ClipExtrapolation {
 
 /**
  * @category Animation and Sequencing
+ * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
  */
 export declare type TrackModel = {
     name: string;
@@ -50,6 +58,7 @@ declare type Quat = { x: number, y: number, z: number, w: number };
 
 /**
  * @category Animation and Sequencing
+ * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
  */
 export declare type TrackOffset = {
     position: Vec3 | Vector3;
@@ -58,6 +67,7 @@ export declare type TrackOffset = {
 
 /**
  * @category Animation and Sequencing
+ * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
  */
 export declare type ClipModel = {
     start: number;
@@ -75,6 +85,7 @@ export declare type ClipModel = {
 
 /**
  * @category Animation and Sequencing
+ * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
  */
 export declare type AnimationClipModel = {
     clip: string | number | AnimationClip;
@@ -87,6 +98,7 @@ export declare type AnimationClipModel = {
 
 /**
  * @category Animation and Sequencing
+ * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
  */
 export declare type AudioClipModel = {
     clip: string;
@@ -96,6 +108,7 @@ export declare type AudioClipModel = {
 
 /**
  * @category Animation and Sequencing
+ * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
  */
 export declare type ControlClipModel = {
     sourceObject: string | Object3D;
@@ -109,6 +122,7 @@ export enum MarkerType {
 
 /**
  * @category Animation and Sequencing
+ * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
  */export declare class MarkerModel {
     type: MarkerType;
     time: number;
@@ -116,6 +130,7 @@ export enum MarkerType {
 
 /**
  * @category Animation and Sequencing
+ * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
  */
 export declare class SignalMarkerModel extends MarkerModel {
     retroActive: boolean;
@@ -133,5 +148,6 @@ export declare class SignalMarkerModel extends MarkerModel {
  * 
  * @link [Example Project using ScrollMarker](https://scrollytelling-bike-z23hmxb2gnu5a.needle.run/)
  * @category Animation and Sequencing
+ * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
 */
 export type ScrollMarkerModel = MarkerModel & { name?: string };