Scripting API
ReactiveModule
ReactiveModule Overview

ReactiveModule

Exposes functionality for performing mathematical and logical operations with signals.
As the Spark AR API uses a reactive model to propagate data and values, regular JavaScript mathematical operations are not valid. Instead methods exposed by the Reactive module should be used, for example Reactive.add(scalarSignalX, scalarSignalY); adds two ScalarSignals together.


The module also exposes classes that describe signal equivalents for basic data types such as booleans and strings, as well as signal types specific to Spark AR.

Example

Properties

PropertyDescription

Box2D

(get) Box2D: Box2D
(set) Box2D: Box2D


Box3D

(get) Box3D: Box3D
(set) Box3D: Box3D


Color

(get) Color: Color
(set) Color: Color


ColorModel

(get) ColorModel: ColorModel
(set) ColorModel: ColorModel


Mat4

(get) Mat4: Mat4
(set) Mat4: Mat4


Rotation

(get) Rotation: Rotation
(set) Rotation: Rotation


Vec2

(get) Vec2: Vec2
(set) Vec2: Vec2


Vec3

(get) Vec3: Vec3
(set) Vec3: Vec3


Vec4

(get) Vec4: Vec4
(set) Vec4: Vec4


Methods

MethodDescription

abs

abs(x: ScalarSignal): ScalarSignal


Returns a signal with the value that is the absolute value of the given signal.
See Also: ScalarSignal.abs

acos

acos(x: ScalarSignal): ScalarSignal


Returns a signal with the value that is the inverse cosine of the value of the given signal (interpreted as radians).

add

add(x: ScalarSignal, y: ScalarSignal): ScalarSignal
add(x: PointSignal, y: Vec3Signal): PointSignal
add(x: Vec3Signal, y: PointSignal): PointSignal
add(x: Vec3Signal, y: Vec3Signal): Vec3Signal


Returns a signal with the value that is the sum of the values of the given signals.
Note: add and sum functions are synonyms, the behavior they provide is equivalent.

See Also: ReactiveModule.sum, ScalarSignal.add, PointSignal.add, Vec3Signal.add

and

and(lhs: BoolSignal, rhs: BoolSignal): BoolSignal


Returns a signal with the value that is the logical conjunction of the values of the given signals. It is true every time both input signals are true and false at all other times.
See Also: BoolSignal.and

andList

andList(x: Array<BoolSignal>): BoolSignal


Performs a logical AND operation with the array of BoolSignals specified and returns the result as a BoolSignal.
If all signals in the array are true then true is returned, otherwise false is returned.


  • x - the array of booleans to perform the logical AND operation with.


antiderivative

antiderivative(signal: ScalarSignal, config: {initialValue: number, max: number, min: number, overflowBehaviour: ReactiveModule.AntiderivativeOverflowBehaviour}): ScalarSignal


Estimates the antiderivative of the specified ScalarSignal with respect to time (in milliseconds) and returns the result as a ScalarSignal.

  • signal - the value to calculate the antiderivative of.
  • config - the configuration for the antiderivative output.


The config JSON object can have the following fields:


  • - the minimum value of the antiderivative output, if overflowBehaviour is set to CLAMP.
  • - the maximum value of the antiderivative output, if overflowBehaviour is set to CLAMP.
  • - the initial value of the antiderivative output.
  • - how the antiderivative output should behave when the values exceed min and max, as an AntiderivativeOverflowBehavior enum value. If set to CLAMP, the output is clamped to the min and max values. If set to WRAP, the output is wrapped around to the min value if max is exceeded and vice versa. The latter is often used when the output represents a cyclic value, such as an angle, which may have a min of 0 and a max of 2 * PI for example.


asin

asin(x: ScalarSignal): ScalarSignal


Returns a signal with the value that is the inverse sine of the value of the given signal (interpreted as radians).

atan

atan(x: ScalarSignal): ScalarSignal


Returns a signal with the value that is the inverse tangent of the value of the given signal (interpreted as radians).

atan2

atan2(x: ScalarSignal, y: ScalarSignal): ScalarSignal


Returns a signal with the value that is the angle in radians between the x-axis and the ray from (0, 0) to (x, y) where x and y are the values of the specified signals. The range is -PI to +PI.
See Also: ScalarSignal.atan2

boolSignalSource

boolSignalSource(sourceId: string): BoolSignalSource


Creates a new BoolSignalSource object, which allows for the value of a BoolSignal object to be updated without rebinding the signal.
The signal provided by the source contains a value of false until a value is assigned via BoolSignalSource.set().

When calling the method, avoid reusing the sourceId of an object that you've called dispose() on.


  • sourceId - the unique ID of the signal to create or retrieve.


boundingBox

boundingBox(x: ScalarSignal, y: ScalarSignal, width: ScalarSignal, height: ScalarSignal): Box2DSignal


Constructs a Box2DSignal with the dimensions specified by width and height, positioned at the location specified by x and y.
All arguments should be provided as normalized screen space units.


  • x - the x position of the top left corner of the bounding box, as a ScalarSignal.
  • y - the y position of the top left corner of the bounding box, as a ScalarSignal.
  • width - the width of the bounding box, as a ScalarSignal.
  • height - the height of the bounding box, as a ScalarSignal.


box2d

box2d(x: ScalarSignal, y: ScalarSignal, width: ScalarSignal, height: ScalarSignal): Box2DSignal


Constructs a Box2DSignal with the dimensions specified by width and height, positioned at the location specified by x and y.
All arguments should be provided as normalized screen space units.


  • x - the x position of the top left corner of the bounding box.
  • y - the y position of the top left corner of the bounding box.
  • width - the width of the bounding box.
  • height - the height of the bounding box.


box3d

box3d(min: PointSignal, max: PointSignal): Box3DSignal


Constructs a Box3DSignal with the provided min and max points.

  • min - the minimum point of the bounding box.
  • max - the maximum point of the bounding box.


ceil

ceil(x: ScalarSignal): ScalarSignal


Returns a signal with the value that is the smallest integer that is greater than or equal to the value of the given signal.
See Also: ScalarSignal.ceil

clamp

clamp(x: ScalarSignal, min: ScalarSignal, max: ScalarSignal): ScalarSignal


Returns a signal with the value that is the value of the given x signal constrained to lie between the values of the given min and max signals.
Note: The behavior is undefined if min is greater than max.

concat

concat(lhs: StringSignal, rhs: StringSignal): StringSignal


Joins two StringSignal objects and returns the result as a new StringSignal.
The values of the existing StringSignals passed as arguments are unaffected.

StringSignal objects provide their own equivalent concat() method that can be called directly from the object instead of through Reactive.concat().

var string0 = Reactive.val("Hello ");
var string1 = Reactive.val("world!");

var string2 = Reactive.concat(string0, string1);
// Value of 'string2': Hello world!



  • lhs - the first string to concatenate.
  • rhs - the second string to concatenate.


cos

cos(x: ScalarSignal): ScalarSignal


Returns a signal with the value that is the cosine of the value of the given signal (interpreted as radians).

cross

cross(v1: Vec3Signal, v2: Vec3Signal): PointSignal


Returns a vector signal with the value that is the cross product of the given signals.
See Also: Vec3Signal.dot, ScalarSignal.mul, Vec3Signal.mul

derivative

derivative(signal: ScalarSignal): ScalarSignal


Estimates the derivative of the specified ScalarSignal with respect to time (in milliseconds) and returns the result as a ScalarSignal.
As the rate of change is calculated with respect to time elapsed, the initial value of the derivative is always zero.

Input signals with constantly updating values, such as the openness signal exposed by the Mouth class, may produce a noisy derivative value. In these instances, it's recommended to first pass the input signal to the Reactive.expSmooth() method with a dampFactor between 100 and 500 before passing to this method.


  • signal - the value to calculate the derivative of.


distance

distance(v1: PointSignal, v2: PointSignal): ScalarSignal


Returns the distance from the point to another point as a ScalarSignal.

div

div(x: ScalarSignal, y: ScalarSignal): ScalarSignal


Returns a signal with the value that is the value of the first signal divided by the value of the second signal.
See Also: ScalarSignal.div

dot

dot(v1: Vec3Signal, v2: Vec3Signal): ScalarSignal


Returns a scalar signal with the value that is the dot product of the given signals.
See Also: Vec3Signal.cross, ScalarSignal.mul, Vec3Signal.mul

eq

eq(lhs: ScalarSignal, rhs: ScalarSignal): BoolSignal
eq(lhs: StringSignal, rhs: StringSignal): BoolSignal
eq(lhs: BoolSignal, rhs: BoolSignal): BoolSignal


Compares whether the left hand side signal's value is equal to the right hand side signal's value and returns the result as a BoolSignal.
ScalarSignal, StringSignal and BoolSignal objects can all be compared against another signal of the same type.

If the values are equal true is returned, otherwise false is returned.

The above object types also provide their own equivalent eq() method that can be called directly from the object instead of through Reactive.eq().


  • lhs - the first signal to compare.
  • rhs - the second signal to compare.


eventEmitter

eventEmitter(): EventEmitter


Creates a new EventEmitter object, which allows you to emit new events from an EventSource without rebinding it.
When calling the method, avoid reusing the sourceId of an object that you've called dispose() on.

exp

exp(x: ScalarSignal): ScalarSignal


Returns a signal with the value that is e (the Euler's constant 2.718...) to the power of the value of the given signal.

expSmooth

expSmooth(signal: ScalarSignal, dampFactor: number): ScalarSignal
expSmooth(signal: PointSignal, dampFactor: number): PointSignal
expSmooth(signal: Vec3Signal, dampFactor: number): Vec3Signal
expSmooth(signal: Mat4Signal, dampFactor: number): Mat4Signal


Smooths the specified variable signal using exponential averaging over time and returns the result as a signal of the same type.
The smoothed transformation for a signal that specifies a rigid body transformation is guaranteed to also be a rigid body transformation. The rotation component is smoothed in spherical coordinates using spherical linear interpolation (Slerp).

ScalarSignal, PointSignal, Vec3Signal and Mat4Signal objects each provide their own equivalent expSmooth() method that can be called directly from the object instead of through Reactive.expSmooth().


  • signal - the signal to smooth.
  • dampFactor - the dampening time constant, in milliseconds.


floor

floor(x: ScalarSignal): ScalarSignal


Returns a signal with the value that is the largest integer that is less than or equal to the value of the given signal.
See Also: ScalarSignal.floor

fromRange

fromRange(x: ScalarSignal, min: ScalarSignal, max: ScalarSignal): ScalarSignal


Maps x from [min, max] range to [0.0, 1.0] range.

ge

ge(lhs: ScalarSignal, rhs: ScalarSignal): BoolSignal


Compares whether the ScalarSignal value on the left hand side of the evaluation is greater than or equal to the ScalarSignal on the right hand side and returns the result as a BoolSignal.
If the left hand value is greater than or equal to the right hand value true is returned. If the left hand value is lower false is returned.

ScalarSignal objects provide their own equivalent ge() method that can be called directly from the object instead of through Reactive.ge().


  • lhs - the first scalar value to compare.
  • rhs - the second scalar value to compare.


gt

gt(lhs: ScalarSignal, rhs: ScalarSignal): BoolSignal


Compares whether the ScalarSignal value on the left hand side of the evaluation is greater than the ScalarSignal on the right hand side and returns the result as a BoolSignal.
If the left hand value is greater than the right hand value true is returned. If the left hand value is lower, or if the values are equal, false is returned.

ScalarSignal objects provide their own equivalent gt() method that can be called directly from the object instead of through Reactive.gt().


  • lhs - the first scalar value to compare.
  • rhs - the second scalar value to compare.


HSVA

HSVA(h: ScalarSignal | number, s: ScalarSignal | number, v: ScalarSignal | number, a: ScalarSignal | number): HsvaSignal


Constructs an HsvaSignal object from the individual component values specified.
The ScalarSignal or number passed into each component must contain a value between 0.0 and 1.0.


  • h - the hue component of the HSVA signal.
  • s - the saturation component of the HSVA signal.
  • v - the value component of the HSVA signal.
  • a - the alpha component of the HSVA signal.


ifThenElse

ifThenElse<T, U>(condition: BoolSignal | boolean, thenValue: EventSource<T>, elseValue: EventSource<U>): EventSource<T | U>
ifThenElse(condition: BoolSignal | boolean, thenValue: ScalarSignal | number, elseValue: ScalarSignal | number): ScalarSignal
ifThenElse(condition: BoolSignal | boolean, thenValue: StringSignal | string, elseValue: StringSignal | string): StringSignal
ifThenElse(condition: BoolSignal | boolean, thenValue: BoolSignal | boolean, elseValue: BoolSignal | boolean): BoolSignal


Returns a signal or an EventSource which at any point of time takes the value (passes the events in case of EventSource) of one or another inputs, depending on the momentary value of the given condition BoolSignal.

le

le(lhs: ScalarSignal, rhs: ScalarSignal): BoolSignal


Compares whether the ScalarSignal value on the left hand side of the evaluation is less than or equal to the ScalarSignal on the right hand side and returns the result as a BoolSignal.
If the left hand value is lower than or equal to the right hand value true is returned. If the left hand value is greater false is returned.

ScalarSignal objects provide their own equivalent le() method that can be called directly from the object instead of through Reactive.le().


  • lhs - the first scalar value to compare.
  • rhs - the second scalar value to compare.


log

log(x: ScalarSignal): ScalarSignal


Returns a signal with the value that is the natural logarithm of the value of the given signal.

lookAt

lookAt(eyeTransform: Mat4Signal, targetPosition: PointSignal, eyeUp?: Vec3Signal): Mat4Signal


Returns a Mat4Signal object with its rotation set in the direction of the specified target.
Create a new null object in Spark AR Studio and place the object to use as the 'eye' object within it. Then, pass the null object's transform to the lookAt method, for example:

(async function () {  // Enables async/await in JS [part 1]

// Locate the objects in the scene
const [nullObject, plane0, plane1] = await Promise.all([

// The object to rotate's null parent object
Scene.root.findFirst('nullObject0'),

// The object to rotate
Scene.root.findFirst('plane0'),

// The object to look at
Scene.root.findFirst('plane1')
]);

// Create a new transform with rotation set in the direction of the target
// The null object's transform is passed as the 'eyeTransform' argument
// instead of the plane0's transform
const lookAtTransform = Reactive.lookAt(nullObject.transform.toSignal(),
plane1.transform.position);

// Update the plane0 object's rotation with the rotational values from the
// 'lookAt' transform signal
plane0.transform.rotationX = lookAtTransform.rotationX;
plane0.transform.rotationY = lookAtTransform.rotationY;
plane0.transform.rotationZ = lookAtTransform.rotationZ;

})(); // Enables async/await in JS [part 2]



  • eyeTransform - the transform of the 'eye' object that is looking at the target object, as a Mat4Signal. This transform needs to point the scene object along the x axis.
  • targetPosition - the position of the target object, as a PointSignal.
  • eyeUp - an optional Vec3Signal specifying the 'up' direction of the eye origin. If no value is specified, a vector of (0, 1, 0) is used by default.


lt

lt(lhs: ScalarSignal, rhs: ScalarSignal): BoolSignal


Compares whether the ScalarSignal value on the left hand side of the evaluation is less than the ScalarSignal on the right hand side and returns the result as a BoolSignal.
If the left hand value is lower than the right hand value true is returned. If the left hand value is greater, or if the values are equal, false is returned.

ScalarSignal objects provide their own equivalent lt() method that can be called directly from the object instead of through Reactive.lt().


  • lhs - the first scalar value to compare.
  • rhs - the second scalar value to compare.


magnitude

magnitude(v: Vec3Signal): ScalarSignal


Returns the magnitude of the vector as a ScalarSignal.

magnitudeSquared

magnitudeSquared(signal: ScalarSignal): ScalarSignal
magnitudeSquared(signal: Vec2Signal): ScalarSignal
magnitudeSquared(signal: Vec3Signal): ScalarSignal
magnitudeSquared(signal: Vec4Signal): ScalarSignal


Returns the squared length (magnitude) of a given signal.
Calculating the squared magnitude instead of the magnitude is much faster.
Often if you are comparing magnitudes of two vectors you can just compare their squared magnitudes.

max

max(x: ScalarSignal, y: ScalarSignal): ScalarSignal


Returns a signal with the value that is the greater of the values of the given signals.

min

min(x: ScalarSignal, y: ScalarSignal): ScalarSignal


Returns a signal with the value that is the lesser of the values of the given signals.

mix

mix(x: ScalarSignal, y: ScalarSignal, alpha: ScalarSignal): ScalarSignal
mix(x: PointSignal, y: PointSignal, alpha: ScalarSignal): PointSignal
mix(x: Vec3Signal, y: Vec3Signal, alpha: ScalarSignal): Vec3Signal
mix(x: Mat4Signal, y: Mat4Signal, alpha: ScalarSignal): Mat4Signal
mix(x: ShaderSignal, y: ShaderSignal, alpha: ScalarSignal): ShaderSignal


Returns a signal with the value that is the interpolation of the values of the given signals.

mod

mod(x: ScalarSignal, y: ScalarSignal): ScalarSignal


Returns a signal with the value that is the floating-point remainder of the division of the value of the first signal by the value of the second signal.
See Also: ScalarSignal.mod

monitorMany

monitorMany(signals: {[name: string]: ScalarSignal}, config?: {fireOnInitialValue?: false | true}): EventSource<{newValues: {[key: string]: number}, oldValues: {[key: string]: number}}>


Returns an EventSource that emits an event whenever the value of any of the specified input signals changes.
The event contains a JSON object which provides the old and new values of the signals in the format { "oldValues": oldValues, "newValues": newValues }.

oldValues is itself a JSON object, the keys of which are the names of the signals as specified in the method call and the values of which are each signals' previous values. The newValues JSON object uses the same keys but provides each signals' new value.


  • signals - the array of ScalarSignals to track the values of.
  • config - an optional configuration for the event source.


The config JSON object can have the following field:

  • - Specifies whether an initial event should be emitted containing the signals' initial values. If no value is specified, false is used by default. If set to true, an initial event will be emitted but oldValues will not be available for the first instance.


// Load in the required modules
const Reactive = require('Reactive');
const HandTracking = require('HandTracking');

// Create a new ScalarSignal
var scalarValue = Reactive.val(1);

// Monitor changes to the values of the hand tracking count or
// 'scalarValue' signals
Reactive.monitorMany({
"handsDetected": HandTracking.count,
"scalarValue": scalarValue
},

{fireOnInitialValue: false}).subscribe((event) => {
// Log the old and new values of the hand tracking count signal
Diagnostics.log(Old hand count value: ${event.oldValues.handsDetected});
Diagnostics.log(New hand count value: ${event.newValues.handsDetected});
});


mul

mul(x: ScalarSignal, y: ScalarSignal): ScalarSignal
mul(x: Vec3Signal, y: ScalarSignal): Vec3Signal
mul(x: ScalarSignal, y: Vec3Signal): Vec3Signal
mul(x: Vec3Signal, y: Vec3Signal): Vec3Signal


Returns a signal with the value that is the product of the values of the given signals.
See Also: ScalarSignal.mul, Vec3Signal.mul

mulList

mulList(x: Array<number | ScalarSignal>): ScalarSignal


Returns a ScalarSignal containing the value that is the product of all of the values in the array specified.
const numArray = [2, 3, 4];
const arrayMul = Reactive.mulList(numArray); // Returns 24 (24)



  • x - an array of numbers and/or ScalarSignals to multiply together.


ne

ne(lhs: ScalarSignal, rhs: ScalarSignal): BoolSignal
ne(lhs: StringSignal, rhs: StringSignal): BoolSignal
ne(lhs: BoolSignal, rhs: BoolSignal): BoolSignal


Compares whether the left hand side signal's value is not equal to the right hand side signal's value and returns the result as a BoolSignal.
ScalarSignal, StringSignal and BoolSignal objects can all be compared against another signal of the same type.

If the values are not equal true is returned, otherwise false is returned.

The above object types also provide their own equivalent ne() method that can be called directly from the object instead of through Reactive.ne().


  • lhs - the first signal to compare.
  • rhs - the second signal to compare.


neg

neg(x: ScalarSignal): ScalarSignal
neg(x: Vec3Signal): Vec3Signal


Returns a signal with the negated value of the given signal.
See Also: ScalarSignal.neg, Vec3Signal.neg

normalize

normalize(v: Vec3Signal): Vec3Signal


Returns the normalized (unit) vector in the direction of the original vector as a Vec3Signal.

not

not(signal: BoolSignal): BoolSignal


Performs a logical NOT operation with the BoolSignal specified and returns the result as a BoolSignal.
If a signal with a value of true is passed to the method false will be returned and vice versa.

BoolSignal objects provide their own equivalent not() method that can be called directly from the object instead of through Reactive.not().


  • signal - the boolean to perform the logical NOT operation with.


once

once(): EventSource<void>


Returns an EventSource that emits an empty event a single time, as soon as it is able to.

or

or(lhs: BoolSignal, rhs: BoolSignal): BoolSignal


Returns a signal with the value that is the logical disjunction of the values of the given signals. It is true every time at least one of the input signals is true and false at all other times.
See Also: BoolSignal.or

orList

orList(x: Array<BoolSignal>): BoolSignal


Performs a logical OR operation with the array of BoolSignals specified and returns the result as a BoolSignal.
If any of the signals in the array are true then true is returned, otherwise false is returned.


  • x - the array of booleans to perform the logical OR operation with.


pack2

pack2(x: ScalarSignal, y: ScalarSignal): Vec2Signal
pack2(x: ScalarSignal, y: Vec2Signal): PointSignal
pack2(x: Vec2Signal, y: ScalarSignal): PointSignal
pack2(x: ScalarSignal, y: PointSignal): Vec4Signal
pack2(x: PointSignal, y: ScalarSignal): Vec4Signal
pack2(x: Vec2Signal, y: Vec2Signal): Vec4Signal


Packs two Scalar or Point signals into a bigger Point signal.

pack3

pack3(x: ScalarSignal, y: ScalarSignal, z: ScalarSignal): PointSignal
pack3(x: ScalarSignal, y: ScalarSignal, z: Vec2Signal): Vec4Signal
pack3(x: ScalarSignal, y: Vec2Signal, z: ScalarSignal): Vec4Signal
pack3(x: Vec2Signal, y: ScalarSignal, z: ScalarSignal): Vec4Signal


Packs three Scalar or Point signals into a bigger Point signal.

pack4

pack4(x: ScalarSignal, y: ScalarSignal, z: ScalarSignal, w: ScalarSignal): Vec4Signal


Packs four ScalarSignals into a Vec4Signal.

point

point(x: ScalarSignal | number, y: ScalarSignal | number, z: ScalarSignal | number): PointSignal


Constructs a PointSignal representing a 3D coordinate from the three ScalarSignal or number values provided.

  • x - the x component of the 3D coordinate.
  • y - the y component of the 3D coordinate.
  • z - the z component of the 3D coordinate.


point2d

point2d(x: ScalarSignal | number, y: ScalarSignal | number): Vec2Signal


Constructs a Vec2Signal from the two ScalarSignal or number values provided.

  • x - the x component of the 2D vector.
  • y - the y component of the 2D vector.


pow

pow(base: ScalarSignal, exponent: ScalarSignal): ScalarSignal


Returns a signal with the value that is the base signal raised to the power of the exponent signal.
The result is undefined if the base is negative, or if the base is zero and the exponent is not positive.

See Also: ScalarSignal.pow

quaternion

quaternion(w: ScalarSignal, x: ScalarSignal, y: ScalarSignal, z: ScalarSignal): QuaternionSignal


Constructs a QuaternionSignal with the component values specified.



quaternionFromAngleAxis

quaternionFromAngleAxis(angle: ScalarSignal, axis: Vec3Signal): QuaternionSignal


Constructs a QuaternionSignal from the rotation specified by the angle and normalized axis.

  • angle - the angle of the rotation, as a ScalarSignal. Specifies the magnitude of the rotation about axis.
  • axis - the direction of the axis of rotation, as a Vec3Signal.


quaternionFromEuler

quaternionFromEuler(x: ScalarSignal, y: ScalarSignal, z: ScalarSignal): QuaternionSignal


Constructs a QuaternionSignal from the rotation specified by the euler angle.

  • x - the x axis value of the euler angle, as a ScalarSignal. Represents pitch.
  • y - the y axis value of the euler angle, as a ScalarSignal. Represents yaw.
  • z - the z axis value of the euler angle, as a ScalarSignal. Represents roll.


quaternionFromTo

quaternionFromTo(from: Vec3Signal, to: Vec3Signal): QuaternionSignal


Calculates the rotation required to rotate the from vector to the to vector and returns the result as a QuaternionSignal.



quaternionIdentity

quaternionIdentity(): QuaternionSignal


Constructs a QuaternionSignal that represents an identity quaternion.

quaternionLookAt

quaternionLookAt(targetPosition: PointSignal, selfUp?: Vec3Signal): QuaternionSignal


Constructs a QuaternionSignal representing rotation in the direction of a normalized target direction vector.

  • targetPosition - the position of the target, as a PointSignal.
  • selfUp - an optional Vec3Signal specifying the 'up' direction. If no value is specified, a vector of (0, 1, 0) is used by default.


reflect

reflect(incident: Vec3Signal, normal: Vec3Signal): Vec3Signal


Calculates the reflection direction for an incident vector and a normal as a Vec3Signal.

RGBA

RGBA(r: ScalarSignal | number, g: ScalarSignal | number, b: ScalarSignal | number, a: ScalarSignal | number): RgbaSignal


Constructs an RgbaSignal object from the individual component values specified.
The ScalarSignal or number passed into each component must contain a value between 0.0 and 1.0.

The RGB components are interpreted in sRGB color space.


  • r - the red component of the RGBA signal.
  • g - the blue component of the RGBA signal.
  • b - the green component of the RGBA signal.
  • a - the alpha component of the RGBA signal.


rotation

rotation(w: number, x: number, y: number, z: number): Rotation


Creates a Rotation from the quaternion components specified.

  • w - the w component of the quaternion.
  • x - the x component of the quaternion.
  • y - the y component of the quaternion.
  • z - the z component of the quaternion.


round

round(x: ScalarSignal): ScalarSignal


Returns a signal with the value that is the rounded value of the given signal.
Note: When the fractional part is 0.5, it rounds the number away from zero, which is at odds with JavaScript standard behavior of rounding it always up in such cases. Therefore, this function is NOT exactly the reactive counterpart of the standard JavaScript Math.round utility.

See Also: ScalarSignal.round

scalarSignalSource

scalarSignalSource(sourceId: string): ScalarSignalSource


Creates a new ScalarSignalSource object, which allows for the value of a ScalarSignal object to be updated without rebinding the signal.
The signal provided by the source contains a value of 0 until a value is assigned via ScalarSignalSource.set().

When calling the method, avoid reusing the sourceId of an object that you've called dispose() on.


  • sourceId - the unique ID of the signal to create or retrieve.


scale

scale(x: ScalarSignal | number, y: ScalarSignal | number, z: ScalarSignal | number): PointSignal


Constructs a PointSignal representing a 3D scale from the three ScalarSignal or number values provided.

  • x - the x component of the 3D scale.
  • y - the y component of the 3D scale.
  • z - the z component of the 3D scale.


schmittTrigger

schmittTrigger(signal: ScalarSignal, config: {high: number, initialValue?: false | true, low: number}): BoolSignal


Returns a BoolSignal with true if the ScalarSignal provided is higher than the upper threshold specified, or false if the signal is lower than the lower threshold specified.
If the signal contains a value within, or equal to, the threshold values this method returns the same boolean value it contained in the previous update, or the value specified by initialValue if this is the first update.

var scalar = Reactive.val(12);

const valAboveThreshold = Reactive.schmittTrigger(scalar, {
"low": 5,
"high": 10,
"initialValue": false
});

// schmittTrigger() returns 'true' because the value of 'scalar' (12) is
// higher than the upper threshold specified (10)



  • signal - the ScalarSignal to monitor.
  • config - the configuration for the threshold values.


The config JSON object can have the following fields:

  • - the lower threshold. If signal is lower than this, the method returns false.
  • - the upper threshold. If signal is higher than this, the method returns true.
  • - an optional initial value for the boolean returned by the method. If no value is specified, this is set to false by default.


sign

sign(x: ScalarSignal): ScalarSignal


Returns a signal with the value that is the sign of the given signal. Possible sign values: NaN, -0.0, 0.0, -1.0, 1.0.
Note: this function is the reactive counterpart of the standard JavaScript Math.sign utility.

See Also: ScalarSignal.sign

signalHistory

signalHistory<T>(source: EventSource<T>, count: number): EventSourceHistory<T>
signalHistory<T>(signal: Signal<T>, count: number, initialValues?: Array<T>): SignalHistory<T>


Returns an object containing the values of the specified signal from previous frames.
If the method is called with an EventSource as the source, an EventSourceHistory object is returned. However, if a Signal is specified in the method call instead, a SignalHistory object is returned.


  • source - the EventSource containing the signal to access previous values from.
  • signal - the signal to access previous values from.
  • count - the number of frames to track the signal value for.
  • initialValues - sets the initial value of the signal. If unspecified, the value of the signal when the method is called is used instead. Not valid if and EventSource object is passed in the method call.


sin

sin(x: ScalarSignal): ScalarSignal


Returns a signal with the value that is the sine of the value of the given signal (interpreted as radians).

smoothStep

smoothStep(x: ScalarSignal, edge0: ScalarSignal, edge1: ScalarSignal): ScalarSignal


Returns 0.0 if x is less than edge0, and 1.0 if x is greater than edge1.
If x is between edge0 and edge1, smooth Hermite interpolation is performed.

sqrt

sqrt(x: ScalarSignal): ScalarSignal


Returns a signal with the value that is the square root of the value of the given signal.
See Also: ScalarSignal.sqrt

step

step(x: ScalarSignal, edge: ScalarSignal): ScalarSignal


Returns 0.0 if x is less than edge, and 1.0 is returned otherwise.

stringSignalSource

stringSignalSource(sourceId: string): StringSignalSource


Creates a new StringSignalSource object, which allows for the value of a StringSignal object to be updated without rebinding the signal.
The signal provided by the source contains an empty string until a value is assigned via StringSignalSource.set().

When calling the method, avoid reusing the sourceId of an object that you've called dispose() on.


  • sourceId - the unique ID of the signal to create or retrieve.


sub

sub(x: ScalarSignal, y: ScalarSignal): ScalarSignal
sub(x: PointSignal, y: Vec3Signal): PointSignal
sub(x: Vec3Signal, y: Vec3Signal): Vec3Signal
sub(x: PointSignal, y: PointSignal): Vec3Signal


Returns a signal with the value that is the difference of the values of the given signals.
See Also: ScalarSignal.sub, Vec3Signal.sub, PointSignal.sub

sum

sum(x: ScalarSignal, y: ScalarSignal): ScalarSignal
sum(x: PointSignal, y: Vec3Signal): PointSignal
sum(x: Vec3Signal, y: PointSignal): PointSignal
sum(x: Vec3Signal, y: Vec3Signal): Vec3Signal


Returns a signal with the value that is the sum of the values of the given signals.
Note: add and sum functions are synonyms, the behavior they provide is equivalent.

See Also: ReactiveModule.sum, ScalarSignal.add, PointSignal.add, Vec3Signal.add

sumList

sumList(x: Array<number | ScalarSignal>): ScalarSignal


Returns a ScalarSignal containing the value that is the sum of all of the values in the array specified.
const numArray = [1, 2, 3];
const arraySum = Reactive.sumList(numArray); // Returns 6 (1 + 2 + 3)



  • x - an array of numbers and/or ScalarSignals to add together.


switch

switch(condition: StringSignal, map: {[key: string]: string}, defaultValue: string): StringSignal


Returns a StringSignal object, the value of which is determined by the current value of the condition argument.
If the value of the condition matches a key from map, the the corresponding value is assigned to the returned StringSignal. Otherwise, defaultValue is assigned.

var condition = Reactive.val("Option 0");

var switchString = Reactive.switch(condition, {
"Option 0": "Apple",
"Option 1": "Banana",
"Option 2": "Orange"
}, "Mango");

// Value of 'switchString': Apple



  • condition - the StringSignal to monitor the value of.
  • map - a map containing key-value pairs to compare condition against. If condition matches a key, the corresponding value is assigned to the StringSignal returned by the method.
  • defaultValue - the default value to assign to the StringSignal returned by the method, if condition does not match any of the keys from map.


tan

tan(x: ScalarSignal): ScalarSignal


Returns a signal with the value that is the tangent of the value of the given signal (interpreted as radians).

toRange

toRange(x: ScalarSignal, min: ScalarSignal, max: ScalarSignal): ScalarSignal


Maps x from [0.0, 1.0] range to [min, max] range.

transform

transform(translation: PointSignal, scale: PointSignal, rotation: QuaternionSignal): Mat4Signal


Creates a scene object transform from translation, scale and rotation rotation

val

val(constant: number): ScalarSignal
val(constant: string): StringSignal
val(constant: boolean): BoolSignal
val(constant: Box2D): Box2DSignal
val(constant: Point3D | Vec3): PointSignal
val(constant: Point2D | Vec2): Vec2Signal
val(constant: Vec4): Vec4Signal
val(constant: Box3D): Box3DSignal
val(constant: Rotation): QuaternionSignal
val(constant: Mat4): Mat4Signal


Returns a signal containing a constant value, as specified by the argument.
The type of signal returned (ScalarSignal, StringSignal, BoolSignal, Box2DSignal, Box3DSignal, Vec2Signal, PointSignal, Vec4Signal, QuaternionSignal, or Mat4Signal) depends on the value passed.

Raw JavaScript types (number, string, bool, Box2D, Point3D, Vec3, Point2D, Vec2, Vec4, Box3D, Rotation, Mat4) are implicitly converted to their signal equivalents when passed as a method argument or when setting a property. Converting the values to signals with Reactive.val() method is not required.


  • val - the value to assign to the constructed signal.


vector

vector(x: ScalarSignal | number, y: ScalarSignal | number, z: ScalarSignal | number): Vec3Signal


Constructs a Vec3Signal from the three ScalarSignal or number values provided.

  • x - the x component of the 3D vector.
  • y - the y component of the 3D vector.
  • z - the z component of the 3D vector.


xor

xor(lhs: BoolSignal | boolean, rhs: BoolSignal | boolean): BoolSignal


Performs a logical XOR operation with the BoolSignals specified and returns the result as a BoolSignal.
If only one of the signals specified is true then true is returned. If both, or neither, of the signals are true then false is returned.

BoolSignal objects provide their own equivalent xor() method that can be called directly from the object instead of through Reactive.xor().


  • lhs - the first boolean to perform the logical XOR operation with.
  • rhs - the second boolean to perform the logical XOR operation with.


xorList

xorList(x: Array<BoolSignal>): BoolSignal


Performs a logical XOR operation with the array of BoolSignals specified and returns the result as a BoolSignal.
If only one of the signals in the array is true then true is returned. If more than one, or none, of the signals are true then false is returned.


  • x - the array of booleans to perform the logical XOR operation with.


Classes

ClassDescription
AnimationBlendThe AnimationBlend class combines an array of AnimationBlendInputs to drive animation blending.
Applying to a target ThreeDObject allows playing a blended animation from a collection of blend inputs.

AnimationBlendInputThe AnimationBlendInput class describes an input used for animation blending.
Each input is composed of an AnimationClip, progress ScalarSignal, and weight ScalarSignal.

'clip' - the source animation clip from which to sample animation data.
'progress' - the time driver controlling at which point in time to sample the above clip. Ranges from 0 to 1.
'weight' - the amount this input affects the final blend. Weights for all blend inputs ideally add up to 1.

AnimationClipSignalThe AnimationClipSignal class describes the MultiChannelSampler loaded from an animation in a .glb asset file.
Transmitting a signal to this clip through blocks i/o allows playing animations from externally downloaded blocks.

BoolSignalMonitors a boolean value and exposes functionality for performing logical operations with a given signal.

BoolSignalSourceRepresents a source used to get and set the value of a BoolSignal.
Typically, changing the value that a signal contains requires a total reassignment:

TouchGestures.onTap().subscribe((gesture) => {
someSignal = Reactive.val(true);
});


In the example above, someSignal is bound to a completely new signal which itself contains the desired value.

The BoolSignalSource API provides the ability to change the value of the original signal without reassignment, with behavior similar to that of non-reactive programming models.

Box2DThe Box2D class describes a 2D bounding box value.

Box2DSignalThe Box2DSignal class monitors a 2D bounding box value.

Box3DThe Box3D class describes the bounds in 3D space.

Box3DSignalThe Box3DSignal class describes the bounds in 3D space.

ColorSignalThe ColorSignal class monitors a color.

EventSourceThe EventSource class provides methods for monitoring signals.

EventSourceHistoryThe EventSourceHistory encapsulates methods for accessing values of EventSource from previous frames.

HsvaSignalThe HsvaSignal class monitors a HSVA color value.

ISignalThe ISignal interface. The base class for ScalarSignal, PointSignal, Vec3Signal, BoolSignal, and StringSignal.

Mat4The Mat4 class contains a 4D Matrix.

Mat4SignalThe Mat4Signal class monitors a scene transform.

Point2DThe Point2D class contains a 2D coordinate.

Point3DThe Point3D class contains a 3D coordinate.

PointSignalThe PointSignal class monitors a 3D coordinate.

PrimitiveOrShaderSignalThe PrimitiveOrShader represents a primitive or shader signal.

QuaternionSignalThe QuaternionSignal class monitors rotation in a quaternion representation.

RgbaSignalThe RgbaSignal class monitors a RGBA color value.

RotationThe Rotation class encapsulates an object's rotation in a quaternion representation.

ScalarSignalMonitors a numerical value and exposes functionality for performing mathematical operations with the given signal.

ScalarSignalSourceRepresents a source used to get and set the value of a ScalarSignal.
Typically, changing the value that a signal contains requires a total reassignment:

TouchGestures.onTap().subscribe((gesture) => {
someSignal = Reactive.val(1);
});


In the example above, someSignal is bound to a completely new signal which itself contains the desired value.

The ScalarSignalSource API provides the ability to change the value of the original signal without reassignment, with behavior similar to that of non-reactive programming models.

ShaderSignalThe ShaderSignal represents a shader signal. Scalar and Vector signals can be automatically converted to a ShaderSignal.

SignalHistoryThe SignalHistory<T> class encapsulates methods for accessing values from previous frames.

StringSignalMonitors a string value.

StringSignalSourceRepresents a source used to get and set the value of a StringSignal.
Typically, changing the value that a signal contains requires a total reassignment:

TouchGestures.onTap().subscribe((gesture) => {
someSignal = Reactive.val("Hello");
});


In the example above, someSignal is bound to a completely new signal which itself contains the desired value.

The StringSignalSource API provides the ability to change the value of the original signal without reassignment, with behavior similar to that of non-reactive programming models.

SubscriptionThe Subscription class implements object value monitoring.

Vec2The Vec2 class contains a 2D coordinate.

Vec2SignalThe Vec2Signal class monitors a 2D coordinate.

Vec3The Vec3 class contains a 3D coordinate.

Vec3SignalThe Vec3Signal class monitors a vector.

Vec4The Vec4 class contains a 4D coordinate.

Vec4SignalThe Vec4Signal class monitors a 4D coordinate.

Enums

EnumDescription
AntiderivativeOverflowBehaviourThe AntiderivativeOverflowBehaviour enum describes the recovery technique used when an
antiderivative overflows.