altspacevrutil v1.0.2

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.rawgit.com/NGenesis/altspacevr-behaviors/v1.0.2/js/altspaceutil.min.js"></script>

API Reference

Functions

• altspaceutil.getFullspaceEnclosure
• altspaceutil.getAbsoluteURL
• altspaceutil.getBasePath
• altspaceutil.isMobileApp
• altspaceutil.expandSerializationBuffer
• altspaceutil.profileSerializationBuffer
• altspaceutil.setCursorCollider
• altspaceutil.isCursorCollider
• altspaceutil.loadTexture

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

Events

• transform-controls-dragmove
• transform-controls-dragbegin
• transform-controls-dragend
• avatarchange
• userchange
• avatarstatus
• n-sound-preloaded

A-Frame Components

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

Functions

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

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
}

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

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

n-text-material (Example)

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

Properties

Resources

• Three.js API for AltspaceVR
• A-Frame API for AltspaceVR
• AltspaceVR Native Resources
• TextMesh Pro Documentation