npm.io
1.0.2 • Published 8 years ago

altspacevrutil

Licence
MIT
Version
1.0.2
Deps
2
Size
3.0 MB
Vulns
0
Weekly
0
Stars
3
DeprecatedThis package is deprecated
SummaryDependencyVersions

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

Behaviors

Events

A-Frame Components

Functions

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.

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

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.

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.

Resources

Keywords

altspacealtspacevraltspacesdkaltspaceutilvrwebvrbehavioraframe