Utils

Note: This documentation is for the old 1.4.0 version of A-Frame. Check out the documentation for the current 1.5.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.isGearVR ()`

Checks if device is Gear VR. 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'.