@needle-tools/engine 4.11.1 → 4.11.3-next.2d2dff8

package/src/engine-components/Animation.ts

@@ -58,7 +58,7 @@ declare type AnimationIdentifier = AnimationClip | number | string | undefined;
 class Vec2 { x!: number; y!: number }
 
 /**
- * Animation component to play animations on a GameObject
+ * Animation component to play animations on a GameObject.
  * @category Animation and Sequencing
  * @group Components
  */
@@ -78,10 +78,10 @@ export class Animation extends Behaviour implements IAnimationComponent {
 
     /**
      * If true, the animation will start at a random time. This is used when the animation component is enabled
-     * @default true
+     * @default false
      */
     @serializable()
-    randomStartTime: boolean = true;
+    randomStartTime: boolean = false;
 
     /**
      * The animation min-max speed range
@@ -449,6 +449,7 @@ export class Animation extends Behaviour implements IAnimationComponent {
             action.time = 0;
         }
 
+
         // Apply speed
         if (options?.minMaxSpeed) {
             action.timeScale = Mathf.lerp(options.minMaxSpeed.x, options.minMaxSpeed.y, Math.random());

package/src/engine-components/AnimationCurve.ts

@@ -27,7 +27,10 @@ export class Keyframe {
 }
 
 /**
- * AnimationCurve is a representation of a curve that can be used to animate values over time.  
+ * AnimationCurve is a representation of a curve that can be used to animate values over time. 
+ * 
+ * @category Animation
+ * @group Utilities 
  */
 export class AnimationCurve {
 

package/src/engine-components/Animator.ts

@@ -39,8 +39,9 @@ export declare class PlayOptions {
 
 /** 
  * The Animator component plays and manages animations on a GameObject. 
- * It works with an AnimatorController to handle state transitions and animation blending.
- * A new AnimatorController can be created from code via `AnimatorController.createFromClips`.
+ * It works with an {@link AnimatorController} to handle state transitions and animation blending.
+ * A new AnimatorController can be created from code via `AnimatorController.createFromClips`.  
+ * 
  * @category Animation and Sequencing
  * @group Components
 */

package/src/engine-components/AnimatorController.ts

@@ -51,6 +51,9 @@ declare type CreateAnimatorControllerOptions = {
  * 
  * Use the static method {@link AnimatorController.createFromClips} to create
  * an animator controller from a set of animation clips.
+ * 
+ * @category Animation and Sequencing
+ * @group Utilities
  */
 export class AnimatorController {
 

package/src/engine-components/LookAtConstraint.ts

@@ -2,9 +2,14 @@ import { Object3D, Vector3 } from "three";
 
 import { serializable } from "../engine/engine_serialization_decorator.js";
 import { Behaviour } from "./Component.js";
+import type { OrbitControls } from "./OrbitControls.js";
 
 /**
- * A LookAtConstraint is used by OrbitControls to make the camera look at a target.
+ * A LookAtConstraint is used by OrbitControls to make the camera look at a target.  
+ * This component is used by {@link OrbitControls} internally.
+ * 
+ * @category Camera Controls
+ * @group Components
  */
 export class LookAtConstraint extends Behaviour {
 

package/src/engine-components/NeedleMenu.ts

@@ -9,6 +9,7 @@ import { Behaviour } from './Component.js';
  * 
  * Controls display options, button visibility, and menu positioning.
  * From code, you can access the menu via {@link Context.menu}. 
+ * 
  * @category User Interface
  * @group Components
  **/

package/src/engine-components/NestedGltf.ts

@@ -10,6 +10,9 @@ const debug = getParam("debugnestedgltf");
 
 /** The nested gltf is a component that is used to load a gltf file when the component becomes active (start)  
  * It will load the gltf file and instantiate it as a child of the parent of the GameObject that has this component
+ * 
+ * @category Asset Management
+ * @group Components
  */
 export class NestedGltf extends Behaviour {
 

package/src/engine-components/ReflectionProbe.ts

@@ -15,6 +15,10 @@ const $reflectionProbeKey = Symbol("reflectionProbeKey");
 const $originalMaterial = Symbol("original material");
 
 /**
+ * A ReflectionProbe provides reflection data to materials within its defined area.
+ * 
+ * - Sample: http://samples.needle.tools/reflection-probes
+ * 
  * @category Rendering
  * @group Components
  */

package/src/engine-components/RendererLightmap.ts

@@ -9,9 +9,13 @@ const debug = getParam("debuglightmaps");
 
 declare type MaterialWithLightmap = Material & { lightMap?: Texture | null };
 
-// this component is automatically added by the Renderer if the object has lightmap uvs AND we have a lightmap
-// for multimaterial objects GLTF exports a "Group" with the renderer component
-// and every child mesh is a material from unity
+
+/**
+ * This component is automatically added by the {@link Renderer} component if the object has lightmap uvs AND we have a lightmap.
+ * 
+ * @category Rendering
+ * @group Components
+ */
 export class RendererLightmap {
 
     get lightmap(): Texture | null {

package/src/engine-components/SeeThrough.ts

@@ -39,6 +39,9 @@ let i = 0;
  * Requires a Renderer component on the same object or a child object.
  * 
  * - Example https://see-through-walls-z23hmxbz1kjfjn.needle.run/
+ * 
+ * @category Rendering
+ * @group Components
  */
 export class SeeThrough extends Behaviour {
 
@@ -241,6 +244,7 @@ export class SeeThrough extends Behaviour {
 
                 const wasTransparent = mat.transparent;
                 const wasAlphaHash = mat.alphaHash;
+                const previousOpacity = mat.opacity;
 
                 mat.alphaHash = this.useAlphaHash;
 
@@ -253,7 +257,10 @@ export class SeeThrough extends Behaviour {
                     mat.transparent = mat.opacity >= 1 ? false : !this.useAlphaHash;
                 }
 
-                if (wasTransparent != mat.transparent || wasAlphaHash != mat.alphaHash) {
+                if (wasTransparent !== mat.transparent 
+                    || wasAlphaHash !== mat.alphaHash 
+                    || mat.opacity !== previousOpacity // MeshPhysicsMaterial needs that and maybe other materials too...
+                ) {
                     mat.needsUpdate = true;
                 }
             }

package/src/engine-components/Skybox.ts

@@ -120,6 +120,9 @@ ContextRegistry.registerCallback(ContextEvent.ContextCreationStart, () => {
  * ```ts
  * skybox.setSkybox("https://example.com/skybox.hdr");
  * ```
+ * 
+ * @category Rendering
+ * @group Components
  */
 export class RemoteSkybox extends Behaviour {
 

package/src/engine-components/SpriteRenderer.ts

@@ -9,6 +9,9 @@ import { Behaviour } from "./Component.js";
 const debug = getParam("debugspriterenderer");
 const showWireframe = getParam("wireframe");
 
+/**
+ * @internal
+ */
 class SpriteUtils {
 
     static cache: { [key: string]: BufferGeometry } = {};
@@ -82,7 +85,7 @@ function updateTextureIfNecessary(tex: Texture) {
 }
 
 /**
- * A sprite is a mesh that represents a 2D image
+ * A sprite is a mesh that represents a 2D image. Used by the {@link SpriteRenderer} to render 2D images in the scene.
  * @category Rendering
  * @group Components
  */
@@ -152,6 +155,9 @@ export class Sprite {
 
 const $spriteTexOwner = Symbol("spriteOwner");
 
+/**
+ * @category Sprites
+ */
 export class SpriteSheet {
 
     @serializable(Sprite)
@@ -162,6 +168,11 @@ export class SpriteSheet {
     }
 }
 
+/**
+ * Used by the {@link SpriteRenderer} to hold the sprite sheet and the currently active sprite index.
+ * 
+ * @category Sprites
+ */
 export class SpriteData {
 
     static create() {
@@ -246,7 +257,12 @@ export class SpriteData {
 }
 
 /**
- * The sprite renderer renders a sprite on a GameObject using an assigned spritesheet ({@link SpriteData}).  
+ * The sprite renderer renders a sprite on a GameObject using an assigned spritesheet ({@link SpriteData}).   
+ * 
+ * - Example: https://engine.needle.tools/samples/spritesheet-animation
+ * 
+ * @category Sprites
+ * @group Components
  */
 export class SpriteRenderer extends Behaviour {
 

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

@@ -39,9 +39,10 @@ import * as fflate from 'three/examples/jsm/libs/fflate.module.js';
 import { VERSION } from "../../../engine/engine_constants.js";
 import type { OffscreenCanvasExt } from '../../../engine/engine_shims.js';
 import { Progress } from '../../../engine/engine_time_utils.js';
-import { BehaviorExtension } from '../../api.js';
+// import { BehaviorExtension } from '../../api.js';
 import type { IUSDExporterExtension } from './Extension.js';
 import type { AnimationExtension } from './extensions/Animation.js';
+import { BehaviorExtension } from './extensions/behavior/Behaviour.js';
 import type { PhysicsExtension } from './extensions/behavior/PhysicsExtension.js';
 import {buildNodeMaterial} from './extensions/NodeMaterialConverter.js';
 
@@ -622,13 +623,13 @@ class USDZExporterContext {
 	output: string;
 	animations: AnimationClip[];
 
-	constructor( root: Object3D | undefined, exporter: USDZExporter, options: { 
+	constructor( root: Object3D | null | undefined, exporter: USDZExporter, options: { 
 		extensions?: Array<IUSDExporterExtension>, 
 		quickLookCompatible: boolean,
 		exportInvisible: boolean,
 	} ) {
 
-		this.root = root;
+		this.root = root || undefined;
 		this.exporter = exporter;
 		this.quickLookCompatible = options.quickLookCompatible;
 		this.exportInvisible = options.exportInvisible;
@@ -656,18 +657,28 @@ export type Anchoring = "plane" | "image" | "face" | "none"
 /**[documentation](https://developer.apple.com/documentation/arkit/usdz_schemas_for_ar/preliminary_anchoringapi/preliminary_planeanchoring_alignment) */
 export type Alignment = "horizontal" | "vertical" | "any";
 
-class USDZExporterOptions {
+type USDZExporterOptions = {
 	ar: {
 		anchoring: { type: Anchoring },
 		planeAnchoring: { alignment: Alignment },
-	} = { 
-		anchoring: { type: 'plane' },
-		planeAnchoring: { alignment: 'horizontal' }
-	};
-	quickLookCompatible: boolean = false;
-	extensions: any[] = [];
-	maxTextureSize: number = 4096;
-	exportInvisible: boolean = false;
+	}
+	quickLookCompatible: boolean;
+	extensions: Array<IUSDExporterExtension>;
+	maxTextureSize: number;
+	exportInvisible: boolean;
+}
+
+const getDefaultExporterOptions : () => USDZExporterOptions = () => {
+	return {
+		ar: {
+			anchoring: { type: 'plane' },
+			planeAnchoring: { alignment: 'horizontal' }
+		},
+		quickLookCompatible: false,
+		extensions: [],
+		maxTextureSize: 4096,
+		exportInvisible: false
+	}
 }
 
 // #region USDZExporter
@@ -675,7 +686,7 @@ class USDZExporterOptions {
 class USDZExporter {
 	debug: boolean;
 	pruneUnusedNodes: boolean;
-	sceneAnchoringOptions: USDZExporterOptions = new USDZExporterOptions();
+	sceneAnchoringOptions: USDZExporterOptions = getDefaultExporterOptions();
 	extensions: Array<IUSDExporterExtension> = [];
 	keepObject?: (object: Object3D) => boolean;
 	beforeWritingDocument?: () => void;
@@ -687,9 +698,10 @@ class USDZExporter {
 
 	}
 
-	async parse(scene: Object3D | undefined, options: USDZExporterOptions = new USDZExporterOptions()) {
+	async parse(scene: Object3D | null | undefined, options: USDZExporterOptions = getDefaultExporterOptions()) {
 
-		options = Object.assign( new USDZExporterOptions(), options );
+		// clone options to avoid modifying the original object
+		options = Object.assign({}, options );
 
 		this.sceneAnchoringOptions = options;
 		const context = new USDZExporterContext( scene, this, options );

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

@@ -483,7 +483,6 @@ export class USDZExporter extends Behaviour {
 
         Progress.report("export-usdz", "Invoking exporter.parse");
 
-        //@ts-ignore
         const arraybuffer = await exporter.parse(this.objectToExport, {
             ar: {
                 anchoring: {

package/src/engine-components/export/usdz/extensions/behavior/BehaviourComponents.ts

@@ -58,6 +58,13 @@ export class ChangeTransformOnClick extends Behaviour implements IPointerClickHa
         ensureRaycaster(this.gameObject);
     }
 
+    onPointerEnter() {
+        this.context.input.setCursor("pointer");
+    }
+    onPointerExit() {
+        this.context.input.unsetCursor("pointer");
+    }
+
     onPointerClick(args: PointerEventData) {
         args.use();
         if (this.coroutine) this.stopCoroutine(this.coroutine);
@@ -380,6 +387,13 @@ export class SetActiveOnClick extends Behaviour implements IPointerClickHandler,
         ensureRaycaster(this.gameObject);
     }
 
+    onPointerEnter() {
+        this.context.input.setCursor("pointer");
+    }
+    onPointerExit() {
+        this.context.input.unsetCursor("pointer");
+    }
+
     onPointerClick(args: PointerEventData) {
         args.use();
 
@@ -703,6 +717,13 @@ export class PlayAudioOnClick extends Behaviour implements IPointerClickHandler,
         }
     }
 
+
+    onPointerEnter() {
+        this.context.input.setCursor("pointer");
+    }
+    onPointerExit() {
+        this.context.input.unsetCursor("pointer");
+    }
     onPointerClick(args: PointerEventData) {
         args.use();
 
@@ -810,6 +831,13 @@ export class PlayAnimationOnClick extends Behaviour implements IPointerClickHand
         ensureRaycaster(this.gameObject);
     }
 
+
+    onPointerEnter() {
+        this.context.input.setCursor("pointer");
+    }
+    onPointerExit() {
+        this.context.input.unsetCursor("pointer");
+    }
     onPointerClick(args: PointerEventData) {
         args.use();
         if (!this.target) return;

package/src/engine-components/splines/Spline.ts

@@ -36,6 +36,9 @@ export class SplineData {
  * The spline is defined by an array of knots (SplineData) which define position, rotation and tangents.  
  * 
  * You can create a SplineContainer from an array of points using the static method 'createFromPoints'.
+ * 
+ * @category Splines
+ * @group Components
  */
 export class SplineContainer extends Behaviour {
 

package/src/engine-components/splines/SplineUtils.ts

@@ -3,7 +3,9 @@ import { Vector3 } from "three";
 import { Mathf } from "../../engine/engine_math.js";
 import { SplineContainer, SplineData } from "./Spline.js";
 
-
+/**
+ * @category Splines
+ */
 export namespace SplineUtils {
 
     /**

package/src/engine-components/splines/SplineWalker.ts

@@ -11,6 +11,9 @@ import { SplineContainer } from "./Spline.js";
  * Use this with a SplineContainer component.
  * 
  * - Example http://samples.needle.tools/splines
+ * 
+ * @category Splines
+ * @group Components
  */
 export class SplineWalker extends Behaviour {
 
@@ -114,12 +117,13 @@ export class SplineWalker extends Behaviour {
     /** @internal */
     onEnable(): void {
         window.addEventListener("pointerdown", this.onUserInput, { passive: true });
-        window.addEventListener("wheel", this.onUserInput, { passive: true });
+        // TODO: wheel event is also triggered for touch and it interrupts spline pull if it's an actual site scroll
+        this.context.domElement.addEventListener("wheel", this.onUserInput, { passive: true });
     }
     /** @internal */
     onDisable(): void {
         window.removeEventListener("pointerdown", this.onUserInput);
-        window.removeEventListener("wheel", this.onUserInput);
+        this.context.domElement.removeEventListener("wheel", this.onUserInput);
     }
     private onUserInput = () => {
         if (this.object?.contains(this.context.mainCamera)) {

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

@@ -2,15 +2,23 @@ import { serializable } from "../../engine/engine_serialization_decorator.js";
 import { getParam } from "../../engine/engine_utils.js";
 import { Behaviour } from "../Component.js";
 import { EventList } from "../EventList.js";
+import type { PlayableDirector } from "./PlayableDirector.js";
 
 const debug = getParam("debugsignals")
 
 
+/**
+ * Used to reference a signal asset in a SignalReceiver. This is internally used by the {@link SignalReceiverEvent}.
+ */
 export class SignalAsset {
     @serializable()
     guid!: string;
 }
 
+/**
+ * An event that links a signal to a reaction.
+ * Used internally by {@link SignalReceiver}.
+ */
 export class SignalReceiverEvent {
     @serializable(SignalAsset)
     signal!: SignalAsset;
@@ -19,7 +27,10 @@ export class SignalReceiverEvent {
 }
 
 /** SignalReceiver is a component that listens for signals and invokes a reaction when a signal is received. 
- * Signals can be added to a signal track on a timeline
+ * Signals can be added to a signal track on a {@link PlayableDirector}
+ * 
+ * @category Sequencing and Timelines
+ * @group Components
  */
 export class SignalReceiver extends Behaviour {
 
@@ -41,7 +52,7 @@ export class SignalReceiver extends Behaviour {
 
     /** @internal */
     awake(): void {
-        if(debug) console.log("SignalReceiver awake", this);
+        if (debug) console.log("SignalReceiver awake", this);
     }
 
     /** @internal */

package/src/engine-components/ui/Raycaster.ts

@@ -28,6 +28,12 @@ export abstract class Raycaster extends Behaviour {
 }
 
 
+/**
+ * A Raycaster that performs raycasting against its own GameObject.  
+ * 
+ * @category Interaction
+ * @group Components
+ */
 export class ObjectRaycaster extends Raycaster {
     private targets: Object3D[] | null = null;
     private raycastHits: Intersection[] = [];
@@ -65,6 +71,13 @@ export class ObjectRaycaster extends Raycaster {
     }
 }
 
+
+/**
+ * A Raycaster that performs raycasting against UI elements (objects with a CanvasRenderer component).  
+ * 
+ * @category UI
+ * @group Components
+ */
 export class GraphicRaycaster extends ObjectRaycaster {
     // eventCamera: Camera | null = null;
     // ignoreReversedGraphics: boolean = false;
@@ -76,6 +89,12 @@ export class GraphicRaycaster extends ObjectRaycaster {
     }
 }
 
+/**
+ * A Raycaster that performs sphere overlap raycasting for spatial grab interactions in XR.  
+ * 
+ * @category XR
+ * @group Components
+ */
 export class SpatialGrabRaycaster extends Raycaster {
 
     /**

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

@@ -1,4 +1,5 @@
 import { Vector2 } from "three";
+
 import { NEPointerEvent } from "../../engine/engine_input.js";
 import { onStart } from "../../engine/engine_lifecycle_api.js";
 import { addAttributeChangeCallback } from "../../engine/engine_utils.js";