@needle-tools/engine
Version:
Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.
1,028 lines (1,027 loc) • 60.1 kB
JavaScript
var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
return c > 3 && r && Object.defineProperty(target, key, r), r;
};
import { Material, Matrix4, Mesh, Object3D, Quaternion, Vector3 } from "three";
import { isDevEnvironment, showBalloonWarning } from "../../../../../engine/debug/index.js";
import { serializable } from "../../../../../engine/engine_serialization_decorator.js";
import { getWorldPosition, getWorldQuaternion, getWorldScale, setWorldPosition, setWorldQuaternion, setWorldScale } from "../../../../../engine/engine_three_utils.js";
import { getParam } from "../../../../../engine/engine_utils.js";
import { compareAssociation } from "../../../../../engine/extensions/extension_utils.js";
import { NEEDLE_progressive } from "../../../../../engine/extensions/NEEDLE_progressive.js";
import { Animation } from "../../../../Animation.js";
import { Animator } from "../../../../Animator.js";
import { AudioSource } from "../../../../AudioSource.js";
import { Behaviour, GameObject } from "../../../../Component.js";
import { Rigidbody } from "../../../../RigidBody.js";
import { makeNameSafeForUSD, USDDocument, USDObject } from "../../ThreeUSDZExporter.js";
import { AnimationExtension } from "../Animation.js";
import { AudioExtension } from "./AudioExtension.js";
import { ActionBuilder, BehaviorModel, TriggerBuilder } from "./BehavioursBuilder.js";
const debug = getParam("debugusdzbehaviours");
/**
* 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 {
/** The object to move. */
object;
/** The target object whose transform to move to. */
target;
/** The duration of the movement animation in seconds. */
duration = 1;
/** If true, the motion is relative to the object's current transform instead of moving to the target's absolute position. */
relativeMotion = false;
coroutine = null;
targetPos = new Vector3();
targetRot = new Quaternion();
targetScale = new Vector3();
onEnable() {
this.context.accessibility.updateElement(this, {
role: "button",
label: "Move " + (this.object?.name || "object") + " to " + (this.target?.name || "target") + " on click",
hidden: false,
});
}
onDisable() {
this.context.accessibility.updateElement(this, {
hidden: true,
});
}
onDestroy() {
this.context.accessibility.removeElement(this);
}
onPointerEnter() {
this.context.input.setCursor("pointer");
}
onPointerExit() {
this.context.input.unsetCursor("pointer");
}
onPointerClick(args) {
const rbs = this.object?.getComponentsInChildren(Rigidbody);
if (rbs) {
for (const rb of rbs) {
rb.resetVelocities();
rb.resetForcesAndTorques();
}
}
args.use();
if (this.coroutine)
this.stopCoroutine(this.coroutine);
if (!this.relativeMotion)
this.coroutine = this.startCoroutine(this.moveToTarget());
else
this.coroutine = this.startCoroutine(this.moveRelative());
}
*moveToTarget() {
if (!this.target || !this.object)
return;
const thisPos = getWorldPosition(this.object).clone();
const targetPos = getWorldPosition(this.target).clone();
const thisRot = getWorldQuaternion(this.object).clone();
const targetRot = getWorldQuaternion(this.target).clone();
const thisScale = getWorldScale(this.object).clone();
const targetScale = getWorldScale(this.target).clone();
const dist = thisPos.distanceTo(targetPos);
const rotDist = thisRot.angleTo(targetRot);
const scaleDist = thisScale.distanceTo(targetScale);
if (dist < 0.01 && rotDist < 0.01 && scaleDist < 0.01) {
setWorldPosition(this.object, targetPos);
setWorldQuaternion(this.object, targetRot);
setWorldScale(this.object, targetScale);
this.coroutine = null;
return;
}
let t01 = 0;
let eased = 0;
while (t01 < 1) {
t01 += this.context.time.deltaTime / this.duration;
if (t01 > 1)
t01 = 1;
// apply ease-in-out
// https://easings.net/
eased = t01 < 0.5 ? 4 * t01 * t01 * t01 : 1 - Math.pow(-2 * t01 + 2, 3) / 2;
this.targetPos.lerpVectors(thisPos, targetPos, eased);
this.targetRot.slerpQuaternions(thisRot, targetRot, eased);
this.targetScale.lerpVectors(thisScale, targetScale, eased);
setWorldPosition(this.object, this.targetPos);
setWorldQuaternion(this.object, this.targetRot);
setWorldScale(this.object, this.targetScale);
yield;
}
this.coroutine = null;
}
*moveRelative() {
if (!this.target || !this.object)
return;
const thisPos = this.object.position.clone();
const thisRot = this.object.quaternion.clone();
const thisScale = this.object.scale.clone();
const posOffset = this.target.position.clone();
const rotOffset = this.target.quaternion.clone();
const scaleOffset = this.target.scale.clone();
// convert into right space
posOffset.applyQuaternion(this.object.quaternion);
this.targetPos.copy(this.object.position).add(posOffset);
this.targetRot.copy(this.object.quaternion).multiply(rotOffset);
this.targetScale.copy(this.object.scale).multiply(scaleOffset);
let t01 = 0;
let eased = 0;
while (t01 < 1) {
t01 += this.context.time.deltaTime / this.duration;
if (t01 > 1)
t01 = 1;
// apply ease-in-out
// https://easings.net/
eased = t01 < 0.5 ? 4 * t01 * t01 * t01 : 1 - Math.pow(-2 * t01 + 2, 3) / 2;
this.object.position.lerpVectors(thisPos, this.targetPos, eased);
this.object.quaternion.slerpQuaternions(thisRot, this.targetRot, eased);
this.object.scale.lerpVectors(thisScale, this.targetScale, eased);
yield;
}
this.coroutine = null;
}
beforeCreateDocument(ext) {
if (this.target && this.object && this.gameObject) {
const moveForward = new BehaviorModel("Move to " + this.target?.name, TriggerBuilder.tapTrigger(this.gameObject), ActionBuilder.transformAction(this.object, this.target, this.duration, this.relativeMotion ? "relative" : "absolute"));
ext.addBehavior(moveForward);
}
}
}
__decorate([
serializable(Object3D)
], ChangeTransformOnClick.prototype, "object", void 0);
__decorate([
serializable(Object3D)
], ChangeTransformOnClick.prototype, "target", void 0);
__decorate([
serializable()
], ChangeTransformOnClick.prototype, "duration", void 0);
__decorate([
serializable()
], ChangeTransformOnClick.prototype, "relativeMotion", void 0);
/**
* 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
*/
export class ChangeMaterialOnClick extends Behaviour {
/**
* The material that will be switched to the variant material
*/
materialToSwitch;
/**
* The material that will be switched to
*/
variantMaterial;
/**
* The duration of the fade effect in seconds (USDZ/Quicklook only)
* @default 0
*/
fadeDuration = 0;
start() {
// initialize the object list
this._objectsWithThisMaterial = this.objectsWithThisMaterial;
if (isDevEnvironment() && this._objectsWithThisMaterial.length <= 0) {
console.warn("ChangeMaterialOnClick: No objects found with material \"" + this.materialToSwitch?.name + "\"");
}
}
onEnable() {
this.context.accessibility.updateElement(this, {
role: "button",
label: "Change material to " + (this.variantMaterial?.name || "unknown material"),
hidden: false,
});
}
onDisable() {
this.context.accessibility.updateElement(this, {
hidden: true,
});
}
onDestroy() {
this.context.accessibility.removeElement(this);
}
onPointerEnter(_args) {
this.context.input.setCursor("pointer");
}
onPointerExit(_) {
this.context.input.unsetCursor("pointer");
}
onPointerClick(args) {
args.use();
if (!this.variantMaterial)
return;
for (let i = 0; i < this.objectsWithThisMaterial.length; i++) {
const obj = this.objectsWithThisMaterial[i];
obj.material = this.variantMaterial;
}
}
_objectsWithThisMaterial = null;
/** Get all objects in the scene that have the assigned materialToSwitch */
get objectsWithThisMaterial() {
if (this._objectsWithThisMaterial != null)
return this._objectsWithThisMaterial;
this._objectsWithThisMaterial = [];
if (this.variantMaterial && this.materialToSwitch) {
this.context.scene.traverse(obj => {
if (obj instanceof Mesh) {
if (Array.isArray(obj.material)) {
for (const mat of obj.material) {
if (mat === this.materialToSwitch) {
this.objectsWithThisMaterial.push(obj);
break;
}
}
}
else {
if (obj.material === this.materialToSwitch) {
this.objectsWithThisMaterial.push(obj);
}
else if (compareAssociation(obj.material, this.materialToSwitch)) {
this.objectsWithThisMaterial.push(obj);
}
}
}
});
}
return this._objectsWithThisMaterial;
}
selfModel;
targetModels;
static _materialTriggersPerId = {};
static _startHiddenBehaviour = null;
static _parallelStartHiddenActions = [];
async beforeCreateDocument(_ext, _context) {
this.targetModels = [];
ChangeMaterialOnClick._materialTriggersPerId = {};
ChangeMaterialOnClick.variantSwitchIndex = 0;
// Ensure that the progressive textures have been loaded for all variants and materials
if (this.materialToSwitch) {
await NEEDLE_progressive.assignTextureLOD(this.materialToSwitch, 0);
}
if (this.variantMaterial) {
await NEEDLE_progressive.assignTextureLOD(this.variantMaterial, 0);
}
}
createBehaviours(_ext, model, _context) {
const shouldExport = this.objectsWithThisMaterial.find(o => o.uuid === model.uuid);
if (shouldExport) {
this.targetModels.push(model);
}
if (this.gameObject.uuid === model.uuid) {
this.selfModel = model;
if (this.materialToSwitch) {
if (!ChangeMaterialOnClick._materialTriggersPerId[this.materialToSwitch.uuid])
ChangeMaterialOnClick._materialTriggersPerId[this.materialToSwitch.uuid] = [];
ChangeMaterialOnClick._materialTriggersPerId[this.materialToSwitch.uuid].push(this);
}
}
}
afterCreateDocument(ext, _context) {
if (!this.materialToSwitch)
return;
const handlers = ChangeMaterialOnClick._materialTriggersPerId[this.materialToSwitch.uuid];
if (handlers) {
const variants = {};
for (const handler of handlers) {
const createdVariants = handler.createVariants();
if (createdVariants && createdVariants.length > 0)
variants[handler.selfModel.uuid] = createdVariants;
}
for (const handler of handlers) {
const otherVariants = [];
for (const key in variants) {
if (key !== handler.selfModel.uuid) {
otherVariants.push(...variants[key]);
}
}
handler.createAndAttachBehaviors(ext, variants[handler.selfModel.uuid], otherVariants);
}
}
delete ChangeMaterialOnClick._materialTriggersPerId[this.materialToSwitch.uuid];
}
createAndAttachBehaviors(ext, myVariants, otherVariants) {
const select = [];
const fadeDuration = Math.max(0, this.fadeDuration);
select.push(ActionBuilder.fadeAction([...this.targetModels, ...otherVariants], fadeDuration, false));
select.push(ActionBuilder.fadeAction(myVariants, fadeDuration, true));
ext.addBehavior(new BehaviorModel("Select_" + this.selfModel.name, TriggerBuilder.tapTrigger(this.selfModel), ActionBuilder.parallel(...select)));
ChangeMaterialOnClick._parallelStartHiddenActions.push(...myVariants);
if (!ChangeMaterialOnClick._startHiddenBehaviour) {
ChangeMaterialOnClick._startHiddenBehaviour =
new BehaviorModel("StartHidden_" + this.selfModel.name, TriggerBuilder.sceneStartTrigger(), ActionBuilder.fadeAction(ChangeMaterialOnClick._parallelStartHiddenActions, fadeDuration, false));
ext.addBehavior(ChangeMaterialOnClick._startHiddenBehaviour);
}
}
static getMaterialName(material) {
return makeNameSafeForUSD(material.name || 'Material') + "_" + material.id;
}
static variantSwitchIndex = 0;
createVariants() {
if (!this.variantMaterial)
return null;
const variantModels = [];
for (const target of this.targetModels) {
const variant = target.clone();
variant.name += "_Variant_" + ChangeMaterialOnClick.variantSwitchIndex++ + "_" + ChangeMaterialOnClick.getMaterialName(this.variantMaterial);
variant.displayName = variant.displayName + ": Variant with material " + this.variantMaterial.name;
variant.material = this.variantMaterial;
variant.geometry = target.geometry;
variant.transform = target.transform;
if (!target.parent || !target.parent.isEmpty()) {
USDObject.createEmptyParent(target);
}
if (target.parent)
target.parent.add(variant);
variantModels.push(variant);
}
return variantModels;
}
}
__decorate([
serializable(Material)
], ChangeMaterialOnClick.prototype, "materialToSwitch", void 0);
__decorate([
serializable(Material)
], ChangeMaterialOnClick.prototype, "variantMaterial", void 0);
__decorate([
serializable()
], ChangeMaterialOnClick.prototype, "fadeDuration", void 0);
/**
* 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 {
/** The target object to show or hide. */
target;
/** If true, the target's visibility will be toggled on each click. When enabled, `hideSelf` and `targetState` are ignored. */
toggleOnClick = false;
/** The visibility state to apply to the target when clicked. Only used when `toggleOnClick` is false. */
targetState = true;
/** If true, this object will hide itself after being clicked. Only used when `toggleOnClick` is false. */
hideSelf = true;
onPointerEnter() {
this.context.input.setCursor("pointer");
}
onPointerExit() {
this.context.input.unsetCursor("pointer");
}
onPointerClick(args) {
args.use();
if (!this.toggleOnClick && this.hideSelf)
this.gameObject.visible = false;
if (this.target)
this.target.visible = this.toggleOnClick ? !this.target.visible : this.targetState;
}
selfModel;
selfModelClone;
targetModel;
toggleModel;
createBehaviours(_, model, _context) {
if (model.uuid === this.gameObject.uuid) {
this.selfModel = model;
this.selfModelClone = model.clone();
}
}
stateBeforeCreatingDocument = false;
targetStateBeforeCreatingDocument = false;
static clonedToggleIndex = 0;
static wasVisible = Symbol("usdz_SetActiveOnClick_wasVisible");
static toggleClone = Symbol("clone for toggling");
static reverseToggleClone = Symbol("clone for reverse toggling");
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)
this.gameObject[SetActiveOnClick.wasVisible] = this.gameObject.activeSelf;
if (this.target[SetActiveOnClick.wasVisible] === undefined)
this.target[SetActiveOnClick.wasVisible] = this.target.activeSelf;
this.stateBeforeCreatingDocument = this.gameObject[SetActiveOnClick.wasVisible];
this.targetStateBeforeCreatingDocument = this.target[SetActiveOnClick.wasVisible];
// Objects need to be on so they are exported, as we're skipping invisible objects
this.gameObject.visible = true;
this.target.visible = true;
}
afterCreateDocument(ext, context) {
if (!this.target)
return;
// Parameters:
// - hideSelf: the trigger is hidden after clicking. Can basically only be used once.
// - toggleOnClick: the target is toggled on/off when the trigger is clicked.
// - targetState: the target is set to this state when the trigger is clicked.
// Combinations:
// - when toggleOnClick is on, hideSelf is ignored
// - we need to make a copy of our object
// - when the trigger is clicked
// - hide the original trigger
// - show the copied trigger
// - set the target to targetState
// - when the copied trigger is clicked
// - hide the copied trigger
// - show the original trigger again
// - set the target to !targetState
// - when toggleOnClick is off, hideSelf is used
// - no copy is needed
// - when the trigger is clicked
// - hide the trigger
// - set the target to the targetState
this.targetModel = context.document.findById(this.target.uuid);
const originalModel = this.selfModel;
if (this.selfModel && this.targetModel) {
let selfModel = this.selfModel;
let targetState = this.targetState;
// if we toggle, we need to create a copy of our object
if (this.toggleOnClick) {
// When toggling we want to respect the current state of the target,
// so effectively this.targetState and this.hideSelf are ignored.
targetState = !this.targetStateBeforeCreatingDocument;
// Potentially it's easier/better to just "clone" and put the object as a sibling next
// to the rest of the hierarchy. This way we would lose nested clicks (clicking on a child would not trigger events)
// but we're not potentially duplicating tons of objects.
// 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) {
if (!this.selfModel.parent || this.selfModel.parent.isEmpty())
USDDocument.createEmptyParent(this.selfModel);
this.toggleModel = this.selfModel.deepClone();
this.toggleModel.name += "_toggle";
this.selfModel.parent.add(this.toggleModel);
}
else {
// Option B: we shallow clone ourselves and put the clone next to us. This means childs are not clickable anymore.
// We create clones exactly once for this gameObject, so that all SetActiveOnClick on the same object use the same trigger.
if (!this.gameObject[SetActiveOnClick.toggleClone]) {
const clone = this.selfModelClone.clone();
clone.setMatrix(new Matrix4());
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());
clone.name += "_toggleReverse" + (SetActiveOnClick.clonedToggleIndex++);
originalModel.add(clone);
this.gameObject[SetActiveOnClick.reverseToggleClone] = clone;
}
this.toggleModel = this.gameObject[SetActiveOnClick.reverseToggleClone];
if (!this.toggleModel.geometry || !clonedSelfModel.geometry) {
console.error("triggers without childs and without geometry won't work!", this, originalModel.geometry);
}
// We're targeting the clone in the actions below, not the original object
selfModel = clonedSelfModel;
// Remove the geometry, we've duplicated it into the toggle/reverseToggle already
originalModel.geometry = null;
originalModel.material = null;
// Known issues: clone() does not clone skinned mesh geometry, lights, cameras;
// we still have them on the original object and the clones won't have it.
}
}
// this.toggleOnClick is false, so we don't have a toggleModel – no need for clones,
// just set the target object to targetState and optionally hide ourselves
if (!this.toggleModel) {
const sequence = [];
if (this.hideSelf)
sequence.push(ActionBuilder.fadeAction(selfModel, 0, false));
sequence.push(ActionBuilder.fadeAction(this.targetModel, 0, targetState));
ext.addBehavior(new BehaviorModel("Toggle_" + selfModel.name + "_ToggleTo" + (targetState ? "On" : "Off"), TriggerBuilder.tapTrigger(selfModel), sequence.length > 1 ? ActionBuilder.parallel(...sequence) : sequence[0]));
}
// We have a toggleModel, so we need to set up two sequences:
// - one that hides the original object, shows the toggle and sets the target to targetState
// - one that hides the toggle, shows the original object and sets the target to !targetState
else if (this.toggleOnClick) {
const toggleSequence = [];
toggleSequence.push(ActionBuilder.fadeAction(selfModel, 0, false));
toggleSequence.push(ActionBuilder.fadeAction(this.toggleModel, 0, true));
toggleSequence.push(ActionBuilder.fadeAction(this.targetModel, 0, targetState));
ext.addBehavior(new BehaviorModel("Toggle_" + selfModel.name + "_ToggleTo" + (targetState ? "On" : "Off"), TriggerBuilder.tapTrigger(selfModel), ActionBuilder.parallel(...toggleSequence)));
const reverseSequence = [];
reverseSequence.push(ActionBuilder.fadeAction(this.toggleModel, 0, false));
reverseSequence.push(ActionBuilder.fadeAction(selfModel, 0, true));
reverseSequence.push(ActionBuilder.fadeAction(this.targetModel, 0, !targetState));
ext.addBehavior(new BehaviorModel("Toggle_" + selfModel.name + "_ToggleTo" + (!targetState ? "On" : "Off"), TriggerBuilder.tapTrigger(this.toggleModel), ActionBuilder.parallel(...reverseSequence)));
}
// Ensure initial states are set correctly so that we get the same result as was currently active in the runtime
const objectsToHide = new Array();
if (!this.targetStateBeforeCreatingDocument)
objectsToHide.push(this.targetModel);
if (!this.stateBeforeCreatingDocument)
objectsToHide.push(originalModel);
if (this.toggleModel)
objectsToHide.push(this.toggleModel);
HideOnStart.add(objectsToHide, ext);
}
}
afterSerialize(_ext, _context) {
// cleanup visibility cache
if (this.gameObject[SetActiveOnClick.wasVisible] !== undefined) {
this.gameObject.visible = this.gameObject[SetActiveOnClick.wasVisible];
delete this.gameObject[SetActiveOnClick.wasVisible];
}
if (this.target && this.target[SetActiveOnClick.wasVisible] !== undefined) {
this.target.visible = this.target[SetActiveOnClick.wasVisible];
delete this.target[SetActiveOnClick.wasVisible];
}
// cleanup trigger clones
delete this.gameObject[SetActiveOnClick.toggleClone];
delete this.gameObject[SetActiveOnClick.reverseToggleClone];
}
}
__decorate([
serializable(Object3D)
], SetActiveOnClick.prototype, "target", void 0);
__decorate([
serializable()
], SetActiveOnClick.prototype, "toggleOnClick", void 0);
__decorate([
serializable()
], SetActiveOnClick.prototype, "targetState", void 0);
__decorate([
serializable()
], SetActiveOnClick.prototype, "hideSelf", void 0);
/**
* 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
*/
export class HideOnStart extends Behaviour {
static _fadeBehaviour;
static _fadeObjects = [];
static add(target, ext) {
const arr = Array.isArray(target) ? target : [target];
for (const entry of arr) {
if (!HideOnStart._fadeObjects.includes(entry)) {
console.log("adding hide on start", entry);
HideOnStart._fadeObjects.push(entry);
}
}
if (HideOnStart._fadeBehaviour === undefined) {
HideOnStart._fadeBehaviour = new BehaviorModel("HideOnStart", TriggerBuilder.sceneStartTrigger(),
//@ts-ignore
ActionBuilder.fadeAction(HideOnStart._fadeObjects, 0, false));
ext.addBehavior(HideOnStart._fadeBehaviour);
}
}
start() {
GameObject.setActive(this.gameObject, false);
}
createBehaviours(ext, model, _context) {
if (model.uuid === this.gameObject.uuid) {
// we only want to mark the object as HideOnStart if it's still hidden
if (!this.wasVisible) {
HideOnStart.add(model, ext);
}
}
}
wasVisible = false;
beforeCreateDocument() {
this.wasVisible = GameObject.isActiveSelf(this.gameObject);
}
}
/**
* 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 {
/** The target object to emphasize. */
target;
/** The duration of the emphasis animation in seconds. */
duration = 0.5;
/** The type of motion to use for the emphasis effect (e.g. `"bounce"`, `"jiggle"`). */
motionType = "bounce";
onEnable() {
this.context.accessibility.updateElement(this, {
role: "button",
label: "Emphasize " + this.target?.name + " on click",
hidden: false,
});
}
onDisable() {
this.context.accessibility.updateElement(this, {
hidden: true,
});
}
onDestroy() {
this.context.accessibility.removeElement(this);
}
beforeCreateDocument() { }
createBehaviours(ext, model, _context) {
if (!this.target)
return;
if (model.uuid === this.gameObject.uuid) {
const emphasize = new BehaviorModel("emphasize " + this.name, TriggerBuilder.tapTrigger(this.gameObject), ActionBuilder.emphasize(this.target, this.duration, this.motionType, undefined, "basic"));
ext.addBehavior(emphasize);
}
}
afterCreateDocument(_ext, _context) { }
}
__decorate([
serializable()
], EmphasizeOnClick.prototype, "target", void 0);
__decorate([
serializable()
], EmphasizeOnClick.prototype, "duration", void 0);
__decorate([
serializable()
], EmphasizeOnClick.prototype, "motionType", void 0);
/**
* 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 {
/** The {@link AudioSource} to use for playback. If not set, one will be created automatically on this object. */
target;
/** URL of the audio clip to play. If not set, the clip assigned to `target` is used. */
clip = "";
/** If true, clicking again while the audio is playing will stop it. */
toggleOnClick = false;
// Not exposed, but used for implicit playback of PlayOnAwake audio sources
trigger = "tap";
ensureAudioSource() {
if (!this.target) {
const newAudioSource = this.gameObject.addComponent(AudioSource);
if (newAudioSource) {
this.target = newAudioSource;
newAudioSource.spatialBlend = 1;
newAudioSource.volume = 1;
newAudioSource.loop = false;
newAudioSource.preload = true;
}
}
}
onEnable() {
this.context.accessibility.updateElement(this, {
role: "button",
label: "Play audio: " + (this.clip || this.target?.clip || "unknown clip"),
hidden: false,
});
}
onDisable() {
this.context.accessibility.updateElement(this, {
hidden: true,
});
}
onDestroy() {
this.context.accessibility.removeElement(this);
}
onPointerEnter() {
this.context.input.setCursor("pointer");
}
onPointerExit() {
this.context.input.unsetCursor("pointer");
}
onPointerClick(args) {
args.use();
if (!this.target?.clip && !this.clip)
return;
this.ensureAudioSource();
if (this.target) {
if (this.target.isPlaying && this.toggleOnClick) {
this.target.stop();
}
else {
if (!this.toggleOnClick && this.target.isPlaying) {
this.target.stop();
}
if (this.clip)
this.target.play(this.clip);
else
this.target.play();
}
}
}
createBehaviours(ext, model, _context) {
if (!this.target && !this.clip)
return;
if (model.uuid === this.gameObject.uuid) {
const clipUrl = this.clip ? this.clip : this.target ? this.target.clip : undefined;
if (!clipUrl)
return;
if (typeof clipUrl !== "string")
return;
const playbackTarget = this.target ? this.target.gameObject : this.gameObject;
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 => {
if (c instanceof Mesh && c.visible)
anyChildHasGeometry = true;
});
// 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 = ActionBuilder.playAudioAction(playbackTarget, audioClip, "play", volume, auralMode);
if (this.target && this.target.loop)
playAction = ActionBuilder.sequence(playAction).makeLooping();
const behaviorName = (this.name ? "_" + this.name : "");
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.multiplePerformOperation = "stop";
const playClipOnTap = new BehaviorModel("playAudio" + behaviorName, TriggerBuilder.tapTrigger(model), playAction);
ext.addBehavior(playClipOnTap);
}
// automatically play audio on start too if the referenced AudioSource has playOnAwake enabled
if (this.target && this.target.playOnAwake && this.target.enabled) {
if (anyChildHasGeometry && this.trigger === "tap") {
// WORKAROUND Currently (20240509) we MUST not emit this behaviour if we're also expecting the tap trigger to work.
// Seems to be a regression in QuickLook... audio clips can't be stopped anymore as soon as they start playing.
console.warn("USDZExport: Audio sources that are played on tap can't also auto-play at scene start due to a QuickLook bug.");
}
else {
const playClipOnStart = new BehaviorModel("playAudioOnStart" + behaviorName, TriggerBuilder.sceneStartTrigger(), playAction);
ext.addBehavior(playClipOnStart);
}
}
}
}
}
__decorate([
serializable(AudioSource)
], PlayAudioOnClick.prototype, "target", void 0);
__decorate([
serializable(URL)
], PlayAudioOnClick.prototype, "clip", void 0);
__decorate([
serializable()
], PlayAudioOnClick.prototype, "toggleOnClick", void 0);
/**
* 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 {
/** The {@link Animator} component whose state to play when clicked. */
animator;
/** The name of the animation state to play. Required when using an {@link Animator}. */
stateName;
// Not editable from the outside yet, but from code
// we want to expose this once we have a nice drawer for "Triggers" (e.g. shows proximity distance)
// and once we rename the component to "PlayAnimation" or "PlayAnimationOnTrigger"
trigger = "tap"; // "proximity"
animation;
get target() { return this.animator?.gameObject || this.animation?.gameObject; }
onEnable() {
this.context.accessibility.updateElement(this, {
role: "button",
label: "Plays animation " + (this.stateName || "") + " on " + (this.target ? this.target.name : ""),
hidden: false
});
}
onDisable() {
this.context.accessibility.updateElement(this, {
hidden: true,
});
}
onDestroy() {
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");
}
onPointerClick(args) {
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.
this.animator?.play(this.stateName, 0, 0, .1);
}
}
selfModel;
stateAnimationModel;
animationSequence = new Array();
animationLoopAfterSequence = new Array();
randomOffsetNormalized = 0;
createBehaviours(_ext, model, _context) {
if (model.uuid === this.gameObject.uuid)
this.selfModel = model;
}
static animationActions = [];
static rootsWithExclusivePlayback = new Set();
// Cleanup. TODO This is not the best way as it's called multiple times (once for each component).
afterSerialize() {
if (PlayAnimationOnClick.rootsWithExclusivePlayback.size > 1) {
const message = "Multiple root objects targeted by more than one animation. To work around QuickLook bug FB13410767, animations will be set as \"exclusive\" and activating them will stop other animations being marked as exclusive.";
if (isDevEnvironment())
showBalloonWarning(message);
console.warn(message, ...PlayAnimationOnClick.rootsWithExclusivePlayback);
}
PlayAnimationOnClick.animationActions = [];
PlayAnimationOnClick.rootsWithExclusivePlayback = new Set();
}
afterCreateDocument(ext, context) {
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);
if (!animationExt)
return;
// This is a workaround for FB13410767 - StartAnimationAction in USDZ preliminary behaviours does not stop when another StartAnimationAction is called on the same prim
// When we play multiple animations on the same root, QuickLook just overlaps them and glitches around instead of stopping an earlier one.
// Once this is fixed, we can relax this check and just always make it non-exclusive again.
// Setting exclusive playback has the side effect of unfortunately canceling all other playing actions that are exclusive too -
// seems there is no finer-grained control over which actions should stop which other actions...
const requiresExclusivePlayback = animationExt.getClipCount(this.target) > 1;
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);
}
const behaviorName = (this.name ? this.name : "");
document.traverse(model => {
if (model.uuid === this.target?.uuid) {
const sequence = PlayAnimationOnClick.getActionForSequences(document, model, this.animationSequence, this.animationLoopAfterSequence, this.randomOffsetNormalized);
const playAnimationOnTap = new BehaviorModel(this.trigger + "_" + behaviorName + "_toPlayAnimation_" + this.stateName + "_on_" + this.target?.name, 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);
ext.addBehavior(playAnimationOnTap);
}
});
}
static getActionForSequences(_document, model, animationSequence, animationLoopAfterSequence, randomOffsetNormalized) {
const getOrCacheAction = (model, anim) => {
let action = PlayAnimationOnClick.animationActions.find(a => a.affectedObjects == model && a.start == anim.start && a.duration == anim.duration && a.animationSpeed == anim.speed);
if (!action) {
action = ActionBuilder.startAnimationAction(model, anim);
PlayAnimationOnClick.animationActions.push(action);
}
return action;
};
const sequence = ActionBuilder.sequence();
if (animationSequence && animationSequence.length > 0) {
for (const anim of animationSequence) {
sequence.addAction(getOrCacheAction(model, anim));
}
}
if (animationLoopAfterSequence && animationLoopAfterSequence.length > 0) {
// only make a new action group if there's already stuff in the existing one
const loopSequence = sequence.actions.length == 0 ? sequence : ActionBuilder.sequence();
for (const anim of animationLoopAfterSequence) {
loopSequence.addAction(getOrCacheAction(model, anim));
}
loopSequence.makeLooping();
if (sequence !== loopSequence)
sequence.addAction(loopSequence);
}
if (randomOffsetNormalized && randomOffsetNormalized > 0) {
sequence.actions.unshift(ActionBuilder.waitAction(randomOffsetNormalized));
}
return sequence;
}
static getAndRegisterAnimationSequences(ext, target, stateName) {
if (!target)
return undefined;
const animator = target.getComponent(Animator);
const animation = target.getComponent(Animation);
if (!animator && !animation)
return undefined;
if (animator && !stateName) {
throw new Error("PlayAnimationOnClick: No stateName specified for animator " + animator.name + " on " + target.name);
}
let animationSequence = [];
let animationLoopAfterSequence = [];
if (animation) {
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;
const to = animation.minMaxOffsetNormalized.y;
randomTimeOffset = (animation.clip?.duration || 1) * (from + Math.random() * (to - from));
}
return {
animationSequence,
animationLoopAfterSequence,
randomTimeOffset,
};
}
// If there's a separate state specified to play after this one, we
// play it automatically. Theoretically an animator state machine flow could be encoded here.
// We're parsing the Animator states here and follow the transition chain until we find a loop.
// There are some edge cases:
// - (0 > 1.looping) should keep looping (1).
// - (0 > 1 > 1) should keep looping (1).
// - (0 > 1 > 2 > 3 > 2) should keep looping (2,3).
// - (0 > 1 > 2 > 3 > 0) should keep looping (0,1,2,3).
const runtimeController = animator?.runtimeAnimatorController;
let currentState = runtimeController?.findState(stateName);
let statesUntilLoop = [];
let statesLooping = [];
if (runtimeController && currentState) {
// starting point – we have set this above already as startAction
const visitedStates = new Array;
visitedStates.push(currentState);
let foundLoop = false;
while (true && visitedStates.length < 100) {
if (!currentState || currentState === null || !currentState.transitions || currentState.transitions.length === 0) {
if (currentState.motion?.isLooping)
foundLoop = true;
break;
}
// find the first transition without parameters
// TODO we could also find the first _valid_ transition here instead based on the current parameters.
const transition = currentState.transitions.find(t => t.conditions.length === 0);
const nextState = transition ? runtimeController["getState"](transition.destinationState, 0) : null;
// abort: we found a state loop
if (nextState && visitedStates.includes(nextState)) {
currentState = nextState;
foundLoop = true;
break;
}