@needle-tools/engine 4.11.4 → 4.11.5-beta

package/src/engine/engine_camera.fit.ts

@@ -1,6 +1,7 @@
 import { Camera, Object3D, PerspectiveCamera, Vector3, Vector3Like } from "three";
 
 import { GroundProjectedEnv } from "../engine-components/GroundProjection.js";
+import type { OrbitControls } from "../engine-components/OrbitControls.js";
 import { findObjectOfType } from "./engine_components.js";
 import { Context } from "./engine_context.js";
 import { Gizmos } from "./engine_gizmos.js";
@@ -9,7 +10,10 @@ import { NeedleXRSession } from "./xr/NeedleXRSession.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 +35,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 +53,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 +91,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 +103,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/engine_utils_qrcode.ts

@@ -166,7 +166,7 @@ async function internalRenderQRCodeOverlays(canvas: HTMLCanvasElement, args: { s
         haveLogo = await new Promise((resolve, _reject) => {
             image.onload = () => resolve(true);
             image.onerror = (err) => {
-                let errorUrl = logoSrc !== needleLogoOnlySVG ? "'" + logoSrc + "'" : null;
+                const errorUrl = logoSrc !== needleLogoOnlySVG ? "'" + logoSrc + "'" : null;
                 console.error("[QR Code] Error loading logo image for QR code", errorUrl, isDevEnvironment() ? err : "");
                 resolve(false);
             };

package/src/engine/extensions/NEEDLE_components.ts

@@ -2,12 +2,13 @@ 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/webcomponents/buttons.ts

@@ -8,7 +8,9 @@ import { getIconElement } from "./icons.js";
  * Use the ButtonsFactory to create buttons with icons and functionality   
  * Get access to the default buttons by using `ButtonsFactory.instance`  
  * The factory will create the buttons if they don't exist yet, and return the existing ones if they do (this allows you to reparent or modify created buttons) 
- */
+ * 
+ * @category HTML
+*/
 export class ButtonsFactory {
 
     private static _instance?: ButtonsFactory;

package/src/engine/webcomponents/needle menu/needle-menu.ts

@@ -48,11 +48,13 @@ export declare type ButtonInfo = {
 }
 
 /**
- * The NeedleMenu is a menu that can be displayed in the needle engine webcomponent or in VR/AR sessions.
+ * The NeedleMenu is a menu that can be displayed in the needle engine webcomponent or in VR/AR sessions.  
+ * 
  * The menu can be used to add buttons to the needle engine that can be used to interact with the application.  
- * The menu can be positioned at the top or the bottom of the needle engine webcomponent  
  * 
- * @example Create a button using the NeedleMenu
+ * The menu can be positioned at the top or the bottom of the <needle-engine> webcomponent.
+ * 
+ * @example Add a new button using the NeedleMenu
  * ```typescript
  * onStart(ctx => {
  *   ctx.menu.appendChild({ 
@@ -76,6 +78,20 @@ export declare type ButtonInfo = {
  *    }
  * }, "*");
  * ```
+ * 
+ * @example Access the menu from a component
+ * ```typescript
+ * import { Behaviour, OnStart } from '@needle-tools/engine';
+ * 
+ * export class MyComponent extends Behaviour {
+ * 
+ *   start() {
+ *    this.context.menu.appendChild({ ... });
+ *   }
+ * }
+ * ```
+ * 
+ * @category HTML
  */
 export class NeedleMenu {
     private readonly _context: Context;
@@ -909,6 +925,27 @@ export class NeedleMenuElement extends HTMLElement {
             }
         }
     }
+    /**
+     * Appends a button or HTML element to the needle-menu options.
+     * @param node a Node or ButtonInfo to create a button from
+     * @returns the appended Node
+     * 
+     * @example Append a button
+     * ```javascript
+     * const button = document.createElement("button");
+     * button.textContent = "Click Me";
+     * needleMenu.appendChild(button);
+     * ```
+     * @example Append a button using ButtonInfo
+     * ```javascript
+     * needleMenu.appendChild({
+     *    label: "Click Me",
+     *    onClick: () => { alert("Button clicked!"); },
+     *    icon: "info",
+     *    title: "This is a button",
+     * });
+     * ```
+     */
     appendChild<T extends Node>(node: T | ButtonInfo): T {
 
         if (!(node instanceof Node)) {

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() {