@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.
993 lines • 52.2 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 { ObjectRaycaster, Raycaster } from "../../../../ui/Raycaster.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");
function ensureRaycaster(obj) {
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);
}
}
/**
* @category Everywhere Actions
* @group Components
*/
export class ChangeTransformOnClick extends Behaviour {
object;
target;
duration = 1;
relativeMotion = false;
coroutine = null;
targetPos = new Vector3();
targetRot = new Quaternion();
targetScale = new Vector3();
start() {
ensureRaycaster(this.gameObject);
}
onPointerClick(args) {
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);
/**
* @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;
ensureRaycaster(this.gameObject);
if (isDevEnvironment() && this._objectsWithThisMaterial.length <= 0) {
console.warn("ChangeMaterialOnClick: No objects found with material \"" + this.materialToSwitch?.name + "\"");
}
}
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);
/**
* @category Everywhere Actions
* @group Components
*/
export class SetActiveOnClick extends Behaviour {
target;
toggleOnClick = false;
targetState = true;
hideSelf = true;
start() {
ensureRaycaster(this.gameObject);
}
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);
/**
* @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);
}
}
/**
* @category Everywhere Actions
* @group Components
*/
export class EmphasizeOnClick extends Behaviour {
target;
duration = 0.5;
motionType = "bounce";
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);
/**
* @category Everywhere Actions
* @group Components
*/
export class PlayAudioOnClick extends Behaviour {
target;
clip = "";
toggleOnClick = false;
// Not exposed, but used for implicit playback of PlayOnAwake audio sources
trigger = "tap";
start() {
ensureRaycaster(this.gameObject);
}
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;
}
}
}
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);
/**
* @category Everywhere Actions
* @group Components
*/
export class PlayAnimationOnClick extends Behaviour {
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; }
start() {
ensureRaycaster(this.gameObject);
}
onPointerClick(args) {
args.use();
if (!this.target)
return;
if (this.stateName) {
// 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;
}
// keep looking: transition to another state
else if (transition) {
currentState = nextState;
if (!currentState)
break;
visitedStates.push(currentState);
}
// abort: no transition found. check if last state is looping
else {
foundLoop = currentState.motion?.isLooping ?? false;
break;
}
}
if (foundLoop && currentState) {
// check what the first state in the loop is – it must be matching the last one we added
const firstStateInLoop = visitedStates.indexOf(currentState);
statesUntilLoop = visitedStates.slice(0, firstStateInLoop); // can be empty, which means we're looping all
statesLooping = visitedStates.slice(firstStateInLoop); // can be empty, which means nothing is looping
// Potentially we need to prevent self-transitions into a non-looping state, these do not result in a loop in the runtime
/*
if (statesLooping.length === 1 && !statesLooping[0].motion?.isLooping) {
statesUntilLoop.push(statesLooping[0]);
statesLooping = [];
}
*/
if (debug)
console.log("found loop from " + stateName, "states until loop", statesUntilLoop, "states looping", statesLooping);
}
else {
statesUntilLoop = visitedStates;
statesLooping = [];
if (debug)
console.log("found no loop from " + stateName, "states", statesUntilLoop);
}
// If we do NOT loop, we need to explicitly add a single-keyframe clip with a "hold" pose
// to prevent the animation from resetting to the start.
if (!statesLooping.length) {
const lastState = statesUntilLoop[statesUntilLoop.length - 1];
const lastClip = lastState.motion?.clip;
if (lastClip) {
let clipCopy;
if (ext.holdClipMap.has(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
const holdStateName = lastState.name + "_hold";
clipCopy = lastClip.clone();
clipCopy.duration = 1;
clipCopy.name = holdStateName;
const lastFrame = lastClip.duration;
clipCopy.tracks = lastClip.tracks.map(t => {
const trackCopy = t.clone();
trackCopy.times = new Float32Array([0, lastFrame]);
const len = t.values.length;
const size = t.getValueSize();
;
const lastValue = t.values.slice(len - size, len);
// we need this twice
trackCopy.values = new Float32Array(2 * size);
trackCopy.values.set(lastValue, 0);
trackCopy.values.set(lastValue, size);
return trackCopy;
});
clipCopy.name = holdStateName;
ext.holdClipMap.set(lastClip, clipCopy);
}
if (clipCopy) {
const holdState = {
name: clipCopy.name,
motion: { clip: clipCopy, isLooping: false, name: clipCopy.name },
speed: 1,
transitions: [],
behaviours: [],
hash: lastState.hash + 1,
};
statesLooping.push(holdState);
}
}
}
}
// Special case: someone's trying to play an empty clip without any motion data, no loops or anything.
// In that case, we simply go to the rest clip – this is a common case for "idle" states.
if (statesUntilLoop.length === 1 && (!statesUntilLoop[0].motion?.clip || statesUntilLoop[0].motion?.clip.tracks?.length === 0)) {
animationSequence = new Array();
const anim = ext.registerAnimation(target, null);
if (anim)
animationSequence.push(anim);
return undefined;
}
// filter out any states that don't have motion data
statesUntilLoop = statesUntilLoop.filter(s => s.motion?.clip && s.motion?.clip.tracks?.length > 0);
statesLooping = statesLooping.filter(s => s.motion?.clip && s.motion?.clip.tracks?.length > 0);
// If none of the found states have motion, we need to warn
if (statesUntilLoop.length === 0 && statesLooping.length === 0) {
console.warn("No clips found for state " + stateName + " on " + animator?.name + ", can't export animation data");
return undefined;
}
const addStateToSequence = (state, sequence) => {
if (!target)
return;
const anim = ext.registerAnimation(target, state.motion.clip ?? null);
if (anim) {
anim.speed = state.speed;
sequence.push(anim);
}
else
console.warn("Couldn't register animation for state " + state.name + " on " + animator?.name);
};
// Register all the animation states we found.
if (statesUntilLoop.length > 0) {
animationSequence = new Array();
for (const state of statesUntilLoop) {
addStateToSequence(state, animationSequence);
}
}
if (statesLooping.length > 0) {
animationLoopAfterSequence = new Array();
for (const state of statesLooping) {
addStateToSequence(state, animationLoopAfterSequence);
}
}
let randomTimeOffset = 0;
if (animator && runtimeController && animator.minMaxOffsetNormalized) {
const from = animator.minMaxOffsetNormalized.x;
const to = animator.minMaxOffsetNormalized.y;
// first state in the sequence
const firstState = statesUntilLoop.length ? statesUntilLoop[0] : statesLooping.length ? statesLooping[0] : null;
randomTimeOffset = (firstState?.motion.clip?.duration || 1) * (from + Math.random() * (to - from));
}
return {
animationSequence,
animationLoopAfterSequence,
randomTimeOffset,
};
}
createAnim