aframe

--- title: Utils type: core layout: docs parent_section: core order: 11 source_code: src/utils/index.js --- 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. ```js 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. ```js 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. ```js 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` [getattr]: ./entity.md#getattribute-componentname ### `.getComponentProperty(entity, componentName, delimiter='.')` Performs like [`Entity.getAttribute`][getattr], 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. ```js // <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)` [setattr]: ./entity.md#setattribute-componentname-value-propertyvalue-clobber Performs like [`Entity.setAttribute`][setattr], 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. ```js // <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. ```js AFRAME.utils.styleParser.parse('attribute: color; dur: 5000;') // >> {"attribute": "color", "dur": "5000"} ``` ### `.stringify (data)` Stringifies an object to a CSS style-like string. ```js 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. ```js diff({a: 1, b: 2, c: 3}, {b: 2, c: 4}) // >> {"a": undefined, "c": 4} ``` ### `AFRAME.utils.extend(target, source, [source, ...])` [Object Assign polyfill](https://www.npmjs.com/package/object-assign) ### `AFRAME.utils.extendDeep (target, source, [source, ...])` [Deep Assign](https://www.npmjs.com/package/deep-assign) ## `AFRAME.utils.device` ### `AFRAME.utils.device.checkHeadsetConnected ()` Checks if a VR headset is connected by looking for browser support of immersive-vr or immersive-ar WebXR session. Returns a `boolean`. ### `AFRAME.utils.device.isMobile ()` Checks if device is a smartphone. Returns a `boolean`. ### `AFRAME.utils.device.isTablet ()` Checks if device is a tablet. Returns a `boolean`. ### `AFRAME.utils.device.isMobileVR ()` Checks if device is a standalone headset. Returns a `boolean`. ## Function Utils ### `AFRAME.utils.throttle (function, minimumInterval [, optionalContext])` [lodash]: https://lodash.com/docs/#throttle 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`][lodash]. ```js 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. ```js 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](https://threejs.org/docs/#examples/en/controls/TransformControls), via the objectChange event. A context such as `this` can be provided to handle function binding for convenience. The same as [lodash's`throttle`][lodash], 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. ```js AFRAME.utils.getUrlParameter('testing'); // If visiting the current page with ?testing=aframe, this will log 'aframe'. ```