Utils

NOTE: This version of the documentation tracks unstable development happening on A-Frame’s master branch. If you wish to try it out, grab the unstable build. Otherwise, head to the documentation for the current 1.6.0 version

A-Frame’s utility modules are public through AFRAME.utils.

AFRAME.utils.coordinates

Module for handling vec3 and vec4 types.

.isCoordinates (value)

Tests whether a string is a vec3 or vec4.

AFRAME.utils.coordinates.isCoordinates('1 2 3')
// >> true

AFRAME.utils.coordinates.isCoordinates('1 2 3 4')
// >> true

.parse (value)

Parses an “x y z” string to an {x, y, z} vec3 object. Or parses an “x y z w” string to an {x, y, z, w} vec4 object.

AFRAME.utils.coordinates.parse('1 2 -3')
// >> {x: 1, y: 2, z: -3}

.stringify (data)

Stringifies an {x, y, z} vec3 object to an “x y z” string.Or Stringifies an {x, y, z, w} vec4 object to an “x y z w” string.

AFRAME.utils.coordinates.stringify({x: 1, y: 2, z: -3})
// >> "1 2 -3"

AFRAME.utils.coordinates.stringify({x: 1, y: 2, z: -3, w:4})
// >> "1 2 -3 4"

AFRAME.utils.entity

.getComponentProperty(entity, componentName, delimiter='.')

Performs like Entity.getAttribute, but with support for return an individual property for a multi-property component. componentName is a string that can either be a component name, or a component name delimited with a property name.

// <a-entity id="box" geometry="primitive: box"></a-entity>
var entity = document.querySelector('#box');

AFRAME.utils.entity.getComponentProperty(entity, 'geometry.primitive');
AFRAME.utils.entity.getComponentProperty(entity, 'geometry|primitive', '|');
// >> 'box'

AFRAME.utils.entity.getComponentProperty(entity, 'geometry');
// >> {primitive: 'box', width: 1, ...}

This is useful for components that need a way to reference a property of a multi-property component.

.setComponentProperty (entity, componentName, value, delimiter)

Performs like Entity.setAttribute, but with support for setting an individual property for a multi-property component. componentName is a string that can either be a component name, or a component name delimited with a property name.

// <a-entity id="box" geometry="primitive: box"></a-entity>
var entity = document.querySelector('#box');

AFRAME.utils.entity.setComponentProperty(entity, 'geometry.width', 1);
AFRAME.utils.entity.setComponentProperty(entity, 'geometry|height', 2, '|');
AFRAME.utils.entity.setComponentProperty(entity, 'geometry', {depth: 3});

AFRAME.utils.styleParser

.parse (value)

Parses a CSS style-like string to an object.

AFRAME.utils.styleParser.parse('attribute: color; dur: 5000;')
// >> {"attribute": "color", "dur": "5000"}

.stringify (data)

Stringifies an object to a CSS style-like string.

AFRAME.utils.styleParser.stringify({height: 10, width: 5})
// >> "height: 10; width: 5"

Object Utils

AFRAME.utils.deepEqual (a, b)

Checks if two objects have the same attributes and values, including nested objects.

deepEqual({a: 1, b: {c: 3}}, {a: 1, b: {c: 3}})
// >> true

AFRAME.utils.diff (a, b)

Returns difference between two objects. The returned object’s set of keys denote which values were not equal, and the set of values are b‘s values.

diff({a: 1, b: 2, c: 3}, {b: 2, c: 4})
// >> {"a": undefined, "c": 4}

AFRAME.utils.extend(target, source, [source, ...])

Object Assign polyfill

AFRAME.utils.extendDeep (target, source, [source, ...])

Deep Assign

AFRAME.utils.device

AFRAME.utils.device.checkHeadsetConnected ()

Checks if a VR headset is connected by looking for orientation data. Returns a boolean.

AFRAME.utils.device.isOculusGo ()

Checks if device is Oculus Go. Returns a boolean.

AFRAME.utils.device.isMobile ()

Checks if device is a smartphone. Returns a boolean.

Function Utils

AFRAME.utils.throttle (function, minimumInterval [, optionalContext])

Returns a throttled function that is called at most once every minimumInterval milliseconds. A context such as this can be provided to handle function binding for convenience. The same as lodash’s throttle.

AFRAME.registerComponent('foo', {
init: function () {
// Set up throttling.
this.throttledFunction = AFRAME.utils.throttle(this.everySecond, 1000, this);
},

everySecond: function () {
// Called every second.
console.log("A second passed.");
},

tick: function (t, dt) {
this.throttledFunction(); // Called once a second.
console.log("A frame passed."); // Called every frame.
},
});

AFRAME.utils.throttleTick (function (t, dt) {...}, minimumInterval [, optionalContext])

Returns a throttled function that is called at most once every minimumInterval milliseconds. A context such as this can be provided to handle function binding for convenience.

This variant of .throttle() is slightly more performant and tailored for tick handlers as it uses the t and dt timestamps passed by the global render loop.

AFRAME.registerComponent('foo', {
init: function () {
// Set up the tick throttling.
this.tick = AFRAME.utils.throttleTick(this.tick, 500, this);
},

/**
* Tick function that will be wrapped to be throttled.
*/
tick: function (t, dt) {}
});

AFRAME.utils.throttleLeadingAndTrailing (function, minimumInterval [, optionalContext])

Returns a throttled function that is called at most once every minimumInterval milliseconds, but ensures that the very last call of a burst gets deferred until the end of the interval. This is useful when an event is used to trigger synchronization of state, and there is a need to converge to the correct final state following a burst of events.

Example use cases:

  • synchronizing state based on the componentchanged event
  • following a mouse pointer using the mousemove event
  • integrating with THREE.TransformControls, via the objectChange event.

A context such as this can be provided to handle function binding for convenience.

The same as lodash’sthrottle, with leading and trailing options both set to true

Miscellaneous

AFRAME.utils.getUrlParameter (name)

Returns the value of a URL parameter as a string, otherwise returns an empty string.

AFRAME.utils.getUrlParameter('testing');
// If visiting the current page with ?testing=aframe, this will log 'aframe'.