@needle-tools/engine 4.14.0-next.b2e3b1a → 4.14.0

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

@@ -13,7 +13,7 @@ import { AudioSource } from "../../../../AudioSource.js";
 import { Behaviour, GameObject } from "../../../../Component.js";
 import { Rigidbody } from "../../../../RigidBody.js";
 import type { IPointerClickHandler, PointerEventData } from "../../../../ui/PointerEvents.js";
-import { ObjectRaycaster,Raycaster } from "../../../../ui/Raycaster.js";
+
 import { makeNameSafeForUSD,USDDocument, USDObject, USDZExporterContext } from "../../ThreeUSDZExporter.js";
 import { AnimationExtension, RegisteredAnimationInfo, type UsdzAnimation } from "../Animation.js";
 import { AudioExtension } from "./AudioExtension.js";
@@ -22,32 +22,32 @@ import { ActionBuilder, ActionModel, BehaviorModel, EmphasizeActionMotionType,Gr
 
 const debug = getParam("debugusdzbehaviours");
 
-function ensureRaycaster(obj: GameObject) {
-    if (!obj) return;
-    if (!obj.getComponentInParent(Raycaster)) {
-        if (isDevEnvironment())
-            console.debug("Raycaster on \"" + obj.name + "\" was automatically added, because no raycaster was found in the parent hierarchy.")
-        obj.addComponent(ObjectRaycaster);
-    }
-}
-
 /**
- * Make the object move to the target object's transform when clicked.
+ * Moves an object to the target object's transform when clicked.
+ * Works in the browser and in USDZ/QuickLook (Everywhere Actions).
+ *
+ * @see {@link SetActiveOnClick}to toggle visibility of objects when clicked
+ * @see {@link PlayAnimationOnClick} to play animations when clicked
+ * @see [Everywhere Actions](https://engine.needle.tools/docs/everywhere-actions)
  * @summary Moves an object to a target transform upon click
  * @category Everywhere Actions
  * @group Components
  */
 export class ChangeTransformOnClick extends Behaviour implements IPointerClickHandler, UsdzBehaviour {
 
+    /** The object to move. */
     @serializable(Object3D)
     object?: Object3D;
 
+    /** The target object whose transform to move to. */
     @serializable(Object3D)
     target?: Object3D;
 
+    /** The duration of the movement animation in seconds. */
     @serializable()
     duration: number = 1;
 
+    /** If true, the motion is relative to the object's current transform instead of moving to the target's absolute position. */
     @serializable()
     relativeMotion: boolean = false;
 
@@ -57,10 +57,6 @@ export class ChangeTransformOnClick extends Behaviour implements IPointerClickHa
     private targetRot = new Quaternion();
     private targetScale = new Vector3();
 
-    start(): void {
-        ensureRaycaster(this.gameObject);
-    }
-
     onPointerEnter() {
         this.context.input.setCursor("pointer");
     }
@@ -189,7 +185,15 @@ export class ChangeTransformOnClick extends Behaviour implements IPointerClickHa
 }
 
 /**
- * Change the material of objects when clicked.
+ * Switches the material of objects in the scene when clicked.
+ * Works in the browser and in USDZ/QuickLook (Everywhere Actions).
+ * 
+ * Finds all objects in the scene that use `materialToSwitch` and replaces it with `variantMaterial`.
+ * Multiple `ChangeMaterialOnClick` components using the same `materialToSwitch` can be combined to create a material selection UI.
+ *
+ * @see {@link SetActiveOnClick} to toggle visibility of objects when clicked
+ * @see {@link PlayAnimationOnClick} to play animations when clicked
+ * @see [Everywhere Actions](https://engine.needle.tools/docs/everywhere-actions)
  * @summary Changes the material of objects when clicked
  * @category Everywhere Actions
  * @group Components
@@ -218,7 +222,6 @@ export class ChangeMaterialOnClick extends Behaviour implements IPointerClickHan
     start(): void {
         // initialize the object list
         this._objectsWithThisMaterial = this.objectsWithThisMaterial;
-        ensureRaycaster(this.gameObject);
         if (isDevEnvironment() && this._objectsWithThisMaterial.length <= 0) {
             console.warn("ChangeMaterialOnClick: No objects found with material \"" + this.materialToSwitch?.name + "\"");
         }
@@ -345,7 +348,7 @@ export class ChangeMaterialOnClick extends Behaviour implements IPointerClickHan
         );
         ChangeMaterialOnClick._parallelStartHiddenActions.push(...myVariants);
         if (!ChangeMaterialOnClick._startHiddenBehaviour) {
-            ChangeMaterialOnClick._startHiddenBehaviour =  
+            ChangeMaterialOnClick._startHiddenBehaviour =
                 new BehaviorModel("StartHidden_" + this.selfModel.name,
                     TriggerBuilder.sceneStartTrigger(),
                     ActionBuilder.fadeAction(ChangeMaterialOnClick._parallelStartHiddenActions, fadeDuration, false));
@@ -381,29 +384,37 @@ export class ChangeMaterialOnClick extends Behaviour implements IPointerClickHan
 }
 
 /**
- * Set the active state of an object when clicked.
+ * Shows or hides a target object when this object is clicked.
+ * Works in the browser and in USDZ/QuickLook (Everywhere Actions).
+ * 
+ * Optionally hides itself after being clicked (`hideSelf`), or toggles the target's visibility on each click (`toggleOnClick`).
+ *
+ * @see {@link HideOnStart}to hide an object when the scene starts
+ * @see {@link PlayAnimationOnClick} to play animations when clicked
+ * @see {@link ChangeMaterialOnClick} to change material when clicked
+ * @see [Everywhere Actions](https://engine.needle.tools/docs/everywhere-actions)
  * @summary Sets the active state of an object when clicked
  * @category Everywhere Actions
  * @group Components
  */
 export class SetActiveOnClick extends Behaviour implements IPointerClickHandler, UsdzBehaviour {
 
+    /** The target object to show or hide. */
     @serializable(Object3D)
     target?: Object3D;
 
+    /** If true, the target's visibility will be toggled on each click. When enabled, `hideSelf` and `targetState` are ignored. */
     @serializable()
     toggleOnClick: boolean = false;
 
+    /** The visibility state to apply to the target when clicked. Only used when `toggleOnClick` is false. */
     @serializable()
     targetState: boolean = true;
 
+    /** If true, this object will hide itself after being clicked. Only used when `toggleOnClick` is false. */
     @serializable()
     hideSelf: boolean = true;
 
-    start(): void {
-        ensureRaycaster(this.gameObject);
-    }
-
     onPointerEnter() {
         this.context.input.setCursor("pointer");
     }
@@ -416,7 +427,7 @@ export class SetActiveOnClick extends Behaviour implements IPointerClickHandler,
 
         if (!this.toggleOnClick && this.hideSelf)
             this.gameObject.visible = false;
-        
+      
         if (this.target)
             this.target.visible = this.toggleOnClick ? !this.target.visible : this.targetState;
     }
@@ -442,7 +453,7 @@ export class SetActiveOnClick extends Behaviour implements IPointerClickHandler,
 
     beforeCreateDocument() {
         if (!this.target) return;
-        
+      
         // need to cache on the object itself, because otherwise different actions would override each other's visibility state
         // TODO would probably be better to have this somewhere on the exporter, not on this component
         if (this.gameObject[SetActiveOnClick.wasVisible] === undefined)
@@ -503,7 +514,7 @@ export class SetActiveOnClick extends Behaviour implements IPointerClickHandler,
                 // It's much easier to reason about nested actions when we're not duplicating tons of hierarchy...
                 // We can probably only do a shallow clone when the tapped object has geometry of its own, otherwise
                 // we end up with nothing to tap on.
-                
+              
                 // Option A: we deep clone ourselves. This makes hierarchical cases and nested behaviours really complex.
                 // We do this currently when the object doesn't have any geometry.
                 if (!this.selfModelClone.geometry) {
@@ -522,11 +533,11 @@ export class SetActiveOnClick extends Behaviour implements IPointerClickHandler,
                         clone.name += "_toggle" + (SetActiveOnClick.clonedToggleIndex++);
                         originalModel.add(clone);
                         this.gameObject[SetActiveOnClick.toggleClone] = clone;
-                        
+                      
                         console.warn("USDZExport: Toggle " + this.gameObject.name + " doesn't have geometry. It will be deep cloned and nested behaviours will likely not work.");
                     }
                     const clonedSelfModel = this.gameObject[SetActiveOnClick.toggleClone];
-                    
+                  
                     if (!this.gameObject[SetActiveOnClick.reverseToggleClone]) {
                         const clone = this.selfModelClone.clone();
                         clone.setMatrix(new Matrix4());
@@ -578,7 +589,7 @@ export class SetActiveOnClick extends Behaviour implements IPointerClickHandler,
                     TriggerBuilder.tapTrigger(selfModel),
                     ActionBuilder.parallel(...toggleSequence)
                 ));
-                
+              
                 const reverseSequence: ActionModel[] = [];
                 reverseSequence.push(ActionBuilder.fadeAction(this.toggleModel, 0, false));
                 reverseSequence.push(ActionBuilder.fadeAction(selfModel, 0, true));
@@ -621,7 +632,13 @@ export class SetActiveOnClick extends Behaviour implements IPointerClickHandler,
 }
 
 /**
- * Hides the object on scene start.
+ * Hides the object when the scene starts.
+ * Works in the browser and in USDZ/QuickLook (Everywhere Actions).
+ * 
+ * Useful for setting up objects that should initially be hidden and shown later via a {@link SetActiveOnClick} component.
+ * 
+ * @see {@link SetActiveOnClick} to show or hide objects on click
+ * @see [Everywhere Actions](https://engine.needle.tools/docs/everywhere-actions)
  * @summary Hides the object on scene start
  * @category Everywhere Actions
  * @group Components
@@ -663,26 +680,36 @@ export class HideOnStart extends Behaviour implements UsdzBehaviour {
     }
 
     private wasVisible: boolean = false;
-    
+  
     beforeCreateDocument() {
         this.wasVisible = GameObject.isActiveSelf(this.gameObject);
     }
 }
 
 /**
- * Emphasize the target object when clicked.
+ * Applies an emphasis animation to a target object when this object is clicked.
+ * Works in USDZ/QuickLook (Everywhere Actions).
+ * 
+ * The emphasis effect can be a bounce, jiggle, or other motion type defined by `motionType`.
+ * 
+ * @see {@link PlayAnimationOnClick} to play animations when clicked
+ * @see {@link SetActiveOnClick} to toggle visibility when clicked
+ * @see [Everywhere Actions](https://engine.needle.tools/docs/everywhere-actions)
  * @summary Emphasizes the target object when clicked
  * @category Everywhere Actions
  * @group Components
  */
 export class EmphasizeOnClick extends Behaviour implements UsdzBehaviour {
 
+    /** The target object to emphasize. */
     @serializable()
     target?: Object3D;
 
+    /** The duration of the emphasis animation in seconds. */
     @serializable()
     duration: number = 0.5;
 
+    /** The type of motion to use for the emphasis effect (e.g. `"bounce"`, `"jiggle"`). */
     @serializable()
     motionType: EmphasizeActionMotionType = "bounce";
 
@@ -704,29 +731,37 @@ export class EmphasizeOnClick extends Behaviour implements UsdzBehaviour {
 }
 
 /**
- * Plays an audio clip when clicked.
+ * Plays an audio clip when this object is clicked.
+ * Works in the browser and in USDZ/QuickLook (Everywhere Actions).
+ * 
+ * Assign a `target` {@link AudioSource} to use its spatial audio settings, or assign a `clip` URL directly.
+ * If no `target` is assigned, an {@link AudioSource} will be created automatically on this object.
+ *
+ * @see {@link AudioSource}for spatial audio settings
+ * @see {@link PlayAnimationOnClick} to play animations when clicked
+ * @see {@link SetActiveOnClick} to toggle visibility when clicked
+ * @see [Everywhere Actions](https://engine.needle.tools/docs/everywhere-actions)
  * @summary Plays an audio clip when clicked
  * @category Everywhere Actions
  * @group Components
  */
 export class PlayAudioOnClick extends Behaviour implements IPointerClickHandler, UsdzBehaviour {
 
+    /** The {@link AudioSource} to use for playback. If not set, one will be created automatically on this object. */
     @serializable(AudioSource)
     target?: AudioSource;
 
+    /** URL of the audio clip to play. If not set, the clip assigned to `target` is used. */
     @serializable(URL)
     clip: string = "";
 
+    /** If true, clicking again while the audio is playing will stop it. */
     @serializable()
     toggleOnClick: boolean = false;
 
     // Not exposed, but used for implicit playback of PlayOnAwake audio sources
     trigger: "tap" | "start" = "tap";
 
-    start(): void {
-        ensureRaycaster(this.gameObject);
-    }
-
     ensureAudioSource() {
         if (!this.target) {
             const newAudioSource = this.gameObject.addComponent(AudioSource);
@@ -781,7 +816,7 @@ export class PlayAudioOnClick extends Behaviour implements IPointerClickHandler,
             const clipName = AudioExtension.getName(clipUrl);
             const volume = this.target ? this.target.volume : 1;
             const auralMode = this.target && this.target.spatialBlend == 0 ? "nonSpatial" : "spatial";
-            
+          
             // This checks if any child is clickable – if yes, the tap trigger is added; if not, we omit it.
             let anyChildHasGeometry = false;
             this.gameObject.traverse(c => {
@@ -790,7 +825,7 @@ export class PlayAudioOnClick extends Behaviour implements IPointerClickHandler,
             // Workaround: seems iOS often simply doesn't play audio on scene start when this is NOT present.
             // unclear why, but having a useless tap action (nothing to tap on) "fixes" it.
             anyChildHasGeometry = true;
-            
+          
             const audioClip = ext.addAudioClip(clipUrl);
             // const stopAction: IBehaviorElement = ActionBuilder.playAudioAction(playbackTarget, audioClip, "stop", volume, auralMode);
             let playAction: IBehaviorElement = ActionBuilder.playAudioAction(playbackTarget, audioClip, "play", volume, auralMode);
@@ -831,16 +866,30 @@ export class PlayAudioOnClick extends Behaviour implements IPointerClickHandler,
 }
 
 /**
- * Plays an animation when clicked.
+ * Plays an animation state when this object is clicked.
+ * Works in the browser and in USDZ/QuickLook (Everywhere Actions).
+ * 
+ * Assign an {@link Animator} and a `stateName` to play a specific animation state,
+ * or assign an {@link Animation} component to play a legacy animation clip.
+ * 
+ * For USDZ export, the component follows animator state transitions automatically, including looping states.
+ *
+ * @see {@link Animator}for playing animator state machine animations
+ * @see {@link Animation} for playing legacy animation clips
+ * @see {@link PlayAudioOnClick} to play audio when clicked
+ * @see {@link SetActiveOnClick} to toggle visibility when clicked
+ * @see [Everywhere Actions](https://engine.needle.tools/docs/everywhere-actions)
  * @summary Plays an animation when clicked
  * @category Everywhere Actions
  * @group Components
  */
 export class PlayAnimationOnClick extends Behaviour implements IPointerClickHandler, UsdzBehaviour, UsdzAnimation {
 
+    /** The {@link Animator} component whose state to play when clicked. */
     @serializable(Animator)
     animator?: Animator;
 
+    /** The name of the animation state to play. Required when using an {@link Animator}. */
     @serializable()
     stateName?: string;
 
@@ -852,10 +901,6 @@ export class PlayAnimationOnClick extends Behaviour implements IPointerClickHand
 
     private get target() { return this.animator?.gameObject || this.animation?.gameObject }
 
-    start(): void {
-        ensureRaycaster(this.gameObject);
-    }
-
 
     onPointerEnter() {
         this.context.input.setCursor("pointer");
@@ -905,9 +950,9 @@ export class PlayAnimationOnClick extends Behaviour implements IPointerClickHand
     afterCreateDocument(ext: BehaviorExtension, context: USDZExporterContext) {
         if ((this.animationSequence === undefined && this.animationLoopAfterSequence === undefined) || !this.stateAnimationModel) return;
         if (!this.target) return;
-        
+      
         const document = context.document;
-        
+      
         // check if the AnimationExtension has been attached and what data it has for the current object
         const animationExt = context.extensions.find(ext => ext instanceof AnimationExtension) as AnimationExtension;
         if (!animationExt) return;
@@ -921,7 +966,7 @@ export class PlayAnimationOnClick extends Behaviour implements IPointerClickHand
         if (requiresExclusivePlayback) {
             if (isDevEnvironment())
                 console.warn("Setting exclusive playback for " + this.target.name + "@" + this.stateName + " because it has " + animationExt.getClipCount(this.target) + " animations. This works around QuickLook bug FB13410767.");
-            
+          
             PlayAnimationOnClick.rootsWithExclusivePlayback.add(this.target);
         }
 
@@ -941,7 +986,7 @@ export class PlayAnimationOnClick extends Behaviour implements IPointerClickHand
                     this.trigger == "tap" ? TriggerBuilder.tapTrigger(this.selfModel) : TriggerBuilder.sceneStartTrigger(),
                     sequence
                 );
-                
+              
                 // See comment above for why exclusive playback is currently required when playing multiple animations on the same root.
                 if (requiresExclusivePlayback)
                     playAnimationOnTap.makeExclusive(true);
@@ -1010,14 +1055,14 @@ export class PlayAnimationOnClick extends Behaviour implements IPointerClickHand
         let animationLoopAfterSequence: Array<RegisteredAnimationInfo> = [];
 
         if (animation) {
-            const anim = ext.registerAnimation(target, animation.clip);   
+            const anim = ext.registerAnimation(target, animation.clip); 
             if (anim) { 
                 if (animation.loop)
                     animationLoopAfterSequence.push(anim);
                 else
                     animationSequence.push(anim);
             }
-            
+          
             let randomTimeOffset = 0;
             if (animation.minMaxOffsetNormalized) {
                 const from = animation.minMaxOffsetNormalized.x;
@@ -1111,7 +1156,7 @@ export class PlayAnimationOnClick extends Behaviour implements IPointerClickHand
                 if (lastClip) {
                     let clipCopy: AnimationClip | undefined;
                     if (ext.holdClipMap.has(lastClip)) {
-                        clipCopy = ext.holdClipMap.get(lastClip);    
+                        clipCopy = ext.holdClipMap.get(lastClip);  
                     }
                     else {
                         // We're creating a "hold" clip here; exactly 1 second long, and inteprolates exactly on the duration of the clip
@@ -1241,17 +1286,24 @@ export class PreliminaryTrigger extends Behaviour {
 }
 
 /**
- * Hides or shows the object when clicked.
+ * Action to show or hide an object.
+ * Use together with a {@link TapGestureTrigger} to show or hide objects when tapped or clicked.
+ * 
+ * @see {@link TapGestureTrigger} to trigger actions on tap/click
+ * @see {@link SetActiveOnClick} for a combined trigger and action component
+ * @see [Everywhere Actions](https://engine.needle.tools/docs/everywhere-actions)
  * @summary Hides or shows the object when clicked
  * @category Everywhere Actions
  * @group Components
  */
 export class VisibilityAction extends PreliminaryAction {
 
+    /** The type of visibility action to apply. */
     //@type int
     @serializable()
     type: VisibilityActionType = VisibilityActionType.Hide;
 
+    /** The duration of the fade animation in seconds. */
     @serializable()
     duration: number = 1;
 
@@ -1268,7 +1320,12 @@ export class VisibilityAction extends PreliminaryAction {
 }
 
 /**
- * Triggers an action when the object is tapped/clicked.
+ * Triggers a {@link PreliminaryAction} (such as {@link VisibilityAction}) when the object is tapped or clicked.
+ * Works in the browser and in USDZ/QuickLook (Everywhere Actions).
+ * 
+ * @see {@link VisibilityAction} for controlling object visibility on tap
+ * @see {@link SetActiveOnClick} for a combined trigger and action component
+ * @see [Everywhere Actions](https://engine.needle.tools/docs/everywhere-actions)
  * @summary Triggers an action when the object is tapped/clicked
  * @category Everywhere Actions
  * @group Components