physics-animator 0.1.0

package/dist/three/ThreeAnimator.js

@@ -0,0 +1,450 @@
+import { Euler, Matrix4, Quaternion, Vector2, Vector3, Vector4 } from "three";
+import { Animator, Tween } from "../Animator.js";
+import { Spring } from "../Spring.js";
+export var QuaternionSpringMode;
+(function (QuaternionSpringMode) {
+    QuaternionSpringMode[QuaternionSpringMode["DirectionRollCartesian"] = 0] = "DirectionRollCartesian";
+    QuaternionSpringMode[QuaternionSpringMode["YawPitchRoll"] = 1] = "YawPitchRoll";
+})(QuaternionSpringMode || (QuaternionSpringMode = {}));
+/**
+ * Extends Animator to add support for animating vectors and quaternions
+ */
+export class ThreeAnimator {
+    animator;
+    get onAfterStep() {
+        return this.animator.onAfterStep;
+    }
+    get onBeforeStep() {
+        return this.animator.onBeforeStep;
+    }
+    quaternionSprings = new Map();
+    constructor(animator = new Animator()) {
+        this.animator = animator;
+        this.animator.onBeforeStep.on(e => this.stepQuaternionSprings(e.dt_s));
+    }
+    setTo(object, field, target) {
+        if (target instanceof Vector4) {
+            let v = object[field];
+            this.animator.setTo(v, 'x', target.x);
+            this.animator.setTo(v, 'y', target.y);
+            this.animator.setTo(v, 'z', target.z);
+            this.animator.setTo(v, 'w', target.w);
+        }
+        else if (target instanceof Vector3) {
+            let v = object[field];
+            this.animator.setTo(v, 'x', target.x);
+            this.animator.setTo(v, 'y', target.y);
+            this.animator.setTo(v, 'z', target.z);
+        }
+        else if (target instanceof Vector2) {
+            let v = object[field];
+            this.animator.setTo(v, 'x', target.x);
+            this.animator.setTo(v, 'y', target.y);
+        }
+        else if (target instanceof Quaternion) {
+            let q = object[field];
+            this.animator.setTo(q, 'x', target.x);
+            this.animator.setTo(q, 'y', target.y);
+            this.animator.setTo(q, 'z', target.z);
+            this.animator.setTo(q, 'w', target.w);
+        }
+        else if (target instanceof Euler) {
+            let e = object[field];
+            this.animator.setTo(e, 'x', target.x);
+            this.animator.setTo(e, 'y', target.y);
+            this.animator.setTo(e, 'z', target.z);
+            e.order = target.order;
+        }
+        else { // number
+            this.animator.setTo(object, field, target);
+        }
+    }
+    springTo(object, field, target, params = { duration_s: 0.5 }, mode) {
+        if (target instanceof Vector4) {
+            let v = object[field];
+            this.animator.springTo(v, 'x', target.x, params);
+            this.animator.springTo(v, 'y', target.y, params);
+            this.animator.springTo(v, 'z', target.z, params);
+            this.animator.springTo(v, 'w', target.w, params);
+        }
+        else if (target instanceof Vector3) {
+            let v = object[field];
+            this.animator.springTo(v, 'x', target.x, params);
+            this.animator.springTo(v, 'y', target.y, params);
+            this.animator.springTo(v, 'z', target.z, params);
+        }
+        else if (target instanceof Vector2) {
+            let v = object[field];
+            this.animator.springTo(v, 'x', target.x, params);
+            this.animator.springTo(v, 'y', target.y, params);
+        }
+        else if (target instanceof Quaternion) {
+            let q = object[field];
+            let spring = this.getQuaternionSpring(q);
+            // update
+            spring.target.copy(target).normalize();
+            spring.params = Spring.getPhysicsParameters(params);
+            spring.mode = mode ?? QuaternionSpringMode.DirectionRollCartesian;
+        }
+        else if (target instanceof Euler) {
+            let e = object[field];
+            this.animator.springTo(e, 'x', target.x, params);
+            this.animator.springTo(e, 'y', target.y, params);
+            this.animator.springTo(e, 'z', target.z, params);
+            e.order = target.order;
+        }
+        else { // number
+            this.animator.springTo(object, field, target, params);
+        }
+    }
+    customTweenTo(object, field, target, duration_s, step) {
+        if (target instanceof Vector4) {
+            let v = object[field];
+            this.animator.customTweenTo(v, 'x', target.x, duration_s, step);
+            this.animator.customTweenTo(v, 'y', target.y, duration_s, step);
+            this.animator.customTweenTo(v, 'z', target.z, duration_s, step);
+            this.animator.customTweenTo(v, 'w', target.w, duration_s, step);
+        }
+        else if (target instanceof Vector3) {
+            let v = object[field];
+            this.animator.customTweenTo(v, 'x', target.x, duration_s, step);
+            this.animator.customTweenTo(v, 'y', target.y, duration_s, step);
+            this.animator.customTweenTo(v, 'z', target.z, duration_s, step);
+        }
+        else if (target instanceof Vector2) {
+            let v = object[field];
+            this.animator.customTweenTo(v, 'x', target.x, duration_s, step);
+            this.animator.customTweenTo(v, 'y', target.y, duration_s, step);
+        }
+        else if (target instanceof Quaternion) {
+            throw new Error('Quaternion customTweenTo not yet supported, try springTo or use Euler');
+        }
+        else if (target instanceof Euler) {
+            let e = object[field];
+            this.animator.customTweenTo(e, 'x', target.x, duration_s, step);
+            this.animator.customTweenTo(e, 'y', target.y, duration_s, step);
+            this.animator.customTweenTo(e, 'z', target.z, duration_s, step);
+            e.order = target.order;
+        }
+        else { // number
+            this.animator.customTweenTo(object, field, target, duration_s, step);
+        }
+    }
+    linearTo(object, field, target, duration_s) {
+        this.customTweenTo(object, field, target, duration_s, Tween.linearStep);
+    }
+    easeInOutTo(object, field, target, duration_s) {
+        this.customTweenTo(object, field, target, duration_s, Tween.easeInOutStep);
+    }
+    easeInTo(object, field, target, duration_s) {
+        this.customTweenTo(object, field, target, duration_s, Tween.easeInStep);
+    }
+    easeOutTo(object, field, target, duration_s) {
+        this.customTweenTo(object, field, target, duration_s, Tween.easeOutStep);
+    }
+    step(dt_s) {
+        this.animator.step(dt_s);
+    }
+    tick() {
+        this.animator.tick();
+    }
+    remove(object, field) {
+        let v = object[field];
+        if (v instanceof Vector4) {
+            this.animator.remove(v, 'x');
+            this.animator.remove(v, 'y');
+            this.animator.remove(v, 'z');
+            this.animator.remove(v, 'w');
+        }
+        else if (v instanceof Vector3) {
+            this.animator.remove(v, 'x');
+            this.animator.remove(v, 'y');
+            this.animator.remove(v, 'z');
+        }
+        else if (v instanceof Vector2) {
+            this.animator.remove(v, 'x');
+            this.animator.remove(v, 'y');
+        }
+        else if (v instanceof Quaternion) {
+            this.quaternionSprings.delete(v);
+        }
+        else if (v instanceof Euler) {
+            this.animator.remove(v, 'x');
+            this.animator.remove(v, 'y');
+            this.animator.remove(v, 'z');
+        }
+        else { // number
+            this.animator.remove(object, field);
+        }
+    }
+    removeAll() {
+        this.animator.removeAll();
+        this.quaternionSprings.clear();
+    }
+    getVelocity(object, field, into) {
+        let target = object[field];
+        if (target instanceof Vector4) {
+            let i = into ?? new Vector4();
+            i.x = this.animator.getVelocity(target, 'x');
+            i.y = this.animator.getVelocity(target, 'y');
+            i.z = this.animator.getVelocity(target, 'z');
+            i.w = this.animator.getVelocity(target, 'w');
+            return i;
+        }
+        else if (target instanceof Vector3) {
+            let i = into ?? new Vector3();
+            i.x = this.animator.getVelocity(target, 'x');
+            i.y = this.animator.getVelocity(target, 'y');
+            i.z = this.animator.getVelocity(target, 'z');
+            return i;
+        }
+        else if (target instanceof Vector2) {
+            let i = into ?? new Vector2();
+            i.x = this.animator.getVelocity(target, 'x');
+            i.y = this.animator.getVelocity(target, 'y');
+            return i;
+        }
+        else if (target instanceof Quaternion) {
+            let spring = this.quaternionSprings.get(target);
+            return {
+                directionVelocity: spring?.directionVelocity ?? new Vector3(),
+                rollVelocity: spring?.rollVelocity ?? 0
+            };
+        }
+        else if (target instanceof Euler) {
+            let i = into ?? new Euler();
+            i.x = this.animator.getVelocity(target, 'x');
+            i.y = this.animator.getVelocity(target, 'y');
+            i.z = this.animator.getVelocity(target, 'z');
+            i.order = target.order;
+            return i;
+        }
+        else { // number
+            return this.animator.getVelocity(object, field);
+        }
+    }
+    startAnimationFrameLoop() {
+        return this.animator.startAnimationFrameLoop();
+    }
+    startIntervalLoop(interval_ms) {
+        return this.animator.startIntervalLoop(interval_ms);
+    }
+    stop() {
+        this.animator.stop();
+    }
+    stepQuaternionSprings(dt_s) {
+        // step quaternion springs
+        this.quaternionSprings.forEach((spring, q) => {
+            if (spring.params) {
+                if (spring.mode === QuaternionSpringMode.DirectionRollCartesian) {
+                    stepSpringQuaternion(dt_s, spring, spring.params);
+                }
+                else {
+                    stepSpringQuaternionSpherical(dt_s, spring, spring.params);
+                }
+            }
+            else {
+                // copy target
+                q.copy(spring.target);
+                // zero velocity
+                spring.directionVelocity.set(0, 0, 0);
+                spring.rollVelocity = 0;
+            }
+            // if quaternions match and velocity close to zero, remove spring
+            if (Math.abs(q.dot(spring.target)) > 0.999 && spring.directionVelocity.lengthSq() < 0.0001 && Math.abs(spring.rollVelocity) < 0.0001) {
+                this.quaternionSprings.delete(q);
+            }
+        });
+    }
+    getQuaternionSpring(q) {
+        let spring = this.quaternionSprings.get(q);
+        if (!spring) {
+            _m.makeRotationFromQuaternion(q);
+            let direction = new Vector3();
+            _m.extractBasis(new Vector3(), new Vector3(), direction);
+            spring = {
+                q: q,
+                target: new Quaternion(),
+                direction: direction,
+                directionVelocity: new Vector3(),
+                rollVelocity: 0,
+                params: null,
+                mode: QuaternionSpringMode.DirectionRollCartesian,
+            };
+            this.quaternionSprings.set(q, spring);
+        }
+        return spring;
+    }
+}
+/**
+ * Analytic quaternion spring
+ *
+ * Todo:
+ * - for cameras we want to prefer rotations in xz plane rather than z
+ * - animate direction in spherical space rather than cartesian
+ */
+// working variables to avoid allocations
+const _m = new Matrix4();
+const _x = new Vector3();
+const _y = new Vector3();
+const _z = new Vector3();
+const _qMatrix = new Matrix4();
+const _springState = { x: 0, v: 0, targetX: 0 };
+function stepSpringQuaternion(dt_s, state, parameters) {
+    // step direction spring in cartesian space
+    // we should do this in spherical in the future
+    let targetDirection = new Vector3();
+    let targetYBasis = new Vector3();
+    _m.makeRotationFromQuaternion(state.target);
+    _m.extractBasis(_x, targetYBasis, targetDirection);
+    let directionBefore = state.direction.clone();
+    // step spring direction
+    _springState.x = state.direction.x;
+    _springState.v = state.directionVelocity.x;
+    _springState.targetX = targetDirection.x;
+    Spring.stepSpring(dt_s, _springState, parameters);
+    state.direction.x = _springState.x;
+    state.directionVelocity.x = _springState.v;
+    _springState.x = state.direction.y;
+    _springState.v = state.directionVelocity.y;
+    _springState.targetX = targetDirection.y;
+    Spring.stepSpring(dt_s, _springState, parameters);
+    state.direction.y = _springState.x;
+    state.directionVelocity.y = _springState.v;
+    _springState.x = state.direction.z;
+    _springState.v = state.directionVelocity.z;
+    _springState.targetX = targetDirection.z;
+    Spring.stepSpring(dt_s, _springState, parameters);
+    state.direction.z = _springState.x;
+    state.directionVelocity.z = _springState.v;
+    // update quaternion
+    let directionDeltaQuaternion = new Quaternion().setFromUnitVectors(_x.copy(directionBefore).normalize(), _y.copy(state.direction).normalize());
+    state.q.premultiply(directionDeltaQuaternion);
+    // this forces synchronization of direction and quaternion
+    alignQuaternion(state.q, state.direction, _qMatrix);
+    // determine roll required to align yBasis with targetYBasis
+    let directionToTargetQuaternion = new Quaternion().setFromUnitVectors(state.direction.clone().normalize(), targetDirection);
+    _m.makeRotationFromQuaternion(state.q);
+    _m.extractBasis(_x, _y, _z);
+    let newYBasis = _y.applyQuaternion(directionToTargetQuaternion).clone();
+    let rollQuaternion = new Quaternion().setFromUnitVectors(newYBasis, targetYBasis);
+    // to axis angle (clamp w)
+    let rollAngle = Math.acos(Math.min(1, Math.max(-1, rollQuaternion.w))) * 2;
+    let rollSign = _x.crossVectors(newYBasis, targetYBasis).dot(targetDirection) < 0 ? -1 : 1;
+    rollAngle = -rollSign * rollAngle;
+    // step roll spring
+    _springState.x = rollAngle;
+    _springState.v = state.rollVelocity;
+    _springState.targetX = 0;
+    Spring.stepSpring(dt_s, _springState, parameters);
+    state.rollVelocity = _springState.v;
+    let rollAfter = _springState.x;
+    let rollDelta = rollAfter - rollAngle;
+    // apply roll correction
+    let rollDeltaQuaternion = new Quaternion().setFromAxisAngle(state.direction.clone().normalize(), rollDelta /*-rollAngle * 0.1*/);
+    state.q.premultiply(rollDeltaQuaternion);
+    state.q.normalize();
+}
+function stepSpringQuaternionSpherical(dt_s, state, parameters) {
+    let azimuthVelocity = state.directionVelocity.x;
+    let elevationVelocity = state.directionVelocity.y;
+    // get quaternion in spherical coordinates
+    let elAzRoll = quaternionToPitchYawRoll(state.q);
+    // get target quaternion in spherical coordinates
+    let targetElAzRoll = quaternionToPitchYawRoll(state.target);
+    // step springs
+    _springState.x = elAzRoll.x;
+    _springState.v = elevationVelocity;
+    _springState.targetX = getAngleContinuous(targetElAzRoll.x, elAzRoll.x);
+    Spring.stepSpring(dt_s, _springState, parameters);
+    elevationVelocity = _springState.v;
+    let elevationAfter = _springState.x;
+    _springState.x = elAzRoll.y;
+    _springState.v = azimuthVelocity;
+    _springState.targetX = getAngleContinuous(targetElAzRoll.y, elAzRoll.y);
+    Spring.stepSpring(dt_s, _springState, parameters);
+    azimuthVelocity = _springState.v;
+    let azimuthAfter = _springState.x;
+    // update directionVelocity
+    state.directionVelocity.x = azimuthVelocity;
+    state.directionVelocity.y = elevationVelocity;
+    // compose quaternion from spherical coordinates
+    // direction from azimuth and elevation
+    let direction = new Vector3(Math.cos(azimuthAfter) * Math.cos(elevationAfter), Math.sin(elevationAfter), Math.sin(azimuthAfter) * Math.cos(elevationAfter)).normalize();
+    // roll alignment spring
+    _springState.x = elAzRoll.z;
+    _springState.v = state.rollVelocity;
+    _springState.targetX = getAngleContinuous(targetElAzRoll.z, elAzRoll.z);
+    Spring.stepSpring(dt_s, _springState, parameters);
+    state.rollVelocity = _springState.v;
+    let rollAfter = _springState.x;
+    // compose quaternion from direction and roll
+    alignQuaternion(state.q, direction, _qMatrix);
+    setRoll(state.q, rollAfter);
+}
+function quaternionToPitchYawRoll(q, out = new Vector3()) {
+    // // get quaternion in spherical coordinates
+    _m.makeRotationFromQuaternion(q);
+    _m.extractBasis(_x, _y, _z);
+    // // azimuth and elevation are found from z direction
+    let azimuth = Math.atan2(_z.z, _z.x);
+    let elevation = Math.atan2(_z.y, Math.sqrt(_z.x * _z.x + _z.z * _z.z));
+    let roll = getRoll(q);
+    out.set(elevation, azimuth, roll);
+    return out;
+}
+function setRoll(q, roll) {
+    let currentRoll_rad = getRoll(q);
+    let deltaRoll = roll - currentRoll_rad;
+    let objectForward = new Vector3(0, 0, -1).applyQuaternion(q);
+    let rotation = new Quaternion().setFromAxisAngle(objectForward, deltaRoll);
+    q.premultiply(rotation);
+}
+/**
+ * Aligns quaternion
+ */
+const _zBasis = new Vector3();
+function alignQuaternion(q, direction, outMatrix = new Matrix4()) {
+    outMatrix.makeRotationFromQuaternion(q);
+    outMatrix.extractBasis(_x, _y, _z);
+    // must ensure _x and _y are orthogonal to zBasis
+    _zBasis.copy(direction).normalize();
+    _x.crossVectors(_y, _zBasis).normalize();
+    _y.crossVectors(_zBasis, _x).normalize();
+    outMatrix.makeBasis(_x, _y, _zBasis);
+    q.setFromRotationMatrix(outMatrix);
+    return outMatrix;
+}
+function getAngleContinuous(a, lastAngle) {
+    const tau = 2 * Math.PI;
+    let u = a / tau + 0.5;
+    let uLast = fract(lastAngle / tau + 0.5);
+    let du = u - uLast;
+    let angle;
+    if (Math.abs(du) < 0.5) {
+        angle = lastAngle + du * tau;
+    }
+    else {
+        // passed through 0
+        let duSmall = 1 - Math.abs(du);
+        angle = lastAngle + -Math.sign(du) * duSmall * tau;
+    }
+    return angle;
+}
+function fract(x) {
+    return x - Math.floor(x);
+}
+function getRoll(quaternion) {
+    return getQuaternionPlaneAngle(quaternion, new Vector3(0, 1, 0), new Vector3(0, 0, -1));
+}
+function getQuaternionPlaneAngle(quaternion, basisDirection, basisPlane) {
+    let objectDirection = basisDirection.clone().applyQuaternion(quaternion);
+    let objectPlane = basisPlane.clone().applyQuaternion(quaternion);
+    let objectDirectionProjected = objectDirection.projectOnPlane(objectPlane);
+    let worldZeroProjected = basisDirection.clone().projectOnPlane(objectPlane);
+    let angle = worldZeroProjected.angleTo(objectDirectionProjected);
+    // sign of angle
+    let sign = Math.sign(worldZeroProjected.cross(objectDirectionProjected).dot(objectPlane));
+    angle *= sign;
+    return angle;
+}

package/dist/three/index.d.ts

@@ -0,0 +1 @@
+export * from './ThreeAnimator.js';

package/dist/three/index.js

@@ -0,0 +1 @@
+export * from './ThreeAnimator.js';

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "physics-animator",
+  "version": "0.1.0",
+  "author": "haxiomic (George Corney)",
+  "license": "MIT",
+  "type": "module",
+  "description": "A TypeScript animation system grounded in physics with three.js and react support.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./dist/*/index.d.ts",
+      "import": "./dist/*/index.js"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "prepack": "rm -rf dist && npm run build",
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.12",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "@haxiomic/event-signal": "^1.0.0",
+    "use-initializer": "^1.0.2"
+  },
+  "peerDependencies": {
+    "@types/three": "x.x.x",
+    "react": ">=18.2.0",
+    "three": "x.x.x"
+  },
+  "peerDependenciesMeta": {
+    "@types/three": {
+      "optional": true
+    },
+    "three": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  }
+}

package/src/AnimationSequencer.ts

@@ -0,0 +1,193 @@
+import { EventSignal } from "@haxiomic/event-signal";
+
+export type Sequence = {
+    stop: () => void,
+    events: {
+        onStep: EventSignal<number>,
+        onComplete: EventSignal<void>,
+        onFinally: EventSignal<{ complete: boolean, stepIndex: number }>,
+    },
+    promise: Promise<void>,
+};
+
+export class AnimationSequencer {
+
+    timeoutHandles: Array<any> = [];
+    intervalHandles: Array<any> = [];
+    sequences: Array<Sequence> = [];
+    
+    constructor() {}
+
+    /**
+     * Execute a serial sequence of steps, firing a callback at each step. We either wait for the onCompleteEvent to be fired, or we wait for maxWait milliseconds before moving on to the next step.
+     * 
+     * @returns Sequence - a function that can be called to stop the sequence
+     */
+    runSequence = (steps: Array<{
+        callback: () => (Promise<void> | void),
+        maxWait_ms?: number,
+        onCompleteEvent?: EventSignal<any>
+    }>): Sequence => {
+        let sequenceEvents = {
+            onStep: new EventSignal<number>(),
+            onComplete: new EventSignal<void>(),
+            onFinally: new EventSignal<{ complete: boolean, stepIndex: number }>(),
+            onError: new EventSignal<any>(),
+        }
+
+        let openListeners = new Set<{ remove: () => void }>();
+        let timeoutHandles = new Array<any>();
+
+        let stepIndex = 0;
+
+        const executeStep = (index: number) => {
+            try {
+                // check if we've reached the end of the sequence
+                if (index >= steps.length) {
+                    sequenceEvents.onComplete.dispatch();
+                    sequenceEvents.onFinally.dispatch({
+                        complete: true,
+                        stepIndex: steps.length - 1,
+                    });
+                    return;
+                }
+
+                let step = steps[index];
+                if (!step) {
+                    throw new Error(`Step at index ${index} is undefined`);
+                }
+
+                sequenceEvents.onStep.dispatch(index);
+
+                let timeoutHandle: any = null;
+                let completeListener: { remove: () => void } | null = null;
+
+                if (step.onCompleteEvent) {
+                    let listener = step.onCompleteEvent.once(() => {
+                        openListeners.delete(listener);
+                    });
+                }
+
+                if (step.maxWait_ms) {
+                    timeoutHandle = this.setTimeout(() => next(), step.maxWait_ms);
+                    timeoutHandles.push(timeoutHandle);
+                }
+
+                if (!step.onCompleteEvent && !step.maxWait_ms) {
+                    next();
+                }
+
+                let hasFinished = false;
+                function next() {
+                    if (hasFinished) return;
+
+                    clearTimeout(timeoutHandle);
+                    completeListener?.remove();
+
+                    stepIndex++;
+                    hasFinished = true;
+                    executeStep(stepIndex);
+                }
+
+                let result = step.callback();
+                if ((result as any)['then']) {
+                    (result as Promise<any>).then(() => {
+                        // if no onCompleteEvent, then we can move on to the next step
+                        if (!step.onCompleteEvent) {
+                            next();
+                        }
+                    }).catch((error) => {
+                        sequenceEvents.onError.dispatch(error);
+                        stop();
+                    });
+                }
+            } catch (error) {
+                sequenceEvents.onError.dispatch(error);
+                stop();
+            }
+        }
+        
+        let stopped = false;
+        function stop() {
+            if (stopped) return;
+            for (let listener of openListeners) {
+                listener.remove();
+            }
+            for (let handle of timeoutHandles) {
+                clearTimeout(handle);
+            }
+            sequenceEvents.onFinally.dispatch({
+                complete: false,
+                stepIndex,
+            });
+            stopped = true;
+        }
+
+        // promise interface
+        let promise = new Promise<void>((resolve, reject) => {
+            sequenceEvents.onComplete.once(() => resolve());
+            sequenceEvents.onFinally.once(() => resolve());
+            sequenceEvents.onError.once((error) => reject(error));
+        });
+
+        let sequence = {
+            stop,
+            events: sequenceEvents,
+            promise,
+        }
+
+        // track sequence
+        this.sequences.push(sequence);
+        sequenceEvents.onFinally.once(() => {
+            let index = this.sequences.indexOf(sequence);
+            this.sequences.splice(index, 1);
+        });
+
+        // start
+        executeStep(stepIndex);
+
+        return sequence;
+    }
+
+    registerSequence = (sequence: Sequence) => {
+        this.sequences.push(sequence);
+        sequence.events.onFinally.once(() => {
+            let index = this.sequences.indexOf(sequence);
+            this.sequences.splice(index, 1);
+        });
+    }
+
+    setTimeout = (callback: Function, delay: number) => {
+        let handle = window.setTimeout(callback, delay);
+        this.timeoutHandles.push(handle);
+        return handle;
+    }
+
+    setInterval = (callback: Function, delay: number) => {
+        let handle = window.setInterval(callback, delay);
+        this.intervalHandles.push(handle);
+        return handle;
+    }
+
+    stopAllTimeouts = () => {
+        this.timeoutHandles.forEach(handle => clearTimeout(handle));
+        this.timeoutHandles = [];
+    }
+
+    stopAllIntervals = () => {
+        this.intervalHandles.forEach(handle => clearInterval(handle));
+        this.intervalHandles = [];
+    }
+
+    stopAllSequences = () => {
+        this.sequences.forEach(sequence => sequence.stop());
+        this.sequences = [];
+    }
+
+    stopAll = () => {
+        this.stopAllTimeouts();
+        this.stopAllIntervals();
+        this.stopAllSequences();
+    }
+
+}