AltspaceUtil
Provides helper functions, behaviors and A-Frame components for common functionality compatible with AltspaceSDK.
Usage
Include the utility library in your project:
API Reference
Functions
- altspaceutil.getFullspaceApp
- altspaceutil.getFullspaceEnclosure
- altspaceutil.getAbsoluteURL
- altspaceutil.getBasePath
- altspaceutil.isMobileApp
- altspaceutil.expandSerializationBuffer
- altspaceutil.profileSerializationBuffer
- altspaceutil.setCursorCollider
- altspaceutil.isCursorCollider
- altspaceutil.loadTexture
- altspaceutil.loadScript
- altspaceutil.loadScripts
- altspaceutil.loadAsset
- altspaceutil.loadAssets
- altspaceutil.addAssetLoader
- altspaceutil.removeAssetLoader
- altspaceutil.overrideTextureLoader
Behaviors
- altspaceutil.behaviors.NativeComponent
- altspaceutil.behaviors.NativeComponentSync
- altspaceutil.behaviors.TransformControls
- altspaceutil.behaviors.OrbitControls
- altspaceutil.behaviors.UserEvents
- altspaceutil.behaviors.PreloadNativeSounds
- altspaceutil.behaviors.HoverMaterialOpacity
- altspaceutil.behaviors.HoverMaterialColor
- altspaceutil.behaviors.NativeTextMaterial
- altspaceutil.behaviors.TWEEN
- altspaceutil.behaviors.Billboard
- altspaceutil.behaviors.Text
- altspaceutil.behaviors.GLTF
- altspaceutil.behaviors.Sound
Events
- transform-controls-dragmove
- transform-controls-dragbegin
- transform-controls-dragend
- avatarchange
- userchange
- avatarstatus
- n-sound-preloaded
- gltf-loaded
- sound-loaded
- sound-played
- sound-paused
- sound-stopped
Classes
A-Frame Components
Functions
altspaceutil.getFullspaceApp
Gets an initialized fullspace app instance. The app will be initialized on the first call to this function, which sets up the render loop, fullspace enclosure and anchors.
Parameters
Name | Type | Default | Description |
---|---|---|---|
config |
Object | Optional parameters. | |
config.serializationBufferSize |
Number | 500000 | Initial size of the serialization buffer. See altspaceutil.expandSerializationBuffer for more information. |
Returns
Type | Description |
---|---|
Promise | A promise that resolves to a FullspaceApp. |
altspaceutil.getFullspaceEnclosure
Gets the fullspace enclosure for the app.
Returns
Type | Description |
---|---|
Promise | A promise that resolves to a fullspace Enclosure. |
altspaceutil.getAbsoluteURL
Create an absolute URL from the specified relative URL, using the current host as the URL base.
Parameters
Name | Type | Description |
---|---|---|
url |
String | A relative URL. Providing an absolute URL will return itself unchanged. |
Returns
Type | Description |
---|---|
String | An absolute URL of the given relative URL. |
altspaceutil.getBasePath
Create a base path from the specified file URL.
Parameters
Name | Type | Description |
---|---|---|
url |
String | A URL to a file. |
Returns
Type | Description |
---|---|
String | A URL to the file's base path. |
altspaceutil.isMobileApp
Indicates whether the app is being loaded on a mobile version of the Altspace client. This is typically determined by the user agent exposed to the app.
Returns
Type | Description |
---|---|
Boolean | Whether the app is running on a mobile client. Returns true for mobile clients, false otherwise. |
altspaceutil.expandSerializationBuffer
Expands the Altspace client's serialization buffer to improve loading performance.
Parameters
Name | Type | Description |
---|---|---|
size |
Number | The size to expand the serialization buffer by, in bytes. |
altspaceutil.profileSerializationBuffer
Enables or disables the profiler for the Altspace client's serialization buffer to determine whether the buffer needs to be expanded. Profiler messages will be displayed in the console when enabled.
Parameters
Name | Type | Description |
---|---|---|
enabled |
Boolean | Specifies whether the serialization buffer is to be enabled. |
altspaceutil.setCursorCollider
Sets the Altspace cursor collider property for the specified object.
Parameters
Name | Type | Default | Description |
---|---|---|---|
object3d |
THREE.Object3D | An object to set the cursor collider property for. | |
isCursorCollider |
Boolean | Specifies if the object is a cursor collider. | |
recursive |
Boolean | false | Specifies if the property change should also be applied recursively to all children of the object. |
altspaceutil.isCursorCollider
Gets the Altspace cursor collider property for the specified object.
Parameters
Name | Type | Description |
---|---|---|
object3d |
THREE.Object3D | An object to retrieve the cursor collider property from. |
Returns
Type | Description |
---|---|
Boolean | Whether the object is a cursor collider. |
altspaceutil.loadTexture
Loads a three.js texture from the specified texture file URL, optimizing for faster loading times in the Altspace client where appropriate.
Parameters
Name | Type | Description |
---|---|---|
url |
String | A URL to a texture file. |
config |
Object | Optional parameters to be passed to the texture loader (e.g. crossOrigin, withCredentials, path). |
Returns
Type | Description |
---|---|
THREE.Texture | The loaded texture. |
altspaceutil.loadScript
Loads and executes a script from the specified JavaScript file URL.
Parameters
Name | Type | Default | Description |
---|---|---|---|
url |
String | A URL to a JavaScript file. | |
config |
Object | Optional parameters for specialized cases. | |
config.scriptTest |
Function | null | A predicate function that tests whether the script contents has loaded. A return value of true indicates that the loaded script content exists, false otherwise. |
config.loadOnce |
Boolean | true | Indicates whether the script should be loaded if it was previously loaded. If true, the script will not be loaded again on subsequent calls if it was previously loaded. |
Returns
Type | Description |
---|---|
Promise | A promise that resolves when the javascript file has been loaded. |
altspaceutil.loadScripts
Loads and executes one or more scripts from the specified JavaScript file URL.
Parameters (1)
Name | Type | Description |
---|---|---|
scripts |
String[] | An array of JavaScript file URLs to be loaded. |
Parameters (2)
Name | Type | Description |
---|---|---|
scripts |
Script[] | An array of objects containing a URL and optional config parameters for the scripts to be loaded. See below for object parameters. |
Script parameters.
Name | Type | Default | Description |
---|---|---|---|
url |
String | A URL to a JavaScript file. | |
scriptTest |
Function | null | A predicate function that tests whether the script contents has loaded. A return value of true indicates that the loaded script content exists, false otherwise. |
loadOnce |
Boolean | true | Indicates whether the script should be loaded if it was previously loaded. If true, the script will not be loaded again on subsequent calls if it was previously loaded. |
Returns
Type | Description |
---|---|
Promise | A promise that resolves when the javascript files have been loaded. |
altspaceutil.loadAsset (Example)
Loads an asset from the specified URL.
Default formats supported:
- Wavefront OBJ (.obj)
- Material is applied automatically based on MTL file linked to OBJ.
- COLLADA (.dae)
- glTF (.gltf/.glb)
- Altspace client loads glTF assets using n-gltf by default, which can be overridden with the
native
config parameter.
- Altspace client loads glTF assets using n-gltf by default, which can be overridden with the
- STL (.stl)
- AutoDesk FBX (.fbx)
- Open Asset Import Library (.assimp)
- Binary Object/Material (.bom)
Additional formats can be loaded by registering a custom file handler using addAssetLoader.
Parameters
Name | Type | Default | Description |
---|---|---|---|
url |
String | A URL to the asset to be loaded. | |
config |
Object | Optional parameters. | |
config.applyTransform |
Boolean | true | When true, the position /rotation /quaternion /scale properties will be applied to the loaded asset. |
config.cursorCollider |
Boolean | false | Specified whether cursor collision is enabled on the loaded asset. |
config.native |
Boolean | true | When true, assets loaded in the Altspace client will be loaded as native objects where appropriate (e.g. n-gltf for glTF assets), otherwise standard browser behavior will be followed. |
config.position |
THREE.Vector3 | { x: 0, y: 0, z: 0 } | Position to be applied to the loaded asset. |
config.rotation |
THREE.Euler | { x: 0, y: 0, z: 0 } | Rotation to be applied to the loaded asset, in radians. |
config.quaternion |
THREE.Quaternion | { x: 0, y: 0, z: 0, w: 1 } | Quaternion to be applied to the loaded asset. Specifying quaternion will override the rotation property. |
config.scale |
THREE.Vector3 | { x: 1, y: 1, z: 1 } | Scale to be applied to the loaded asset. Alternatively, uniform scaling is applied when a number is specified. |
config.onLoaded |
Function | null | A callback function to execute when the asset has been loaded. A reference to the loaded asset will be passed into this function. |
config.crossOrigin |
String | anonymous | Specifies the cross-origin state for loading textures. |
Returns
Type | Description |
---|---|
Promise | A promise that resolves to the loaded asset. |
altspaceutil.loadAssets (Example)
Loads one or more assets from the specified URLs.
Parameters (1)
Name | Type | Description |
---|---|---|
assets |
Asset[] | An array of assets to be loaded. |
Parameters (2)
Name | Type | Description |
---|---|---|
assets |
Object | An object of unordered, named assets to be loaded. |
Asset parameters.
Name | Type | Default | Description |
---|---|---|---|
url |
String | A URL to a JavaScript file. | |
applyTransform |
Boolean | true | When true, the position /rotation /quaternion /scale properties will be applied to the loaded asset. |
cursorCollider |
Boolean | false | Specified whether cursor collision is enabled on the loaded asset. |
native |
Boolean | true | When true, assets loaded in the Altspace client will be loaded as native objects where appropriate (e.g. n-gltf for glTF assets), otherwise standard browser behavior will be followed. |
position |
THREE.Vector3 | { x: 0, y: 0, z: 0 } | Position to be applied to the loaded asset. |
rotation |
THREE.Euler | { x: 0, y: 0, z: 0 } | Rotation to be applied to the loaded asset, in radians. |
quaternion |
THREE.Quaternion | { x: 0, y: 0, z: 0, w: 1 } | Quaternion to be applied to the loaded asset. Specifying quaternion will override the rotation property. |
scale |
THREE.Vector3 | { x: 1, y: 1, z: 1 } | Scale to be applied to the loaded asset. Alternatively, uniform scaling is applied when a number is specified. |
onLoaded |
Function | null | A callback function to execute when the asset has been loaded. A reference to the loaded asset will be passed into this function. |
crossOrigin |
String | anonymous | Specifies the cross-origin state for loading textures. |
Returns
Type | Description |
---|---|
Promise | A promise that resolves to the loaded assets, either as an array or object of named assets depending on the supplied parameters. |
altspaceutil.addAssetLoader (Example)
Registers a handler that will load and construct the specified asset type when loadAsset or loadAssets is called.
Parameters
Name | Type | Description |
---|---|---|
regex |
RegExp | The regular expression that will be used to identify an asset from its URL (e.g. /\.dae$/i to match the file extension for Collada assets.) |
handler |
AssetLoaderHandler | A handler function that accepts a URL and configuration parameters that will load and construct the asset. The function must return a promise that resolves that resolves to the loaded asset, or a rejected promise on failure. |
AssetLoaderHandler
parameters.
Name | Type | Description |
---|---|---|
url |
String | A URL to the asset to be loaded. |
config |
Object | Optional parameters. |
altspaceutil.removeAssetLoader
Unregisters a handler for the specified asset type that is used when loadAsset or loadAssets is called.
Parameters
Name | Type | Default | Description |
---|---|---|---|
regex |
RegExp | The regular expression associated with an asset handler. | |
handler |
AssetLoaderHandler | null | An asset handler function that is associated with the specified regular expression. If omitted, all handlers for the specified regular expression will be removed. |
altspaceutil.overrideTextureLoader
Enables or disables texture loading optimizations in the Altspace client. Enabling texture loader optimizations can drastically improve texture loading times, reduce resource usage and correct compability issues with embedded textures in the Altspace client.
Please note that these optimizations are enabled by default, and can be disabled when compatibility issues with other libraries arise.
Parameters
Name | Type | Description |
---|---|---|
override |
Boolean | Specifies whether texture loader optimizations are enabled. |
Behaviors
altspaceutil.behaviors.NativeComponent (Example)
Provides support for AltspaceVR native components to be attached to objects, providing sane configuration defaults where appropriate.
Parameters
type
- Native component type.
data
- Native component properties. See here for available properties and defaults.
config
- Optional parameters for specialized use cases. Many of these properties are provided only to override the internal behavior of a component in specialized use cases.
Name | Type | Default | Description |
---|---|---|---|
targetEntity |
THREE.Object3D | null | An object in the scene that a user will teleport to when entering a native portal. |
useCollider |
Boolean | false | Specifies whether cursor collision should be disabled on the native component. |
sharedComponent |
Boolean | true | Specifies whether the native component should share the same THREE.Mesh instance with other native components. |
recursiveMesh |
Boolean | false | Specifies whether the native component is applied recursively to all THREE.Mesh children. |
recursive |
Boolean | false | Specifies whether the native component is applied recursively to all children. |
sendUpdates |
Boolean | true | Specifies whether the native component should send updates to the native Altspace client. |
updateOnStaleData |
Boolean | true | Specifies whether the native component should send updates to the native Altspace client when a property has changed. |
inheritParentData |
Boolean | false | Specifies whether the native component should inherit its property state from a parent component. |
meshComponent |
Boolean | false | Specifies whether the native component is treated as a mesh-specific component. This is used as a performance optimization to defer initialization of mesh-specific components (e.g. native parents and colliders) attached to placeholder objects, until another component is added that gives them functionality (e.g. text, spawner). |
Methods
callComponentAction
Invokes an action associated with the native component, and does not provide a return value.
Name | Type | Description |
---|---|---|
actionName |
String | The action name to invoke on the native component. |
actionArgs |
Object | Arguments that will be passed along with the action when invoked. |
callComponentFunc
Calls a function associated with the native component, and returns a promise of the value that will be returned by the native component function.
Name | Type | Description |
---|---|---|
functionName |
String | The function name to invoke on the native component. |
functionArgs |
Object | Arguments that will be passed to the function when called. |
callComponent
This function has been Deprecated. See callComponentAction.
getAttribute
Retrieves an attribute associated with a native component. See here for available attributes.
Name | Type | Description |
---|---|---|
attributeName |
String | An attribute name associated with the native component. |
Native Component Attributes
Attributes associated with a native component can be retrieved using the getAttribute method.
n-sound
Name | Type | Description |
---|---|---|
loaded |
Boolean | Indicates that the component has been loaded by the AltspaceVR client. |
n-gltf
Name | Type | Description |
---|---|---|
loaded |
Boolean | Indicates that the component has been loaded by the AltspaceVR client. |
n-container
Name | Type | Description |
---|---|---|
count |
Number | The number of objects in the n-container. |
Native Component Properties
n-object
data: res: 'architecture/wall-4w-4h'
n-spawner
data: res: 'interactables/basketball'
n-text
data: text: '' fontSize: 10 width: 10 height: 1 horizontalAlign: 'middle' verticalAlign: 'middle'
n-sphere-collider
data: isTrigger: false center: 'x': 0 'y': 0 'z': 0 radius: 0 type: 'environment'
n-box-collider
data: isTrigger: false center: 'x': 0 'y': 0 'z': 0 size: 'x': 0 'y': 0 'z': 0 type: 'environment'
n-capsule-collider
data: isTrigger: false center: 'x': 0 'y': 0 'z': 0 radius: 0 height: 0 direction: 'y' type: 'environment'
n-mesh-collider
data: isTrigger: false convex: true type: 'environment'
n-container
data: capacity: 4
n-sound
data: on: '' res: '' src: '' loop: false volume: 1 autoplay: false oneshot: false spatialBlend: 1 pitch: 1 minDistance: 1 maxDistance: 12 rolloff: 'logarithmic'
n-skeleton-parent
data: part: 'head' side: 'center' index: 0 userId: null // defaults to current user when omitted
n-cockpit-parent
No properties to be configured.
n-billboard
No properties to be configured.
n-layout-browser
data: url: 'about:blank' isEnclosure: false
n-portal
data: targetSpace: null // defaults to current space when omited targetEvent: null // defaults to current space when omited targetPosition: x: 0 y: 0 z: 0 targetQuaternion: x: 0 y: 0 z: 0 w: 1
n-gltf
data: sceneIndex: 0 url: ''
n-rigidbody
Experimental! This native component is not yet officially supported by the AltspaceSDK.
data: mass: 1 drag: 0 angularDrag: 005 useGravity: true isKinematic: false positionConstraints: false false false rotationConstraints: false false false
altspaceutil.behaviors.NativeComponentSync (Example)
Provides support for AltspaceVR native component data to be synchronized over Firebase. The behavior must be used in conjunction with SceneSync, Object3DSync and a NativeComponent of the same type specified for NativeComponentSync.
Parameters
type
- Type of native component to be synchronized. To retrieve the behavior using the getBehaviorByType
method, prepend sync-
to the name of the native component type (e.g. sync-n-text
for an n-text
native component).
config
- Optional parameters.
Name | Type | Default | Description |
---|---|---|---|
syncRef |
altspace.utilities.behaviors.Object3DSync | null | A reference to the object syncing component. Defaults to using the syncing component of the object the behavior is attached to. |
altspaceutil.behaviors.TransformControls (Example)
Enables an object's position, rotation and scale to be manipulated in AltspaceVR using a draggable transform gizmo.
Parameters
config
- Optional parameters.
Name | Type | Default | Description |
---|---|---|---|
controlType |
String | none | The default control type to be selected. Supported control types are none , position , rotate or scale . |
showButtons |
Boolean | false | Specifies whether buttons should be displayed to toggle between control types. |
followTarget |
Boolean | true | Specified whether the transform gizmo should follow the object that is being manipulated. |
target |
THREE.Object3D | null | The target that the transform gizmo should manipulate when interacted with. If omitted, the object that the behavior is associated with will be used as the target. |
scale |
Number | 1 | Adjusts the scale of the transform gizmo. |
allowNegativeScale |
Boolean | false | Specifies whether the scale transform gizmo will allow the target's scale to be negative. |
positionAxisLock |
Object | Specifies which axes of the position gizmo can be displayed and manipulated. | |
positionAxisLock.x |
Boolean | true | X axis of the position gizmo. |
positionAxisLock.y |
Boolean | true | Y axis of the position gizmo. |
positionAxisLock.z |
Boolean | true | Z axis of the position gizmo. |
rotateAxisLock |
Object | Specifies which axes of the rotate gizmo can be displayed and manipulated. | |
rotateAxisLock.x |
Boolean | true | X axis of the rotate gizmo. |
rotateAxisLock.y |
Boolean | true | Y axis of the rotate gizmo. |
rotateAxisLock.z |
Boolean | true | Z axis of the rotate gizmo. |
scaleAxisLock |
Object | Specifies which axes of the scale gizmo can be displayed and manipulated. | |
scaleAxisLock.x |
Boolean | true | X axis of the scale gizmo. |
scaleAxisLock.y |
Boolean | true | Y axis of the scale gizmo. |
scaleAxisLock.z |
Boolean | true | Z axis of the scale gizmo. |
disableColliders |
Boolean | true | Specifies whether colliders on the target object should be disabled. |
disableChildColliders |
Boolean | true | Specifies whether colliders on the target's children should be disabled. |
Events
transform-controls-dragmove
Fires an event when the transform gizmo is being dragged.
Name | Type | Description |
---|---|---|
behavior |
TransformControls | The behavior that controls the transform gizmo. |
parent |
THREE.Object3D | The object that the transform gizmo is parented to. |
transformTarget |
THREE.Object3D | The object that the transform gizmo will manipulate. |
transformType |
String | The type of transform being performed. Possible values are position , rotate and scale . |
transformAxis |
String | The axis that the transform is being performed on. Possible values are x , y , z (for single axes) and xyz (for all axes). |
transformDelta |
THREE.Vector3 | The transform delta that was applied to the target object. |
transform-controls-dragbegin
Fires an event when the transform gizmo starts being dragged.
Name | Type | Description |
---|---|---|
behavior |
TransformControls | The behavior that controls the transform gizmo. |
parent |
THREE.Object3D | The object that the transform gizmo is parented to. |
transformTarget |
THREE.Object3D | The object that the transform gizmo will manipulate. |
transformType |
String | The type of transform being performed. Possible values are position , rotate and scale . |
transformAxis |
String | The axis that the transform is being performed on. Possible values are x , y , z (for single axes) and xyz (for all axes). |
transform-controls-dragend
Fires an event when the transform gizmo is no longer being dragged.
Name | Type | Description |
---|---|---|
behavior |
TransformControls | The behavior that controls the transform gizmo. |
parent |
THREE.Object3D | The object that the transform gizmo is parented to. |
transformTarget |
THREE.Object3D | The object that the transform gizmo will manipulate. |
transformType |
String | The type of transform being performed. Possible values are position , rotate and scale . |
transformAxis |
String | The axis that the transform is being performed on. Possible values are x , y , z (for single axes) and xyz (for all axes). |
altspaceutil.behaviors.OrbitControls (Example)
Provides a convenience wrapper for THREE.OrbitControls when working with altspace.utilities.Simulation.
altspaceutil.behaviors.UserEvents (Example)
Subscribes to avatar and user preference update events for a given list of users, and dispatches events which have been triggered by a given user changing their avatar and/or account preferences.
Parameters
config
- Optional parameters.
Name | Type | Default | Description |
---|---|---|---|
userIds |
String[] | null | An array of (legacy) User IDs for each user to dispatch events for. When omitted, only avatar change events for the user currently logged in will be handled. |
onRequestData |
onRequestData | null | A precondition callback returning a boolean that determines if a user should have their data requested. User data is requested if the callback returns true, otherwise no action is taken. |
refreshTime |
Number | 5000 | Duration to wait between user updates, in milliseconds. |
trace |
Boolean | false | Specifies whether debugging information should be displayed. |
Callbacks
onRequestData
A precondition callback returning a boolean that determines if a user should have their data requested. User data is requested if the callback returns true, otherwise no action is taken.
Name | Type | Description |
---|---|---|
userId |
String | User ID of a user who will have their data requested. |
object |
THREE.Object3D | The object that will emit the request. |
Methods
subscribeUser
Subscribe to receiving events for a given User ID.
Name | Type | Description |
---|---|---|
userId |
String | User ID to receive events for. |
unsubscribeUser
Unsubscribe from receiving events for a given User ID.
Name | Type | Description |
---|---|---|
userId |
String | User ID to stop receiving events for. |
Events
avatarchange
Fires an event when the user changes avatar preferences.
Name | Type | Description |
---|---|---|
userId |
String | User ID of the user. |
avatarId |
String | Avatar type identifier that was selected by the user. |
avatarClass |
String | Avatar type classification. Typically one of Pod , Robothead or Rubenoid , or empty when unclassified. |
colors |
Object | THREE.Color preferences of the avatar. This typically provides primary and highlight properties for Pod avatars, and highlight for Robothead avatars. |
rawColors |
Object | Raw color preferences of the avatar. This typically provides primary and highlight properties for Pod avatars, and highlight for Robothead avatars. |
textures |
Object | Texture identifier preferences for the avatar. This typically provides hair , skin and clothing properties for Rubenoid avatars. |
target |
THREE.Object3D | The object which emitted the event. |
userchange
Fires an event when the user changes account preferences.
Name | Type | Description |
---|---|---|
userId |
String | User ID of the user. |
username |
String | Username of the user. |
displayName |
String | Display name of the user. |
target |
THREE.Object3D | The object which emitted the event. |
avatarstatus
Fires an event when the user's connection status changes.
Name | Type | Description |
---|---|---|
userId |
String | User ID of the user. |
displayName |
String | Display name of the user. |
online |
Boolean | Specifies whether user is currently logged in. |
target |
THREE.Object3D | The object which emitted the event. |
altspaceutil.behaviors.PreloadNativeSounds (Example)
Preloads the specified sound files used by n-sound to ensure the resources are cached for subsequent uses. The behavior will remove itself automatically once the sound files have been preloaded or the specified timeout threshold has been reached.
Parameters
sounds
- Native sound resources to be preloaded. Can either be an array of sound file paths or an array of NativeComponent n-sound data objects (e.g. { src: 'file.wav', volume: 1.5 }
).
config
- Optional parameters.
Name | Type | Default | Description |
---|---|---|---|
dispose |
Boolean | true | Specifies whether the preloaded native sound objects will be destroyed after the preload has completed. By default, preloaded sound objects will be destroyed after being cached. |
timeout |
Number | 10000 | Time in milliseconds to wait before ending the preload. A n-sound-preloaded event will be fired with a timeout property set to true when the timeout threshold has been reached. Specifying a zero or negative value will disable the timeout. |
Events
n-sound-preloaded
Fires an event once all sounds have been preloaded, or the specified timeout threshold has been reached.
Name | Type | Description |
---|---|---|
behavior |
PreloadNativeSounds | The behavior that preloaded the sounds. |
sounds |
THREE.Object3D[] | The sound objects that were preloaded. Sound objects are children of the object the behavior is associated with. |
timeout |
Boolean | Indicates whether the timeout threshold has been reached before all sounds were preloaded. |
altspaceutil.behaviors.HoverMaterialOpacity (Example)
Changes the opacity of an object's material when the cursor hovers over it, and restores the original opacity when the cursor is no longer hovering over the object.
Parameters
config
- Optional parameters.
Name | Type | Default | Description |
---|---|---|---|
material |
THREE.Material | null | A reference to the material whose opacity will be updated. Defaults to material of the object the behavior is attached to. |
opacity |
Number | 1 | The value that will be applied to the object's current material opacity when the cursor hovers over it. |
beginDuration |
Number | 75 | Duration the hovered opacity adjustment effect is intended to take to complete, in milliseconds. |
endDuration |
Number | 75 | Duration the unhovered opacity adjustment effect is intended to take to complete, in milliseconds. |
revertOnDispose |
Boolean | true | Specifies whether the object's original material opacity should be restored when the behavior has been destroyed. |
eventListener |
THREE.Object3D | null | Specifies an optional object that will listen for cursor events. By default the object that the behavior is attached to will be used as the event listener. |
hoverChildren |
Boolean | true | Specifies whether hovering over children of the event listener object should invoke the hover effect. |
altspaceutil.behaviors.HoverMaterialColor (Example)
Changes the color of an object's material when the cursor hovers over it, and restores the original color when the cursor is no longer hovering over the object.
Parameters
config
- Optional parameters.
Name | Type | Default | Description |
---|---|---|---|
material |
THREE.Material | null | A reference to the material whose color will be updated. Defaults to material of the object the behavior is attached to. |
color |
THREE.Color | new THREE.Color('yellow') | The value that will be applied to the object's material color when the cursor hovers over it. |
beginDuration |
Number | 75 | Duration the hovered color adjustment effect is intended to take to complete, in milliseconds. |
endDuration |
Number | 75 | Duration the unhovered color adjustment effect is intended to take to complete, in milliseconds. |
revertOnDispose |
Boolean | true | Specifies whether the object's original material color should be restored when the behavior has been destroyed. |
eventListener |
THREE.Object3D | null | Specifies an optional object that will listen for cursor events. By default the object that the behavior is attached to will be used as the event listener. |
hoverChildren |
Boolean | true | Specifies whether hovering over children of the event listener object should invoke the hover effect. |
altspaceutil.behaviors.NativeTextMaterial (Example)
Updates the color and opacity of a n-text native component using a material source.
Parameters
config
- Optional parameters.
Name | Type | Default | Description |
---|---|---|---|
material |
THREE.Material | null | A reference to the material whose properties will be applied to the n-text native component. Defaults to material of the object the behavior is attached to. |
color |
Boolean | true | Specifies whether the n-text native component should use the color of the source material. |
opacity |
Boolean | true | Specifies whether the n-text native component should use the opacity of the source material. |
altspaceutil.behaviors.TWEEN (Example)
Provides a convenience wrapper for tween.js to manage and update TWEEN
and TWEEN.Group
objects. Refer to the tween.js user guide for further information.
Parameters
Name | Type | Default | Description |
---|---|---|---|
tweengroup |
TWEEN.Group | TWEEN | A tween group to be managed by the behavior. When ommitted, the global TWEEN object will be managed by the behavior. |
altspaceutil.behaviors.Billboard (Example)
The Billboard behavior updates the orientation of an object to face the camera.
Parameters
Name | Type | Default | Description |
---|---|---|---|
config |
Object | Optional parameters. | |
config.target |
THREE.Object3D | null | A target that the object should face. If omitted, the scene camera will be used. |
config.x |
Boolean | true | Specifies whether the X-axis of the object should be reoriented to face the camera. |
config.y |
Boolean | true | Specifies whether the Y-axis of the object should be reoriented to face the camera. |
config.z |
Boolean | true | Specifies whether the Z-axis of the object should be reoriented to face the camera. |
config.native |
Boolean | true | Specifies whether a native billboard (n-billboard) component will be used when running the app in the Altspace client. |
altspaceutil.behaviors.Text (Example)
The Text behavior displays a text string using an SDF font, supporting line breaks, text alignment and inline formatting tags.
e.g. <color=#FFFFFF>The</color> <color="red">quick <#FFFF00>brown <alpha=#33>fox <color=#FFFFFFFF> jumps over the <noparse><alpha=#DD>lazy</noparse> dog.
Supported Tags
<color=...>Text</color>
<color="name">
- Changes the color of the text using the specified color name. Supported color names areblack
,blue
,green
,orange
,purple
,red
,yellow
orwhite
.<color=#RRGGBB>
<color=#RGB>
<color=#RRGGBBAA>
<color=#RGBA>
<#RRGGBB>
<#RGB>
<#RRGGBBAA>
<#RGBA>
- Changes the color and opacity of text using the specified hexidecimal code.<alpha=#AA>
- Changes the opacity of any text that follows.<b>Text</b>
- Applies a bold effect to the text.<i>Text</i>
- Applies an italic effect to the text.<noparse>Text</noparse>
- Prevents formatting tags from being parsed.
Parameters
Name | Type | Default | Description |
---|---|---|---|
config |
Object | Optional parameters. | |
config.text |
String | The text to be displayed. | |
config.fontSize |
Number | 10 | The size of the text. |
config.width |
Number | 10 | The width of the text block to display before text wrapping occurs. |
config.height |
Number | 1 | The height offset of the text block. |
config.horizontalAlign |
String | middle | The horizontal alignment of the text block. |
config.verticalAlign |
String | middle | The vertical alignment of the text block. |
config.native |
Boolean | true | Specifies whether a native text (n-text) component will be used when running the app in the Altspace client. |
altspaceutil.behaviors.GLTF (Example)
The GLTF behavior loads and displays a glTF model asset.
Parameters
Name | Type | Default | Description |
---|---|---|---|
config |
Object | Optional parameters. | |
config.url |
String | A URL to the GLTF model file to be loaded. | |
config.sceneIndex |
Number | 0 | Specifies the scene to load when the GLTF model contains multiple scenes. |
config.native |
Boolean | true | Specifies whether a native glTF (n-gltf) component will be used when running the app in the Altspace client. |
Members
Name | Type | Description |
---|---|---|
loaded |
Boolean | Indicates whether the sound has been loaded. |
Methods
getBoundingBox
Retreives the axis aligned bounding box of the loaded glTF model.
Returns
Type | Description |
---|---|
Promise | Resolves to a THREE.Box3 representing an axis aligned bounding box of the loaded glTF model. |
Events
gltf-loaded
Fires an event once the glTF model has been loaded.
altspaceutil.behaviors.Sound (Example)
The Sound behavior loads and plays a sound asset supporting positional audio.
Parameters
Name | Type | Default | Description |
---|---|---|---|
config |
Object | Optional parameters. | |
config.target |
THREE.Object3D | A target that will listen for the sound being played. If omitted, the scene camera will be used. | |
config.src |
String | A URL to the sound file to be loaded. | |
config.res |
String | A sound resource identifier to be loaded. | |
config.on |
String | Name of the event that will trigger the sound to be played. | |
config.loop |
Boolean | false | Specifies whether the sound should loop back to the beginning once playback has finished. |
config.autoplay |
Boolean | false | Specifies whether the sound will play automatically when the parent object is loaded into the scene. |
config.oneshot |
Boolean | false | Specifies whether multiple instances of the sound can be played simultaneously. Note that one-shot sounds cannot be paused, stopped or seeked into, and instances will clean themselves up automatically when playback has finished. |
config.volume |
Number | 1 | Volume that the sound should play at. |
config.spatialBlend |
Number | 1 | Specifies how the sound will be perceived spactially, ranging from 0 (2D stereo without panning between left and right sound channels) up to 1 (localized 3D with panning between left and right sound channels). |
config.pitch |
Number | 1 | The speed and octave adjustment that the sound will play at. 0.5 for half speed at a lower octave, 2 for double speed at a higher octave. |
config.minDistance |
Number | 1 | The minimum distance that the sound will play at full volume. |
config.maxDistance |
Number | 12 | The maximum distance that the sound will play before volume reaches silent when a linear/cosine rolloff algorithm is specified, otherwise the volume will stop lowering after the specified distance when a logarithmic rolloff algorithm is specified. |
config.rolloff |
String | logarithmic | Volume can reach a silent level when a linear/cosine rolloff algorithm is specified, otherwise the volume will stop lowering after the specified distance when a logarithmic rolloff algorithm is specified. |
config.native |
Boolean | true | Specifies whether a native sound (n-sound) component will be used when running the app in the Altspace client. |
Members
Name | Type | Description |
---|---|---|
loaded |
Boolean | Indicates whether the sound has been loaded. |
Methods
play
Begins playback of the sound, and emits a sound-played event.
pause
Pauses playback of the sound at the current position, and emits a sound-paused event.
stop
Stops playback of the sound, and emits a sound-stopped event.
seek
Skips playback to a specific time point in the sound.
Parameters
Name | Type | Description |
---|---|---|
time | Number | Number of milliseconds from the beginning of the sound to skip playback to. |
Events
sound-loaded
Fires an event once the sound has been loaded.
sound-played
Fires an event when playback of the sound begins.
sound-paused
Fires an event when playback of the sound is paused.
sound-stopped
Fires an event when playback of the sound is stopped.
Classes
FullspaceApp
Manages the render and update loop and creation of anchor points for a three.js app. This class is not intended to be created directly, but should be retrieved using altspaceutil.getFullspaceApp.
Anchor Points
Overview
Anchor points (also referred to as Anchors) are nodes in a scene which can be positioned, rotated and scaled externally by end users using URL parameters passed in when the app is loaded into an enclosure, allowing an app to be customized for any environment layout.
By default, all apps using altspaceutil.getFullspaceApp are provided with a root anchor point which encompasses all objects in the scene. Additional user-defined anchor points which are transformed relative to the root anchor may also be used to split a scene into seperately customizable parts.
Scene objects should be attached to either the root anchor
point, or a user-defined anchor point obtained from anchors
to ensure that apps can be customized by end users as appropriate.
Example Usage
Imagine a concert environment app containing a skybox, a stage for performers and a seating area for an audience, where each part of the scene can be arranged independently of each other.
https://example.com/concertapp/index.html
altspaceutil;
https://path/to/manifest.json
"enclosure": "position": "x": 0 "y": 0 "z": 0 "rotation": "x": 0 "y": 0 "z": 0 "scale": "x": 1 "y": 1 "z": 1 "anchors": "name": "performerstage" "position": "x": 5 "y": 0 "z": -3 "rotation": "x": 0 "y": 0 "z": 0 "scale": "x": 2 "y": 05 "z": 3 "name": "audiencestand" "position": "x": 1 "y": 0 "z": 0 "rotation": "x": 0 "y": 0 "z": 0 "scale": "x": 1 "y": 1 "z": 1
Manifest file example: https://example.com/concertapp/index.html?altvr.manifest=https://path/to/manifest.json
Anchors can be customized without a manifest file with URL parameters: https://example.com/concertapp/index.html?altvr.enclosure.position=0,0,0&altvr.enclosure.rotation=0,0,0&altvr.anchors.performerstage.position=5,0,-3&altvr.anchors.performerstage.scale=2,0.5,3&altvr.anchors.audiencestand.position=1,0,0
URL parameters can also be used to override a manifest file: https://example.com/concertapp/index.html?altvr.manifest=https://path/to/manifest.json&altvr.enclosure.scale=0.1&altvr.anchors.performerstage.position=4,0,-2&altvr.anchors.performerstage.scale=1,0.6,4&altvr.anchors.audiencestand.position=2,0,0
Members
Name | Type | Description |
---|---|---|
scene |
THREE.Scene | The scene associated with the app. |
renderer |
AltRenderer | The renderer associated with the app. |
camera |
THREE.Camera | The camera associated with the app. |
anchor |
THREE.Group | The root anchor associated with the app. The root anchor can have its transform specified using the altvr.enclosure.position , altvr.enclosure.rotation and altvr.enclosure.scale URL parameters, or a manifest file referenced using the altvr.manifest URL parameter. |
enclosure |
Enclosure | The enclosure associated with the app. |
space |
Space | The space associated with the app. |
Methods
anchors
Retrieves an anchor point with the specified name. If the anchor point does not exist, it will be created automatically. The anchor can have its transform specified using the altvr.anchors.[name].position
, altvr.anchors.[name].rotation
and altvr.anchors.[name].scale
URL parameters, or a manifest file referenced using the altvr.manifest
URL parameter.
Parameters
Name | Type | Description |
---|---|---|
name |
String | Name of the anchor. |
Returns
Type | Description |
---|---|
THREE.Group | An anchor with the specified name. |
A-Frame Components
altspace-transform-controls (Example)
Enables an object's position, rotation and scale to be manipulated in AltspaceVR using a draggable transform gizmo.
Properties
Name | Type | Default | Description |
---|---|---|---|
control-type |
String | none | The default control type to be selected. Supported control types are none , position , rotate or scale . |
show-buttons |
Boolean | false | Specifies whether buttons should be displayed to toggle between control types. |
follow-target |
Boolean | true | Specified whether the transform gizmo should follow the object that is being manipulated. |
target |
Selector | null | The target that the transform gizmo should manipulate when interacted with. If omitted, the object that the behavior is associated with will be used as the target. |
scale |
Number | 1 | Adjusts the scale of the transform gizmo. |
allow-negative-scale |
Boolean | false | Specifies whether the scale transform gizmo will allow the target's scale to be negative. |
sync-events |
Boolean | true | Specifies whether the sync ownership is gained when drag events are fired. Requires sync and sync-transform components be present on the target object. |
position-axis-lock |
String | xyz | Specifies which axes of the position gizmo can be displayed and manipulated. |
rotate-axis-lock |
String | xyz | Specifies which axes of the rotate gizmo can be displayed and manipulated. |
scale-axis-lock |
String | xyz | Specifies which axes of the scale gizmo can be displayed and manipulated. |
disable-colliders |
Boolean | true | Specifies whether colliders on the target object should be disabled. |
disable-child-colliders |
Boolean | true | Specifies whether colliders on the target's children should be disabled. |
n-text-material (Example)
Updates the color and opacity of a n-text native component using a material source.
Properties
Name | Type | Default | Description |
---|---|---|---|
material |
Selector | A reference to the object whose material properties will be applied to the n-text native component. Defaults to material of the object the component is attached to. | |
color |
Boolean | true | Specifies whether the n-text native component should use the color of the source material. |
opacity |
Boolean | true | Specifies whether the n-text native component should use the opacity of the source material. |