@needle-tools/engine 4.9.3 → 4.10.0-beta

package/src/engine-components/OrbitControls.ts

@@ -2,18 +2,19 @@ import { Camera as Camera3, Object3D, PerspectiveCamera, Ray, Vector2, Vector3,
 import { OrbitControls as ThreeOrbitControls } from "three/examples/jsm/controls/OrbitControls.js";
 
 import { isDevEnvironment } from "../engine/debug/index.js";
+import { fitCamera, FitCameraOptions } from "../engine/engine_camera.fit.js";
 import { setCameraController } from "../engine/engine_camera.js";
 import { Gizmos } from "../engine/engine_gizmos.js";
 import { InputEventQueue, NEPointerEvent } from "../engine/engine_input.js";
 import { Mathf } from "../engine/engine_math.js";
 import { IRaycastOptions, RaycastOptions } from "../engine/engine_physics.js";
 import { serializable } from "../engine/engine_serialization_decorator.js";
-import { getBoundingBox, getTempVector, getWorldPosition } from "../engine/engine_three_utils.js";
+import { getTempVector, getWorldPosition } from "../engine/engine_three_utils.js";
 import type { ICameraController } from "../engine/engine_types.js";
 import { DeviceUtilities, getParam } from "../engine/engine_utils.js";
+import { NeedleEngineWebComponent } from "../engine/webcomponents/needle-engine.js";
 import { Camera } from "./Camera.js";
 import { Behaviour, GameObject } from "./Component.js";
-import { GroundProjectedEnv } from "./GroundProjection.js";
 import { LookAtConstraint } from "./LookAtConstraint.js";
 import { SyncedTransform } from "./SyncedTransform.js";
 import { type AfterHandleInputEvent, EventSystem, EventSystemEvents } from "./ui/EventSystem.js";
@@ -354,6 +355,9 @@ export class OrbitControls extends Behaviour implements ICameraController {
         if (debug) console.debug("OrbitControls", this);
         this._didSetTarget = 0;
         this._startedListeningToKeyEvents = false;
+        if ((this.context.domElement as NeedleEngineWebComponent).cameraControls === false) {
+            this.enabled = false;
+        }
     }
 
     /** @internal */
@@ -490,10 +494,13 @@ export class OrbitControls extends Behaviour implements ICameraController {
                 this._lastTimeClickOnBackground = this.context.time.time;
                 if (this.clickBackgroundToFitScene <= 1 || dt < this.clickBackgroundToFitScene * .15) {
                     this._clickOnBackgroundCount += 1;
-                    if (this._clickOnBackgroundCount >= this.clickBackgroundToFitScene - 1)
-                        this.fitCamera(this.context.scene.children, {
-                            immediate: false
+                    if (this._clickOnBackgroundCount >= this.clickBackgroundToFitScene - 1) {
+                        this.autoRotate = false;
+                        this.fitCamera({
+                            objects: this.context.scene,
+                            immediate: false,
                         });
+                    }
                 }
                 else {
                     this._clickOnBackgroundCount = 0;
@@ -530,7 +537,7 @@ export class OrbitControls extends Behaviour implements ICameraController {
     private _orbitStartAngle: number = 0;
     private _zoomStartDistance: number = 0;
     private onControlsChangeStarted = () => {
-        if(debug) console.debug("OrbitControls: Change started");
+        if (debug) console.debug("OrbitControls: Change started");
         if (this._controls) {
             this._orbitStartAngle = this._controls.getAzimuthalAngle() + this._controls.getPolarAngle();
             this._zoomStartDistance = this._controls.getDistance();
@@ -540,7 +547,7 @@ export class OrbitControls extends Behaviour implements ICameraController {
         }
     }
     private onControlsChangeEnded = () => {
-        if(debug) console.debug("OrbitControls: Change ended", { autoTarget: this.autoTarget });
+        if (debug) console.debug("OrbitControls: Change ended", { autoTarget: this.autoTarget });
         if (this._controls) {
             if (this.autoTarget) {
                 const newAngle = this._controls.getAzimuthalAngle() + this._controls.getPolarAngle();
@@ -989,242 +996,26 @@ export class OrbitControls extends Behaviour implements ICameraController {
     /** 
      * Fits the camera to show the objects provided (defaults to the scene if no objects are passed in) 
     */
-    fitCamera(options?: FitCameraOptions);
-    fitCamera(objects?: Object3D | Array<Object3D>, options?: Omit<FitCameraOptions, "objects">);
-    fitCamera(objectsOrOptions?: Object3D | Array<Object3D> | FitCameraOptions, options?: FitCameraOptions): void {
-
-        if (this.context.isInXR) {
-            // camera fitting in XR is not supported
-            console.warn('[OrbitControls] Can not fit camera while XR session is active');
-            return;
-        }
-
-        let objects: Object3D | Array<Object3D> | undefined = undefined;
-        // If the user passed in an array as first argument
-        if (Array.isArray(objectsOrOptions)) {
-            objects = objectsOrOptions;
-        }
-        // If the user passed in an object as first argument
-        else if (objectsOrOptions && "type" in objectsOrOptions) {
-            objects = objectsOrOptions;
-        }
-        // If the user passed in an object as first argument and options as second argument
-        else if (objectsOrOptions && typeof objectsOrOptions === "object") {
-            if (!(objectsOrOptions instanceof Object3D) && !Array.isArray(objectsOrOptions)) {
-                options = objectsOrOptions;
-                objects = options.objects;
-            }
-        }
-        // Ensure objects are setup correctly
-        if (objects && !Array.isArray(objects)) {
-            objects = [objects];
-        }
-        if (!Array.isArray(objects) || objects && objects.length <= 0) {
-            objects = this.context.scene.children;
-        }
-
-        // Make sure there's anything to fit to
-        if (!Array.isArray(objects) || objects.length <= 0) {
-            console.warn("No objects to fit camera to...");
-            return;
-        }
-
-        const camera = this._cameraObject as PerspectiveCamera;
-        const controls = this._controls as ThreeOrbitControls | null;
-
-        if (!camera || !controls) {
-            console.warn("No camera or controls found to fit camera to objects...");
-            return;
-        }
-        if (!options) options = {}
-        const { immediate = false, centerCamera, cameraNearFar = "auto", fitOffset = 1.1, fov = camera?.fov } = options;
-        const size = new Vector3();
-        const center = new Vector3();
-        // TODO would be much better to calculate the bounds in camera space instead of world space - 
-        // we would get proper view-dependant fit.
-        // Right now it's independent from where the camera is actually looking from,
-        // and thus we're just getting some maximum that will work for sure.
-        const box = getBoundingBox(objects, undefined, this._camera?.threeCamera?.layers);
-        const boxCopy = box.clone();
-        box.getCenter(center);
-
-        const box_size = new Vector3();
-        box.getSize(box_size);
-
-        // project this box into camera space
-        camera.updateMatrixWorld();
-        box.applyMatrix4(camera.matrixWorldInverse);
-
-        box.getSize(size);
-        box.setFromCenterAndSize(center, size);
-        if (Number.isNaN(size.x) || Number.isNaN(size.y) || Number.isNaN(size.z)) {
-            console.warn("Camera fit size resultet in NaN", camera, box, [...objects]);
-            return;
-        }
-        if (size.length() <= 0.0000000001) {
-            if (debugCameraFit) console.warn("Camera fit size is zero", box, [...objects]);
-            return;
-        }
-
-        const verticalFov = fov;
-        const horizontalFov = 2 * Math.atan(Math.tan(verticalFov * Math.PI / 360 / 2) * camera.aspect) / Math.PI * 360;
-        const fitHeightDistance = size.y / (2 * Math.atan(Math.PI * verticalFov / 360));
-        const fitWidthDistance = size.x / (2 * Math.atan(Math.PI * horizontalFov / 360));
-
-        const distance = fitOffset * Math.max(fitHeightDistance, fitWidthDistance) + size.z / 2;
-
-        if (debugCameraFit) {
-            console.log("Fit camera to objects", { fitHeightDistance, fitWidthDistance, distance, verticalFov, horizontalFov });
-        }
-
-        this.maxZoom = distance * 10;
-        this.minZoom = distance * 0.01;
-
-        const verticalOffset = 0.05;
-        const lookAt = center.clone();
-        lookAt.y -= size.y * verticalOffset;
-        if (options.targetOffset) {
-            if (options.targetOffset.x !== undefined) lookAt.x += options.targetOffset.x;
-            if (options.targetOffset.y !== undefined) lookAt.y += options.targetOffset.y;
-            if (options.targetOffset.z !== undefined) lookAt.z += options.targetOffset.z;
-        }
-        if (options.relativeTargetOffset) {
-            if (options.relativeTargetOffset.x !== undefined) lookAt.x += options.relativeTargetOffset.x * size.x;
-            if (options.relativeTargetOffset.y !== undefined) lookAt.y += options.relativeTargetOffset.y * size.y;
-            if (options.relativeTargetOffset.z !== undefined) lookAt.z += options.relativeTargetOffset.z * size.z;
-        }
-        this.setLookTargetPosition(lookAt, immediate);
-        this.setFieldOfView(options.fov, immediate);
-
-        if (cameraNearFar == undefined || cameraNearFar == "auto") {
-            // Check if the scene has a GroundProjectedEnv and include the scale to the far plane so that it doesnt cut off
-            const groundprojection = GameObject.findObjectOfType(GroundProjectedEnv);
-            const groundProjectionRadius = groundprojection ? groundprojection.radius : 0;
-            const boundsMax = Math.max(box_size.x, box_size.y, box_size.z, groundProjectionRadius);
-            // TODO: this doesnt take the Camera component nearClipPlane into account
-            camera.near = (distance / 100);
-            camera.far = boundsMax + distance * 10;
-            camera.updateProjectionMatrix();
-
-            // adjust maxZoom so that the ground projection radius is always inside
-            if (groundprojection) {
-                this.maxZoom = Math.max(Math.min(this.maxZoom, groundProjectionRadius * 0.5), distance);
-            }
-        }
-
-        // ensure we're not clipping out of the current zoom level just because we're fitting
-        const currentZoom = controls.getDistance();
-        if (currentZoom < this.minZoom) this.minZoom = currentZoom * 0.9;
-        if (currentZoom > this.maxZoom) this.maxZoom = currentZoom * 1.1;
-
-        const direction = center.clone();
-        if (options.fitDirection) {
-            direction.sub(new Vector3().copy(options.fitDirection).multiplyScalar(1_000_000));
-        }
-        else {
-            direction.sub(camera.worldPosition);
-        }
-        if (centerCamera === "y")
-            direction.y = 0;
-        direction.normalize();
-        direction.multiplyScalar(distance);
-        if (centerCamera === "y")
-            direction.y += -verticalOffset * 4 * distance;
-
-        let cameraLocalPosition = center.clone().sub(direction);
-        if (options.cameraOffset) {
-            if (options.cameraOffset.x !== undefined) cameraLocalPosition.x += options.cameraOffset.x;
-            if (options.cameraOffset.y !== undefined) cameraLocalPosition.y += options.cameraOffset.y;
-            if (options.cameraOffset.z !== undefined) cameraLocalPosition.z += options.cameraOffset.z;
-        }
-        if (options.relativeCameraOffset) {
-            if (options.relativeCameraOffset.x !== undefined) cameraLocalPosition.x += options.relativeCameraOffset.x * size.x;
-            if (options.relativeCameraOffset.y !== undefined) cameraLocalPosition.y += options.relativeCameraOffset.y * size.y;
-            if (options.relativeCameraOffset.z !== undefined) cameraLocalPosition.z += options.relativeCameraOffset.z * size.z;
-        }
-        if (camera.parent) {
-            cameraLocalPosition = camera.parent.worldToLocal(cameraLocalPosition);
-        }
-        this.setCameraTargetPosition(cameraLocalPosition, immediate);
-
-        if (debugCameraFit || options.debug) {
-            Gizmos.DrawWireBox3(box, 0xffff33, 10);
-            Gizmos.DrawWireBox3(boxCopy, 0x00ff00, 10);
-
-            if (!this._haveAttachedKeyboardEvents && debugCameraFit) {
-                this._haveAttachedKeyboardEvents = true;
-                document.body.addEventListener("keydown", (e) => {
-                    if (e.code === "KeyF") {
-                        // random fov for easier debugging of fov-based fitting
-                        let fov: number | undefined = undefined;
-                        if (this._cameraObject instanceof PerspectiveCamera) fov = (Math.random() * Math.random()) * 170 + 10;
-                        this.fitCamera({ objects, fitOffset, immediate: false, fov });
-                    }
-                    if (e.code === "KeyV") {
-                        if (this._cameraObject instanceof PerspectiveCamera) this._cameraObject.fov = 60;
-                    }
-                });
-            }
-        }
-
+    fitCamera(options?: OrbitFitCameraOptions): void {
+        const res = fitCamera({
+            ...options,
+            autoApply: false,
+            context: this.context,
+            camera: this._cameraObject as Camera3,
+            currentZoom: this._controls?.getDistance() || undefined,
+            minZoom: this.minZoom,
+            maxZoom: this.maxZoom,
+        });
+        if (!res) return;
+        this.setLookTargetPosition(res.lookAt, options?.immediate || false);
+        this.setCameraTargetPosition(res.position, options?.immediate || false);
+        this.setFieldOfView(options?.fov, options?.immediate || false);
         this.onBeforeRender();
-        // controls.update(); // this is not enough when calling fitCamera({immediate:true}) in an interval
     }
 
     private _haveAttachedKeyboardEvents: boolean = false;
 }
 
-
-/**
- * Options for fitting the camera to the scene. Used in {@link OrbitControls.fitCamera}
- */
-export type FitCameraOptions = {
-    /** When enabled debug rendering will be shown */
-    debug?: boolean,
-    /**
-     * The objects to fit the camera to. If not provided the scene children will be used
-     */
-    objects?: Object3D[] | Object3D;
-    /** If true the camera will move immediately to the new position, otherwise it will lerp 
-     * @default false
-     */
+type OrbitFitCameraOptions = FitCameraOptions & {
     immediate?: boolean,
-
-    /** Fit offset: A factor to multiply the distance to the objects by
-     * @default 1.1
-     */
-    fitOffset?: number,
-
-    /** The direction from which the camera should be fitted in worldspace. If not defined the current camera's position will be used */
-    fitDirection?: Vector3Like,
-
-    /** If set to "y" the camera will be centered in the y axis */
-    centerCamera?: "none" | "y",
-    /** Set to 'auto' to update the camera near or far plane based on the fitted-objects bounds */
-    cameraNearFar?: "keep" | "auto",
-
-    /**
-     * Offset the camera position in world space
-     */
-    cameraOffset?: Partial<Vector3Like>,
-    /**
-     * Offset the camera position relative to the size of the objects being focused on (e.g. x: 0.5).  
-     * Value range: -1 to 1
-     */
-    relativeCameraOffset?: Partial<Vector3Like>,
-
-    /**
-     * Offset the camera target position in world space
-     */
-    targetOffset?: Partial<Vector3Like>,
-    /**
-     * Offset the camera target position relative to the size of the objects being focused on.  
-     * Value range: -1 to 1
-     */
-    relativeTargetOffset?: Partial<Vector3Like>,
-
-    /**
-     * Field of view (FOV) for the camera
-     */
-    fov?: number,
-}
+}

package/src/engine-components/Renderer.ts

@@ -304,10 +304,12 @@ export class Renderer extends Behaviour implements IRenderer {
         return this._sharedMeshes;
     }
 
+    // @ts-ignore
     get sharedMaterial(): SharedMaterial {
-        return this.sharedMaterials[0] as SharedMaterial;
+        return (this.sharedMaterials?.[0]) as SharedMaterial;
     }
 
+    // @ts-ignore
     set sharedMaterial(mat: SharedMaterial) {
         const cur = this.sharedMaterials[0];
         if (cur === mat) return;
@@ -315,12 +317,12 @@ export class Renderer extends Behaviour implements IRenderer {
         this.applyLightmapping();
     }
 
-    /**@deprecated please use sharedMaterial */
+    /**@deprecated Use sharedMaterial */
     get material(): SharedMaterial {
-        return this.sharedMaterials[0] as SharedMaterial;
+        return this.sharedMaterials?.[0] as SharedMaterial;
     }
 
-    /**@deprecated please use sharedMaterial */
+    /**@deprecated Use sharedMaterial */
     set material(mat: SharedMaterial) {
         this.sharedMaterial = mat;
     }

package/src/engine-components/api.ts

@@ -53,7 +53,6 @@ import "./AnimationUtilsAutoplay.js"
 
 export { DragMode } from "./DragControls.js";
 export type { DropListenerNetworkEventArguments, DropListenerOnDropArguments } from "./DropListener.js";
-export { type FitCameraOptions } from "./OrbitControls.js";
 export * from "./particlesystem/api.js"
 export * from "./splines/index.js";
 export * from "./web/index.js";

package/src/engine-components/codegen/components.ts

@@ -169,6 +169,7 @@ export { SignalReceiverEvent } from "../timeline/SignalAsset.js";
 export { SignalReceiver } from "../timeline/SignalAsset.js";
 export { AnimationTrackHandler } from "../timeline/TimelineTracks.js";
 export { AudioTrackHandler } from "../timeline/TimelineTracks.js";
+export { MarkerTrackHandler } from "../timeline/TimelineTracks.js";
 export { SignalTrackHandler } from "../timeline/TimelineTracks.js";
 export { ControlTrackHandler } from "../timeline/TimelineTracks.js";
 export { TransformGizmo } from "../TransformGizmo.js";
@@ -205,6 +206,7 @@ export { VideoPlayer } from "../VideoPlayer.js";
 export { Voip } from "../Voip.js";
 export { ClickThrough } from "../web/Clickthrough.js";
 export { CursorFollow } from "../web/CursorFollow.js";
+export { HoverAnimation } from "../web/HoverAnimation.js";
 export { ScrollFollow } from "../web/ScrollFollow.js";
 export { Avatar } from "../webxr/Avatar.js";
 export { XRControllerFollow } from "../webxr/controllers/XRControllerFollow.js";

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

@@ -293,6 +293,41 @@ export class PlayableDirector extends Behaviour {
         return this._audioTracks;
     }
 
+    /**
+     * @returns all signal tracks of the timeline
+     */
+    get signalTracks(): Tracks.SignalTrackHandler[] {
+        return this._signalTracks;
+    }
+
+    /**
+     * @returns all marker tracks of the timeline
+     */
+    get markerTracks(): Tracks.MarkerTrackHandler[] {
+        return this._markerTracks;
+    }
+
+    /**
+     * Iterates over all markers of the timeline, optionally filtering by type
+     * 
+     * @example
+     * ```ts
+     * // Iterate over all ScrollMarkers in the timeline
+     * for (const marker of director.foreachMarker<{selector:string}>("ScrollMarker")) {
+     *   console.log(marker.time, marker.selector);
+     * }
+     * ```
+     * 
+     */
+    *foreachMarker<T extends Record<string, any>>(type: string | null = null): Generator<(T & Models.MarkerModel)> {
+        for (const track of this._markerTracks) {
+            for (const marker of track.foreachMarker<T>(type)) {
+                yield marker as T & Models.MarkerModel;
+            }
+        }
+    }
+
+
     private _guidsMap?: GuidsMap;
     /** @internal */
     resolveGuids(map: GuidsMap) {
@@ -309,16 +344,18 @@ export class PlayableDirector extends Behaviour {
     private _time: number = 0;
     private _duration: number = 0;
     private _weight: number = 1;
-    private _animationTracks: Array<Tracks.AnimationTrackHandler> = [];
-    private _audioTracks: Array<Tracks.AudioTrackHandler> = [];
-    private _signalTracks: Array<Tracks.SignalTrackHandler> = [];
-    private _controlTracks: Array<Tracks.ControlTrackHandler> = [];
-    private _customTracks: Array<Tracks.TrackHandler> = [];
-
-    private _allTracks: Array<Array<Tracks.TrackHandler>> = [
+    private readonly _animationTracks: Array<Tracks.AnimationTrackHandler> = [];
+    private readonly _audioTracks: Array<Tracks.AudioTrackHandler> = [];
+    private readonly _signalTracks: Array<Tracks.SignalTrackHandler> = [];
+    private readonly _markerTracks: Array<Tracks.MarkerTrackHandler> = [];
+    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
     ];
@@ -335,7 +372,7 @@ export class PlayableDirector extends Behaviour {
         }
     }
 
-    private *internalUpdate() {
+    private * internalUpdate() {
         while (this._isPlaying && this.activeAndEnabled) {
             if (!this._isPaused && this._isPlaying) {
                 this._time += this.context.time.deltaTime * this.speed;
@@ -415,26 +452,18 @@ export class PlayableDirector extends Behaviour {
             }
         }
 
-        // When timeline reaches the end "stop()" is called which is evaluating with time 0
-        // We don't want to re-evaluate the animation then in case the timeline is blended with the Animator
-        // e.g then the timeline animation at time 0 is 100% applied on top of the animator animation
-        if (!this._isStopping) {
-            for (const handler of this._animationTracks) {
+        for (const track of this._allTracks) {
+            for (const handler of track) {
+                // When timeline reaches the end "stop()" is called which is evaluating with time 0
+                // We don't want to re-evaluate the animation then in case the timeline is blended with the Animator
+                // e.g then the timeline animation at time 0 is 100% applied on top of the animator animation
+
+                if (this._isStopping && handler instanceof Tracks.AnimationTrackHandler) {
+                    continue;
+                }
                 handler.evaluate(time);
             }
         }
-        for (const handler of this._audioTracks) {
-            handler.evaluate(time);
-        }
-        for (const sig of this._signalTracks) {
-            sig.evaluate(time);
-        }
-        for (const ctrl of this._controlTracks) {
-            ctrl.evaluate(time);
-        }
-        for (const cust of this._customTracks) {
-            cust.evaluate(time);
-        }
     }
 
     private resolveBindings() {
@@ -630,26 +659,42 @@ export class PlayableDirector extends Behaviour {
                 }
             }
             else if (track.type === Models.TrackType.Marker) {
-                const signalHandler: Tracks.SignalTrackHandler = new Tracks.SignalTrackHandler();
-                signalHandler.director = this;
-                signalHandler.track = track;
+
                 if (track.markers) {
+                    // For the marker track we create both a signal track handler AND a markertrack handler because a marker track can have signals and markers
+                    const signalHandler: Tracks.SignalTrackHandler = new Tracks.SignalTrackHandler();
+                    signalHandler.director = this;
+                    signalHandler.track = track;
+
+                    const markerHandler: Tracks.MarkerTrackHandler = new Tracks.MarkerTrackHandler();
+                    markerHandler.director = this;
+                    markerHandler.track = track;
+
                     for (const marker of track.markers) {
                         switch (marker.type) {
                             case Models.MarkerType.Signal:
                                 signalHandler.models.push(marker as Models.SignalMarkerModel);
                                 signalHandler.didTrigger.push(false);
                                 break;
+                            default:
+                                markerHandler.models.push(marker);
+                                break;
                         }
                     }
-                }
-                if (signalHandler !== null && signalHandler.models.length > 0) {
-                    const rec = GameObject.getComponent(this.gameObject, SignalReceiver);
-                    if (rec) {
-                        signalHandler.receivers.push(rec);
-                        this._signalTracks.push(signalHandler);
+
+                    if (signalHandler !== null && signalHandler.models.length > 0) {
+                        const rec = GameObject.getComponent(this.gameObject, SignalReceiver);
+                        if (rec) {
+                            signalHandler.receivers.push(rec);
+                            this._signalTracks.push(signalHandler);
+                        }
+                    }
+
+                    if (markerHandler !== null && markerHandler.models.length > 0) {
+                        this._markerTracks.push(markerHandler);
                     }
                 }
+
             }
             else if (track.type === Models.TrackType.Signal) {
                 const handler = new Tracks.SignalTrackHandler();

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

@@ -1,4 +1,5 @@
 import { AnimationClip, Object3D, Quaternion, Vector3 } from "three";
+import { Behavior } from "three-mesh-ui";
 
 export declare type TimelineAssetModel = {
     name: string;
@@ -90,3 +91,5 @@ export declare class SignalMarkerModel extends MarkerModel {
     emitOnce: boolean;
     asset: string;
 }
+
+export type ScrollMarkerModel = MarkerModel & { selector: string };

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

@@ -830,6 +830,28 @@ export class AudioTrackHandler extends TrackHandler {
     }
 }
 
+export class MarkerTrackHandler extends TrackHandler {
+    models: Array<Models.MarkerModel & Record<string, any>> = [];
+    isDirty = true;
+
+    *foreachMarker<T>(type: string | null = null) {
+        for (const model of this.models) {
+            if (model && model.type === type) yield model as T;
+        }
+    }
+
+    onEnable() {
+        this.isDirty = true;
+    }
+
+    evaluate(_time: number) {
+        if (this.isDirty) {
+            this.isDirty = false;
+            this.models.sort((a, b) => a.time - b.time);
+        }
+    }
+}
+
 export class SignalTrackHandler extends TrackHandler {
     models: Models.SignalMarkerModel[] = [];
     didTrigger: boolean[] = [];

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

@@ -21,6 +21,9 @@ onStart(ctx => {
  * - Alternatively, add the `clickthrough` attribute to the `<needle-engine>` HTML element (e.g. `<needle-engine clickthrough></needle-engine>`).
  * 
  * @link Example https://stackblitz.com/~/github.com/needle-engine/sample-3d-over-html
+ * @category Web
+ * @group Components
+ * @component
  */
 export class ClickThrough extends Behaviour {
 

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

@@ -4,6 +4,9 @@ import { Behaviour } from "../Component.js";
 
 /**
  * The CursorFollow component makes the object follow the cursor (or touch) position on screen.
+ * @category Web
+ * @group Components
+ * @component
  */
 export class CursorFollow extends Behaviour {