@needle-tools/engine 4.14.0-beta → 4.14.0-next.52fdb13

package/src/engine-components/ReflectionProbe.ts

@@ -1,14 +1,15 @@
 import { Color, CubeReflectionMapping, CubeTexture, EquirectangularReflectionMapping, LinearSRGBColorSpace, Material, MeshBasicMaterial, MeshStandardMaterial, Object3D, SRGBColorSpace, Texture, Vector3 } from "three";
 
 import { isDevEnvironment, showBalloonWarning } from "../engine/debug/index.js";
+import { MaterialPropertyBlock } from "../engine/engine_materialpropertyblock.js";
 import { serializable } from "../engine/engine_serialization.js";
 import { Context } from "../engine/engine_setup.js";
 import type { IRenderer } from "../engine/engine_types.js";
-import { getParam } from "../engine/engine_utils.js";
+import { getParam, resolveUrl } from "../engine/engine_utils.js";
 import { BoxHelperComponent } from "./BoxHelperComponent.js";
 import { Behaviour } from "./Component.js";
-import { MaterialPropertyBlock } from "../engine/engine_materialpropertyblock.js";
 import { EventList } from "./EventList.js";
+import { loadPMREM } from "../engine/engine_pmrem.js";
 
 export const debug = getParam("debugreflectionprobe");
 const disable = getParam("noreflectionprobe");
@@ -90,10 +91,28 @@ export class ReflectionProbe extends Behaviour {
     }
 
     private _texture!: Texture;
+    private _textureUrlInFlight?: string;
 
-    @serializable(Texture)
+    @serializable([Texture, String])
     set texture(tex: Texture) {
         if (this._texture === tex) return;
+
+        if (typeof tex === "string") {
+            if(debug) console.debug(`[ReflectionProbe] Loading reflection probe texture from URL: ${tex}`);
+            this._textureUrlInFlight = tex;
+            const textureUrl = resolveUrl(this.sourceId, tex);
+            loadPMREM(textureUrl, this.context.renderer).then(loaded => {
+                if (this._textureUrlInFlight === tex && loaded) {
+                    this._textureUrlInFlight = undefined;
+                    if (debug) console.debug(`[ReflectionProbe] Successfully loaded reflection probe texture: ${tex}`);
+                    this.texture = loaded;
+                }
+            });
+            return;
+        }
+
+        this._textureUrlInFlight = undefined;
+
         this._texture = tex;
 
         if (debug) console.debug("[ReflectionProbe] Set reflection probe texture " + (tex?.name || "(removed)"));

package/src/engine-components/RendererLightmap.ts

@@ -1,9 +1,9 @@
 import { NEEDLE_progressive } from "@needle-tools/gltf-progressive";
 import { Group, Mesh, Object3D, ShaderMaterial, Texture, Vector2, Vector4 } from "three";
 
+import { MaterialPropertyBlock } from "../engine/engine_materialpropertyblock.js";
 import type { Context } from "../engine/engine_setup.js";
 import { getParam } from "../engine/engine_utils.js";
-import { MaterialPropertyBlock } from "../engine/engine_materialpropertyblock.js";
 import { type Renderer } from "./Renderer.js";
 
 const debug = getParam("debuglightmaps");

package/src/engine-components/SeeThrough.ts

@@ -1,6 +1,7 @@
 import { Material, Object3D, Object3DEventMap, Vector3 } from "three";
 
 import { Gizmos } from "../engine/engine_gizmos.js";
+import { MaterialPropertyBlock } from "../engine/engine_materialpropertyblock.js";
 import { Mathf } from "../engine/engine_math.js";
 import { serializable } from "../engine/engine_serialization_decorator.js";
 import { getTempVector } from "../engine/engine_three_utils.js";
@@ -11,7 +12,6 @@ import { IUSDExporterExtension } from "./export/usdz/Extension.js";
 import { USDZExporter } from "./export/usdz/USDZExporter.js";
 import type { OrbitControls } from "./OrbitControls.js";
 import { Renderer } from "./Renderer.js";
-import { MaterialPropertyBlock } from "../engine/engine_materialpropertyblock.js";
 
 const debugSeeThrough = getParam("debugseethrough");
 

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

@@ -13,41 +13,40 @@ 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 { makeNameSafeForUSD, USDDocument, USDObject, USDZExporterContext } from "../../ThreeUSDZExporter.js";
 import { AnimationExtension, RegisteredAnimationInfo, type UsdzAnimation } from "../Animation.js";
 import { AudioExtension } from "./AudioExtension.js";
 import type { BehaviorExtension, UsdzBehaviour } from "./Behaviour.js";
-import { ActionBuilder, ActionModel, BehaviorModel, EmphasizeActionMotionType,GroupActionModel,type IBehaviorElement, Target, TriggerBuilder } from "./BehavioursBuilder.js";
+import { ActionBuilder, ActionModel, BehaviorModel, EmphasizeActionMotionType, GroupActionModel, type IBehaviorElement, Target, TriggerBuilder } from "./BehavioursBuilder.js";
 
 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,8 +56,20 @@ export class ChangeTransformOnClick extends Behaviour implements IPointerClickHa
     private targetRot = new Quaternion();
     private targetScale = new Vector3();
 
-    start(): void {
-        ensureRaycaster(this.gameObject);
+    onEnable(): void {
+        this.context.accessibility.updateElement(this, {
+            role: "button",
+            label: "Move " + (this.object?.name || "object") + " to " + (this.target?.name || "target") + " on click",
+            hidden: false,
+        })
+    }
+    onDisable(): void {
+        this.context.accessibility.updateElement(this, {
+            hidden: true,
+        });
+    }
+    onDestroy(): void {
+        this.context.accessibility.removeElement(this);
     }
 
     onPointerEnter() {
@@ -72,8 +83,8 @@ export class ChangeTransformOnClick extends Behaviour implements IPointerClickHa
 
         const rbs = this.object?.getComponentsInChildren(Rigidbody);
 
-        if (rbs){
-            for (const rb of rbs) {	
+        if (rbs) {
+            for (const rb of rbs) {
                 rb.resetVelocities();
                 rb.resetForcesAndTorques();
             }
@@ -189,7 +200,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,12 +237,27 @@ 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 + "\"");
         }
     }
 
+    onEnable(): void {
+        this.context.accessibility.updateElement(this, {
+            role: "button",
+            label: "Change material to " + (this.variantMaterial?.name || "unknown material"),
+            hidden: false,
+        })
+    }
+    onDisable(): void {
+        this.context.accessibility.updateElement(this, {
+            hidden: true,
+        });
+    }
+    onDestroy(): void {
+        this.context.accessibility.removeElement(this);
+    }
+
     onPointerEnter(_args: PointerEventData) {
         this.context.input.setCursor("pointer");
     }
@@ -345,7 +379,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 +415,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 +458,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 +484,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 +545,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 +564,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 +620,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 +663,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,29 +711,55 @@ 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";
 
+    onEnable(): void {
+        this.context.accessibility.updateElement(this, {
+            role: "button",
+            label: "Emphasize " + this.target?.name + " on click",
+            hidden: false,
+        })
+    }
+    onDisable(): void {
+        this.context.accessibility.updateElement(this, {
+            hidden: true,
+        });
+    }
+    onDestroy(): void {
+        this.context.accessibility.removeElement(this);
+    }
+
     beforeCreateDocument() { }
 
     createBehaviours(ext, model, _context) {
@@ -704,29 +778,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);
@@ -740,6 +822,21 @@ export class PlayAudioOnClick extends Behaviour implements IPointerClickHandler,
         }
     }
 
+    onEnable(): void {
+        this.context.accessibility.updateElement(this, {
+            role: "button",
+            label: "Play audio: " + (this.clip || this.target?.clip || "unknown clip"),
+            hidden: false,
+        })
+    }
+    onDisable(): void {
+        this.context.accessibility.updateElement(this, {
+            hidden: true,
+        });
+    }
+    onDestroy(): void {
+        this.context.accessibility.removeElement(this);
+    }
 
     onPointerEnter() {
         this.context.input.setCursor("pointer");
@@ -781,7 +878,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 +887,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);
@@ -799,8 +896,7 @@ export class PlayAudioOnClick extends Behaviour implements IPointerClickHandler,
 
             const behaviorName = (this.name ? "_" + this.name : "");
 
-            if (anyChildHasGeometry && this.trigger === "tap")
-            {
+            if (anyChildHasGeometry && this.trigger === "tap") {
                 // does not seem to work in iOS / QuickLook...
                 // TODO use play "type" which can be start/stop/pause
                 if (this.toggleOnClick) (playAction as ActionModel).multiplePerformOperation = "stop";
@@ -831,16 +927,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,13 +962,25 @@ export class PlayAnimationOnClick extends Behaviour implements IPointerClickHand
 
     private get target() { return this.animator?.gameObject || this.animation?.gameObject }
 
-    start(): void {
-        ensureRaycaster(this.gameObject);
+    onEnable(): void {
+        this.context.accessibility.updateElement(this, {
+            role: "button",
+            label: "Plays animation " + (this.stateName || "") + " on " + (this.target ? this.target.name : ""),
+            hidden: false
+        });
+    }
+    onDisable(): void {
+        this.context.accessibility.updateElement(this, {
+            hidden: true,
+        });
+    }
+    onDestroy(): void {
+        this.context.accessibility.removeElement(this);
     }
-
 
     onPointerEnter() {
         this.context.input.setCursor("pointer");
+        this.context.accessibility.hover(this, "Click to play animation " + (this.stateName || "") + " on " + (this.target ? this.target.name : ""));
     }
     onPointerExit() {
         this.context.input.unsetCursor("pointer");
@@ -867,6 +989,7 @@ export class PlayAnimationOnClick extends Behaviour implements IPointerClickHand
         args.use();
         if (!this.target) return;
         if (this.stateName) {
+            this.context.accessibility.focus(this);
             // TODO this is currently quite annoying to use,
             // as for the web we use the Animator component and its states directly,
             // while in QuickLook we use explicit animations / states.
@@ -878,8 +1001,8 @@ export class PlayAnimationOnClick extends Behaviour implements IPointerClickHand
 
     private stateAnimationModel: any;
 
-    private animationSequence? = new Array<RegisteredAnimationInfo>();
-    private animationLoopAfterSequence? = new Array<RegisteredAnimationInfo>();
+    private animationSequence?= new Array<RegisteredAnimationInfo>();
+    private animationLoopAfterSequence?= new Array<RegisteredAnimationInfo>();
     private randomOffsetNormalized: number = 0;
 
     createBehaviours(_ext: BehaviorExtension, model: USDObject, _context: USDZExporterContext) {
@@ -905,9 +1028,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 +1044,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 +1064,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);
@@ -963,8 +1086,7 @@ export class PlayAnimationOnClick extends Behaviour implements IPointerClickHand
 
         const sequence = ActionBuilder.sequence();
 
-        if (animationSequence && animationSequence.length > 0)
-        {
+        if (animationSequence && animationSequence.length > 0) {
             for (const anim of animationSequence) {
                 sequence.addAction(getOrCacheAction(model, anim));
             }
@@ -988,11 +1110,10 @@ export class PlayAnimationOnClick extends Behaviour implements IPointerClickHand
         return sequence;
     }
 
-    static getAndRegisterAnimationSequences(ext: AnimationExtension, target: GameObject, stateName?: string):
-    { 
-        animationSequence: Array<RegisteredAnimationInfo>, 
+    static getAndRegisterAnimationSequences(ext: AnimationExtension, target: GameObject, stateName?: string): {
+        animationSequence: Array<RegisteredAnimationInfo>,
         animationLoopAfterSequence: Array<RegisteredAnimationInfo>,
-        randomTimeOffset: number, 
+        randomTimeOffset: number,
     } | undefined {
 
         if (!target) return undefined;
@@ -1010,14 +1131,14 @@ export class PlayAnimationOnClick extends Behaviour implements IPointerClickHand
         let animationLoopAfterSequence: Array<RegisteredAnimationInfo> = [];
 
         if (animation) {
-            const anim = ext.registerAnimation(target, animation.clip);   
-            if (anim) { 
+            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 +1232,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 +1362,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 +1396,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