@needle-tools/engine 4.11.4-next.1fca70f → 4.11.4-next.a568de7

package/src/engine/engine_addressables.ts

@@ -10,6 +10,8 @@ import { SerializationContext, TypeSerializer } from "./engine_serialization_cor
 import { Context } from "./engine_setup.js";
 import type { GLTF, IComponent, IGameObject, Model, SourceIdentifier } from "./engine_types.js";
 
+import type { loadAsset } from "./engine_loaders.js";
+
 const debug = getParam("debugaddressables");
 
 /** 
@@ -79,13 +81,50 @@ export type ProgressCallback = (asset: AssetReference, prog: ProgressEvent) => v
 
 const $assetReference = Symbol("assetReference");
 
-/** ### AssetReferences can be used to easily load glTF or GLB assets  
- * You can use `AssetReference.getOrCreate` to get an AssetReference for a URL to be easily loaded.  
- * When using the same URL multiple times the same AssetReference will be returned, this avoids loading or creating the same asset multiple times.  
- * - `myAssetReference.preload()` to load the asset binary without creating an instance yet.
- * - `myAssetReference.loadAssetAsync()` to load the asset and create an instance.  
- * - `myAssetReference.instantiate()` to load the asset and create a new instance.  
- * - `myAssetReference.unload()` to dispose allocated memory and destroy the asset instance.  
+/** ### AssetReferences can be used to load glTF or GLB assets  
+ * Use {@link AssetReference.getOrCreateFromUrl} to get an AssetReference for a URL to be easily loaded. When using the same URL multiple times the same AssetReference will be returned, this avoids loading or creating the same asset multiple times.   
+ * 
+ * **Important methods:**
+ * - {@link preload} to load the asset binary without creating an instance yet.
+ * - {@link loadAssetAsync} to load the asset and create an instance.  
+ * - {@link instantiate} to load the asset and create another instance.  
+ * - {@link unload} to dispose allocated memory and destroy the asset instance.  
+ * 
+ * @example Loading an asset from a URL
+ * ```ts
+ * import { AssetReference } from '@needle-tools/engine';
+ * const assetRef = AssetReference.getOrCreateFromUrl("https://example.com/myModel.glb");
+ * const instance = await assetRef.loadAssetAsync();
+ * scene.add(instance);
+ * ```
+ * 
+ * @example Referencing an asset in a component and loading it on start
+ * ```ts
+ * import { Behaviour, serializable, AssetReference } from '@needle-tools/engine';
+ * 
+ * export class MyComponent extends Behaviour {
+ * 
+ *   @serializable(AssetReference)
+ *   myModel?: AssetReference;
+ *   
+ *   // Load the model on start. Start is called after awake and onEnable
+ *   start() { 
+ *     if (this.myModel) {
+ *       this.myModel.loadAssetAsync().then(instance => {
+ *         if (instance) {
+ *           // add the loaded model to this component's game object
+ *           this.gameObject.add(instance); 
+ *         }
+ *       });
+ *     }
+ *   }
+ * }
+ * ```
+ * 
+ * ### Related:
+ * - {@link ImageReference} to load external image URLs
+ * - {@link FileReference} to load external file URLs
+ * - {@link loadAsset} to load assets directly without using AssetReferences
  */
 export class AssetReference {
 
@@ -524,12 +563,33 @@ new AddressableSerializer();
 
 const failedTexturePromise = Promise.resolve(null);
 
-/** Use this if a file is a external image URL
+/**  
+ * Load images or textures from external URLs.
+ * 
+ * **Important methods:**
+ * - {@link createHTMLImage} to create an HTMLImageElement from the URL
+ * - {@link createTexture} to create a Three.js Texture from the URL
+ * 
  * @example
  * ```ts
- * @serializable(ImageReference)  
- * myImage?:ImageReference;
+ * import { ImageReference, serializable } from '@needle-tools/engine';
+ * 
+ * export class MyComponent extends Behaviour {
+ *   @serializable(ImageReference)  
+ *   myImage?:ImageReference;
+ *   async start() {
+ *     if(this.myImage) {
+ *       const texture = await this.myImage.createTexture();
+ *       if(texture) {
+ *         // use the texture
+ *       }
+ *     }
+ *   }
  * ```
+ * 
+ * ### Related:
+ * - {@link AssetReference} to load glTF or GLB assets
+ * - {@link FileReference} to load external file URLs
  */
 export class ImageReference {
 
@@ -637,7 +697,12 @@ new ImageReferenceSerializer();
 
 
 
-/** Use this if a file is a external file URL. The file can be any arbitrary binary data like a videofile or a text asset
+/** 
+ * Use this if a file is a external file URL. The file can be any arbitrary binary data like a videofile or a text asset.  
+ * 
+ * ### Related:
+ * - {@link AssetReference} to load glTF or GLB assets
+ * - {@link ImageReference} to load external image URLs
  */
 export class FileReference {
 

package/src/engine/engine_camera.fit.ts

@@ -7,9 +7,14 @@ import { Gizmos } from "./engine_gizmos.js";
 import { getBoundingBox } from "./engine_three_utils.js";
 import { NeedleXRSession } from "./xr/NeedleXRSession.js";
 
+import type { OrbitControls } from "../engine-components/OrbitControls.js";
+
 
 /**
- * Options for fitting the camera to the scene. Used in {@link OrbitControls.fitCamera}
+ * Options for fitting a camera to the scene or specific objects.
+ * 
+ * Used by {@link OrbitControls.fitCamera} and the {@link fitCamera}.
+ * 
  */
 export type FitCameraOptions = {
     /** When enabled debug rendering will be shown */
@@ -31,8 +36,17 @@ export type FitCameraOptions = {
      */
     camera?: Camera,
 
+    /**
+     * The current zoom level of the camera (used to avoid clipping when fitting)
+     */
     currentZoom?: number,
+    /**
+     * Minimum and maximum zoom levels for the camera (e.g. if zoom is constrained by OrbitControls)
+     */
     minZoom?: number,
+    /**
+     * Maximum zoom level for the camera (e.g. if zoom is constrained by OrbitControls)
+     */
     maxZoom?: number,
 
     /**
@@ -40,7 +54,11 @@ export type FitCameraOptions = {
      */
     objects?: Object3D[] | Object3D;
 
-    /** Fit offset: A factor to multiply the distance to the objects by
+    /**
+     * A factor to control padding around the fitted objects.  
+     * 
+     * Values > 1 will add more space around the fitted objects, values < 1 will zoom in closer.
+     * 
      * @default 1.1
      */
     fitOffset?: number,
@@ -74,7 +92,7 @@ export type FitCameraOptions = {
     relativeTargetOffset?: Partial<Vector3Like>,
 
     /**
-     * Field of view (FOV) for the camera
+     * Target field of view (FOV) for the camera
      */
     fov?: number,
 }
@@ -86,7 +104,35 @@ export type FitCameraReturnType = {
     fov: number | undefined
 }
 
-
+/**
+ * Fit the camera to the specified objects or the whole scene.    
+ * Adjusts the camera position and optionally the FOV to ensure all objects are visible.
+ * 
+ * @example Fit the main camera to the entire scene:
+ * ```ts
+ * import { fitCamera } from '@needle-tools/engine';
+ * 
+ * // Fit the main camera to the entire scene
+ * fitCamera();
+ * ```
+ * @example Fit a specific camera to specific objects with custom options:
+ * ```ts
+ * import { fitCamera } from '@needle-tools/engine';
+ * 
+ * // Fit a specific camera to specific objects with custom options
+ * const myCamera = ...; // your camera
+ * const objectsToFit = [...]; // array of objects to fit
+ * fitCamera({
+ *    camera: myCamera,
+ *    objects: objectsToFit,
+ *    fitOffset: 1,
+ *    fov: 20,
+ * });
+ * ```
+ * 
+ * @param options Options for fitting the camera
+ * @returns 
+ */
 export function fitCamera(options?: FitCameraOptions): null | FitCameraReturnType {
 
     if (NeedleXRSession.active) {

package/src/engine/engine_context.ts

@@ -129,9 +129,12 @@ export function registerComponent(script: IComponent, context?: Context) {
 }
 
 /**
- * The context is the main object that holds all the data and state of the Needle Engine.  
- * It can be used to access the scene, renderer, camera, input, physics, networking, and more.
- * @example
+ * The Needle Engine context is the main access point that holds all the data and state of a Needle Engine application. 
+ * It can be used to access the {@link Context.scene}, {@link Context.renderer}, {@link Context.mainCamera}, {@link Context.input}, {@link Context.physics}, {@link Context.time}, {@link Context.connection} (networking), and more.
+ * 
+ * The context is automatically created when using the `<needle-engine>` web component.  
+ * 
+ * @example Accessing the context from a [component](https://engine.needle.tools/docs/api/Behaviour):
  * ```typescript
  * import { Behaviour } from "@needle-tools/engine";
  * import { Mesh, BoxGeometry, MeshBasicMaterial } from "three";
@@ -142,6 +145,18 @@ export function registerComponent(script: IComponent, context?: Context) {
  *   }
  * }
  * ```
+ * 
+ * @example Accessing the context from a [hook](https://engine.needle.tools/docs/scripting.html#hooks) without a component e.g. from a javascript module or svelte or react component.
+ * 
+ * ```typescript
+ * import { onStart } from "@needle-tools/engine";
+ * 
+ * onStart((context) => {
+ *   console.log("Hello from onStart hook");
+ *   context.scene.add(new Mesh(new BoxGeometry(), new MeshBasicMaterial()));
+ * });
+ * ```
+ * 
  */
 export class Context implements IContext {
 

package/src/engine/extensions/NEEDLE_components.ts

@@ -1,13 +1,14 @@
 import { Object3D } from "three";
 import { GLTFExporter } from 'three/examples/jsm/exporters/GLTFExporter.js';
 import { type GLTF, type GLTFLoaderPlugin, GLTFParser } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { isDevEnvironment } from "../debug/debug.js";
 
 import { builtinComponentKeyName } from "../engine_constants.js";
 import { debugExtension } from "../engine_default_parameters.js";
 import { getLoader } from "../engine_gltf.js";
 import { type NodeToObjectMap, type ObjectToNodeMap, SerializationContext } from "../engine_serialization_core.js";
 import { apply } from "../js-extensions/index.js";
-import { maskGltfAssociation,resolveReferences } from "./extension_utils.js";
+import { maskGltfAssociation, resolveReferences } from "./extension_utils.js";
 
 export const debug = debugExtension
 const componentsArrayExportKey = "$___Export_Components";
@@ -15,7 +16,7 @@ const componentsArrayExportKey = "$___Export_Components";
 export const EXTENSION_NAME = "NEEDLE_components";
 
 class ExtensionData {
-    [builtinComponentKeyName]?: Array<object | null>
+    [builtinComponentKeyName]?: Array<Record<string, any> | null>
 }
 
 class ExportData {
@@ -35,14 +36,7 @@ export class NEEDLE_components implements GLTFLoaderPlugin {
     get name(): string {
         return EXTENSION_NAME;
     }
-
-    // import
-    parser?: GLTFParser;
-    nodeToObjectMap: NodeToObjectMap = {};
-    /** The loaded gltf */
-    gltf: GLTF | null = null;
-
-    // export
+    // #region export
     exportContext!: { [nodeIndex: number]: ExportData };
     objectToNodeMap: ObjectToNodeMap = {};
     context!: SerializationContext;
@@ -112,7 +106,7 @@ export class NEEDLE_components implements GLTFLoaderPlugin {
 
     writeNode(node: Object3D, nodeDef) {
         const nodeIndex = this.writer.json.nodes.length;
-        if (debug) 
+        if (debug)
             console.log(node.name, nodeIndex, node.uuid);
         const context = new ExportData(node, nodeIndex, nodeDef);
         this.exportContext[nodeIndex] = context;
@@ -158,8 +152,13 @@ export class NEEDLE_components implements GLTFLoaderPlugin {
 
 
     // -------------------------------------
-    // LOADING 
-    // called by GLTFLoader
+    // #region import 
+    parser?: GLTFParser;
+    nodeToObjectMap: NodeToObjectMap = {};
+    /** The loaded gltf */
+    gltf: GLTF | null = null;
+
+
     beforeRoot() {
         if (debug)
             console.log("BEGIN LOAD");
@@ -167,7 +166,6 @@ export class NEEDLE_components implements GLTFLoaderPlugin {
         return null;
     }
 
-    // called by GLTFLoader
     async afterRoot(result: GLTF): Promise<void> {
         this.gltf = result;
 
@@ -175,8 +173,7 @@ export class NEEDLE_components implements GLTFLoaderPlugin {
         const ext = parser?.extensions;
         if (!ext) return;
         const hasExtension = ext[this.name];
-        if (debug)
-            console.log("After root", result, this.parser, ext);
+        if (debug) console.log("After root", result, this.parser, ext);
 
         const loadComponents: Array<Promise<void>> = [];
         if (hasExtension === true) {
@@ -204,7 +201,7 @@ export class NEEDLE_components implements GLTFLoaderPlugin {
 
                     apply(obj);
 
-                    loadComponents.push(this.createComponents(obj, data));
+                    loadComponents.push(this.createComponents(result, node, obj, data));
                 }
             }
         }
@@ -220,7 +217,7 @@ export class NEEDLE_components implements GLTFLoaderPlugin {
         }
     }
 
-    private async createComponents(obj: Object3D, data: ExtensionData) {
+    private async createComponents(result: GLTF, node: Node, obj: Object3D, data: ExtensionData) {
         if (!data) return;
         const componentData = data[builtinComponentKeyName];
         if (componentData) {
@@ -228,20 +225,42 @@ export class NEEDLE_components implements GLTFLoaderPlugin {
             if (debug)
                 console.log(obj.name, componentData);
             for (const i in componentData) {
-                const serializedData = componentData[i];
-                if (debug)
-                    console.log("Serialized data", JSON.parse(JSON.stringify(serializedData)));
+                const data = componentData[i];
+
+                if (debug) console.log("Serialized data", JSON.parse(JSON.stringify(data)));
+
+                // Fix for https://linear.app/needle/issue/NE-6779/blender-export-has-missing-sharedmaterials
+                if (data?.name === "MeshRenderer" || data?.name === "SkinnedMeshRenderer") {
+                    if (!data.sharedMaterials) {
+                        let success = false;
+                        if ("mesh" in node) {
+                            const meshIndex = node.mesh;
+                            if (typeof meshIndex === "number" && result.parser) {
+                                const meshDef = result.parser.json.meshes?.[meshIndex];
+                                if (meshDef?.primitives) {
+                                    data.sharedMaterials =  meshDef.primitives.map(prim => {
+                                        return "/materials/" + (prim.material ?? 0);
+                                    });
+                                    success = true;
+                                }
+                            }
+                        }
+                        if(!success && (debug || isDevEnvironment())) {
+                            console.warn(`[NEEDLE_components] Component '${data.name}' on object '${obj.name}' is not added to a mesh or failed to retrieve materials from glTF.`);
+                        }
+                    }
+                }
 
-                if (serializedData && this.parser) {
+                if (data && this.parser) {
                     tasks.push(
-                        resolveReferences(this.parser, serializedData)
-                            .catch(e => console.error(`Error while resolving references (see console for details)\n`, e, obj, serializedData))
+                        resolveReferences(this.parser, data)
+                            .catch(e => console.error(`Error while resolving references (see console for details)\n`, e, obj, data))
                     );
                 }
 
                 obj.userData = obj.userData || {};
                 obj.userData[builtinComponentKeyName] = obj.userData[builtinComponentKeyName] || [];
-                obj.userData[builtinComponentKeyName].push(serializedData);
+                obj.userData[builtinComponentKeyName].push(data);
             }
             await Promise.all(tasks).catch((e) => {
                 console.error("Error while loading components", e);
@@ -266,4 +285,6 @@ export class NEEDLE_components implements GLTFLoaderPlugin {
     //     // console.log(components);
     //     return null;
     // }
-}
+}
+
+

package/src/engine-components/Renderer.ts

@@ -69,7 +69,7 @@ class SharedMaterialArray implements ISharedMaterials {
     set changed(value: boolean) {
         if (value === true) {
             if (debugRenderer)
-                console.warn("SharedMaterials have changed: " + this._renderer.name, this);
+                console.warn("SharedMaterials have changed: " + this._renderer.name);
         }
         this._changed = value;
     }
@@ -358,11 +358,15 @@ export class Renderer extends Behaviour implements IRenderer {
     //@ts-ignore
     get sharedMaterials(): SharedMaterialArray {
 
-        // @ts-ignore (original materials will be set during deserialization)
-        if (this._originalMaterials === undefined) return null;
-
-        // @ts-ignore during deserialization code might access this property *before* the setter and then create an empty array
-        if (this.__isDeserializing === true) return null;
+        if (this._originalMaterials === undefined) {
+            if (!this.__didAwake) {
+                // @ts-ignore (original materials will be set during deserialization)
+                return null;
+            }
+            else {
+                this._originalMaterials = [];
+            }
+        }
 
         if (!this._sharedMaterials || !this._sharedMaterials.is(this)) {
             if (!this._originalMaterials) this._originalMaterials = [];
@@ -454,6 +458,7 @@ export class Renderer extends Behaviour implements IRenderer {
             this.context.addBeforeRenderListener(this.gameObject, this.onBeforeRenderThree);
         }
 
+        this._lightmaps = undefined;
         this.applyLightmapping();
 
         if (showWireframe) {
@@ -468,8 +473,8 @@ export class Renderer extends Behaviour implements IRenderer {
     }
 
     private applyLightmapping() {
-        if (this.lightmapIndex >= 0) {
-            const type = this.gameObject.type;
+        if (this.lightmapIndex >= 0 && !this._lightmaps) {
+            // const type = this.gameObject.type;
 
             // use the override lightmap if its not undefined
             const tex = this._lightmapTextureOverride !== undefined
@@ -477,45 +482,12 @@ export class Renderer extends Behaviour implements IRenderer {
                 : this.context.lightmaps.tryGetLightmap(this.sourceId, this.lightmapIndex);
             if (tex) {
                 if (!this._lightmaps) this._lightmaps = [];
-
-
                 const rm = new RendererLightmap(this);
                 rm.init(this.lightmapIndex, this.lightmapScaleOffset, tex);
                 this._lightmaps.push(rm);
-
-                // if (type === "Mesh") {
-                //     const mat = this.gameObject["material"];
-                //     if (!mat?.isMeshBasicMaterial) {
-                //         if (this._lightmaps.length <= 0) {
-                //         }
-                //         const rm = this._lightmaps[0];
-                //         rm.init(this.lightmapIndex, this.lightmapScaleOffset, tex);
-                //     }
-                //     else {
-                //         if (mat)
-                //             console.warn("Lightmapping is not supported on MeshBasicMaterial", mat.name)
-                //     }
-                // }
-                // // for multi materials we need to loop through children 
-                // // and then we add a lightmap renderer component to each of them
-                // else if (this.isMultiMaterialObject(this.gameObject) && this.sharedMaterials.length > 0) {
-                //     for (let i = 0; i < this.gameObject.children.length; i++) {
-                //         const child = this.gameObject.children[i];
-                //         if (!child["material"]?.isMeshBasicMaterial) {
-                //             let rm: RendererLightmap | undefined = undefined;
-                //             if (i >= this._lightmaps.length) {
-                //                 rm = new RendererLightmap(child as Mesh, this.context);
-                //                 this._lightmaps.push(rm);
-                //             }
-                //             else
-                //                 rm = this._lightmaps[i];
-                //             rm.init(this.lightmapIndex, this.lightmapScaleOffset, tex);
-                //         }
-                //     }
-                // }
             }
             else {
-                if (debugRenderer) console.warn("Lightmap not found", this.sourceId, this.lightmapIndex);
+                if (debugRenderer) console.warn(`[Renderer] No lightmaps found ${this.name} (${this.sourceId}, ${this.lightmapIndex})`);
             }
         }
 

package/src/engine-components/RendererLightmap.ts

@@ -9,6 +9,10 @@ const debug = getParam("debuglightmaps");
 
 declare type MaterialWithLightmap = Material & { lightMap?: Texture | null };
 
+let cloningCounter = 0;
+
+const $lightmapVersion = Symbol("lightmap-material-version");
+
 
 /**
  * This component is automatically added by the {@link Renderer} component if the object has lightmap uvs AND we have a lightmap.
@@ -37,6 +41,8 @@ export class RendererLightmap {
     private lightmapScaleOffset: Vector4 = new Vector4(1, 1, 0, 0);
 
     private readonly renderer: Renderer;
+    private readonly clonedMaterials = new Array<Material>();
+
     private get context(): Context { return this.renderer.context; }
     private get gameObject() { return this.renderer.gameObject; }
     private lightmapTexture: Texture | null = null;
@@ -89,8 +95,7 @@ export class RendererLightmap {
 
             const mat = this.renderer.sharedMaterials[i];
             if (!mat) continue;
-
-            const newMat = this.ensureLightmapMaterial(mat);
+            const newMat = this.ensureLightmapMaterial(mat, i);
             if (mat !== newMat) {
                 this.renderer.sharedMaterials[i] = newMat;
             }
@@ -118,23 +123,28 @@ export class RendererLightmap {
         }
     }
 
-    private ensureLightmapMaterial(material: Material) {
+    private ensureLightmapMaterial(material: Material, index: number) {
         if (!material.userData) material.userData = {};
         // if (material instanceof MeshPhysicalMaterial) {
         //     return material;
         // }
         // check if the material version has changed and only then clone the material
-        if (material["NEEDLE:lightmap-material-version"] != material.version) {
-            if (material["NEEDLE:lightmap-material-version"] == undefined) {
-                if (debug) console.warn("Cloning material for lightmap " + material.name);
-                const mat: Material = material.clone();
-                if (!mat.name?.includes("(lightmap)")) mat.name = material.name + " (lightmap)";
-                material = mat;
-                material.onBeforeCompile = this.onBeforeCompile;
-            }
-            else {
-                // we need to clone the material
+        if (this.clonedMaterials[index] !== material) {
+            if (debug) {
+                ++cloningCounter;
+                if (cloningCounter++ < 1000) {
+                    console.warn(`Cloning material for lightmap ${this.renderer.name}: '${material.name}'`);
+                }
+                else if (cloningCounter === 1000) {
+                    console.warn(`Further material cloning for lightmaps suppressed to avoid flooding the console.`);
+                }
             }
+            const mat: Material = material.clone();
+            if (!mat.name?.includes("(lightmap)")) mat.name = material.name + " (lightmap)";
+            material = mat;
+            material.onBeforeCompile = this.onBeforeCompile;
+            this.clonedMaterials[index] = material;
+
         }
         return material;
     }
@@ -144,22 +154,22 @@ export class RendererLightmap {
         if (material instanceof MeshPhysicalMaterial && material.transmission > 0) {
             return;
         }
-        const hasChanged = material.lightMap !== this.lightmapTexture || material["NEEDLE:lightmap-material-version"] !== material.version;
+        const hasChanged = material.lightMap !== this.lightmapTexture || material[$lightmapVersion] !== material.version;
         if (!hasChanged) {
             return;
         }
 
-        if (debug) console.log("Assigning lightmap", material.name, material.version, material);
+        if (debug) console.log(`Assigning lightmap texture ${this.renderer.name}: '${material.name}' (${material.version} ${material[$lightmapVersion]})`);
 
         // assign the lightmap
         material.lightMap = this.lightmapTexture;
         material.needsUpdate = true;
         // store the version of the material
-        material["NEEDLE:lightmap-material-version"] = material.version;
+        material[$lightmapVersion] = material.version;
     }
 
     private onBeforeCompile = (shader: WebGLProgramParametersWithUniforms, _) => {
-        if (debug) console.log("Lightmaps, before compile\n", shader)
+        if (debug === "verbose") console.log("Lightmaps, before compile\n", shader)
         this.lightmapScaleOffsetUniform.value = this.lightmapScaleOffset;
         this.lightmapUniform.value = this.lightmapTexture;
         shader.uniforms.lightmapScaleOffset = this.lightmapScaleOffsetUniform;

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

@@ -114,8 +114,7 @@ export class PlayableDirector extends Behaviour {
 
     /** @internal */
     awake(): void {
-        if (debug)
-            console.log(this, this.playableAsset);
+        if (debug) console.log(`[Timeline] Awake '${this.name}'`, this);
 
         this.rebuildGraph();
 
@@ -134,6 +133,8 @@ export class PlayableDirector extends Behaviour {
 
     /** @internal */
     onEnable() {
+        if (debug) console.log("[Timeline] OnEnable", this.name, this.playOnAwake);
+
         for (const track of this._audioTracks) {
             track.onEnable?.();
         }
@@ -162,6 +163,8 @@ export class PlayableDirector extends Behaviour {
 
     /** @internal */
     onDisable(): void {
+        if (debug) console.log("[Timeline] OnDisable", this.name);
+
         this.stop();
         for (const track of this._audioTracks) {
             track.onDisable?.();
@@ -360,14 +363,17 @@ export class PlayableDirector extends Behaviour {
     private readonly _controlTracks: Array<Tracks.ControlTrackHandler> = [];
     private readonly _customTracks: Array<Tracks.TrackHandler> = [];
 
-    private readonly _allTracks: Array<Array<Tracks.TrackHandler>> = [
-        this._animationTracks,
-        this._audioTracks,
-        this._signalTracks,
-        this._markerTracks,
-        this._controlTracks,
-        this._customTracks
-    ];
+    private readonly _tracksArray: Array<Array<Tracks.TrackHandler>> = [];
+    private get _allTracks(): Array<Array<Tracks.TrackHandler>> {
+        this._tracksArray.length = 0;
+        this._tracksArray.push(this._animationTracks);
+        this._tracksArray.push(this._audioTracks);
+        this._tracksArray.push(this._signalTracks);
+        this._tracksArray.push(this._markerTracks);
+        this._tracksArray.push(this._controlTracks);
+        this._tracksArray.push(this._customTracks);
+        return this._tracksArray;
+    }
 
     /** should be called after evaluate if the director was playing */
     private invokePauseChangedMethodsOnTracks() {