altspacevr-behaviors v1.1.5

AltspaceUtil

Provides helper functions, behaviors and A-Frame components for common functionality compatible with AltspaceSDK.

Usage

Include the utility library in your project:

<script src="https://cdn.jsdelivr.net/npm/altspacevr-behaviors@1.1.5/js/altspaceutil.min.js"></script>

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

• FullspaceApp

A-Frame Components

• altspace-transform-controls
• n-text-material

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

Returns

altspaceutil.getFullspaceEnclosure

Gets the fullspace enclosure for the app.

Returns

altspaceutil.getAbsoluteURL

Create an absolute URL from the specified relative URL, using the current host as the URL base.

Parameters

Returns

altspaceutil.getBasePath

Create a base path from the specified file URL.

Parameters

Returns

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

altspaceutil.expandSerializationBuffer

Expands the Altspace client's serialization buffer to improve loading performance.

Parameters

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

altspaceutil.setCursorCollider

Sets the Altspace cursor collider property for the specified object.

Parameters

altspaceutil.isCursorCollider

Gets the Altspace cursor collider property for the specified object.

Parameters

Returns

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

Returns

altspaceutil.loadScript

Loads and executes a script from the specified JavaScript file URL.

Parameters

Returns

altspaceutil.loadScripts

Loads and executes one or more scripts from the specified JavaScript file URL.

Parameters (1)

Parameters (2)

Script parameters.

Returns

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.
• 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

Returns

altspaceutil.loadAssets (Example)

Loads one or more assets from the specified URLs.

Parameters (1)

Parameters (2)

Asset parameters.

Returns

altspaceutil.addAssetLoader (Example)

Registers a handler that will load and construct the specified asset type when loadAsset or loadAssets is called.

Parameters

AssetLoaderHandler parameters.

altspaceutil.removeAssetLoader

Unregisters a handler for the specified asset type that is used when loadAsset or loadAssets is called.

Parameters

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

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.

Methods

callComponentAction

Invokes an action associated with the native component, and does not provide a return value.

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.

callComponent

This function has been Deprecated. See callComponentAction.

getAttribute

Retrieves an attribute associated with a native component. See here for available attributes.

Native Component Attributes

Attributes associated with a native component can be retrieved using the getAttribute method.

n-sound

n-gltf

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: 0.05,
	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.

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.

Events

transform-controls-dragmove

Fires an event when the transform gizmo is being dragged.

transform-controls-dragbegin

Fires an event when the transform gizmo starts being dragged.

transform-controls-dragend

Fires an event when the transform gizmo is no longer being dragged.

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.

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.

Methods

subscribeUser

Subscribe to receiving events for a given User ID.

unsubscribeUser

Unsubscribe from receiving events for a given User ID.

Events

avatarchange

Fires an event when the user changes avatar preferences.

userchange

Fires an event when the user changes account preferences.

avatarstatus

Fires an event when the user's connection status changes.

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.

Events

n-sound-preloaded

Fires an event once all sounds have been preloaded, or the specified timeout threshold has been reached.

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.

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.

altspaceutil.behaviors.NativeTextMaterial (Example)

Updates the color and opacity of a n-text native component using a material source.

Parameters

config - Optional parameters.

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

altspaceutil.behaviors.Billboard (Example)

The Billboard behavior updates the orientation of an object to face the camera.

Parameters

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 are black, blue, green, orange, purple, red, yellow or white.
• <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

altspaceutil.behaviors.GLTF (Example)

The GLTF behavior loads and displays a glTF model asset.

Parameters

Members

Methods

getBoundingBox

Retreives the axis aligned bounding box of the loaded glTF model.

Returns

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

Members

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

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.getFullspaceApp(app => {
	app.anchor.add(skyboxModel);
	app.anchors('performerstage').add(concertStageModel);
	app.anchors('audiencestand').add(audienceStandModel);
});

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": 0.5, "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