AltspaceVR SDK

Latest Version: v0.5.0 -- See Changes

The AltspaceVR SDK can be used together with three.js to create holographic, multi-user web apps for virtual reality. When running inside AltspaceVR they can be experienced with consumer VR hardware including the Oculus Rift DK2.

Three.js is an open-source, render-agnostic 3D engine written in Javascript. It is used to construct much of the 3D graphics you see on the web, and can be used to create entire applications, or enhance existing webpages with 3D content.

Resources

Getting Started - If you're new to the SDK, start here!
API Reference - Reference for built in API functions, utilities, and more
Developer Portal - Tutorials, projects, initiative program, and app submission
Developer Answers - Questions and answers about the SDK
CodePen - Examples that can be edited live in AltspaceVR
Slack - Chat with other members of the community and AltspaceVR devs. Register for Slack

altspace.js

altspace.js should be included whenever you use the SDK. It contains core utilities and apis, and is useful both inside and outside of the client.

Many APIs are present in the client without loading altspace.js, but please still include it, as this may change in the future.

The version baked into the altspace.js script you include will determine which version of the entire SDK that the client will provide your app. This means that if we make any breaking internal changes to things like rendering or cursor events, and you are using an older version of altspace.js we will try to return legacy behavior appropriate to your version of altspace.js. Versioning will follow SEMVER as closely as possible. Details for each version can be found in the Release Notes.

To always use the latest version, simply add this script tag to your project:

<script src="http://sdk.altvr.com/libs/altspace.js/latest/altspace.min.js"></script>

or to include a specific version add:

<script src="http://sdk.altvr.com/libs/altspace.js/0.5.0/altspace.min.js"></script>

API Overview

See the API Reference for full details and a complete list of APIs and utilities.

Note that many of our APIs make use of Promises. Learn about how they work over at HTML5 Rocks

Holographic Rendering

• var renderer = altspace.getThreeJSRenderer();
  returns a renderer that can be used to render three.js scenes as holographic objects

  Holographic objects are limited to the size of the enclosure (1024 x 1024 x 1024 in the apps panel and public 3D browsers, 1280 x 720 x 300 in the browse panel, units are CSS pixels)

Cursor Events

The basic way to allow the user to interact with three.js objects in AltspaceVR is by attaching cursor event listeners.

Note that currently every mesh is represented in our physics engine as object aligned cuboids, 80% the size of a full bounding box (basically a stretched cube that contains most of the object). This means that the cursor will not precisely collide with your meshes, and that signifigantly concave objects (buckets, etc) will block contained objects from being clicked on.

• mesh.addEventListener('cursorup' / 'cursordown', callback);
  listen for cursor events on a specific mesh.

  These events will bubble up the three.js hierarchy. stopPropagation and stopImmediatePropagation are supported and work similarly to DOM events

• scene.addEventListner('cursormove', callback)
  listen for cursor move events

Enclosure Properties

• altspace.getEnclosure().then(callback)
  returns a promise that will fufill with a description of the enclosure, including its size and pixelsPerMeter which can be used as a coefficient to maintain static sizes for objects regardless of the scale of the enclosure.

User Data

• altspace.getUser().then(callback)
  returns a promise that will fufill with information about the local user

Tracking Skeleton

• altspace.getThreeJSTrackingSkeleton().then(callback)
  returns a promise that will fufill with a three.js object hierarchy with each object representing a joint in the unified tracking skeleton. These object's transforms will be automatically updated by AltspaceVR, so feel free to query them for position or add objects as children. Make sure to add the skeleton to your scene after receiving it

Debugger

The Debugger is essentially a remote Chrome inspector for AltspaceVR browsers.

OSX Debugger - Windows Debugger

Note that you cannot rename the OSX Debugger from Debugger.app after you extract it, or it won’t run due to legacy .app bundle structure — it needs an Info.plist with metadata.

Three.js Feature Support

Currently supported:

• Object3D transformation and hierarchy
• Most Geometries
• MeshBasicMaterial map and color properties
• Examples that should work: Draggable Cubes - Voxel Painter - Falling Cubes - Flocking Birds - OBJ/MTL Import

Not currently supported:

• Lighting, custom shaders, screen space effects.
• Examples that won't work: Hemisphere Light - Material Reflection - Ocean Shader
• Using GIF images for textures
• Line Geometries
• Dynamic meshes, skinned meshes
• Geometries with more than 65,000 vertices (Note: Calculated as <number of faces> * 3)

Habits of Successful AltspaceVR Web Apps:

• Use power-of-two dimensions on your textures for improved performance.
• Mind your texture sizes. Large textures can cause frame locking in the client.
• If your app requires many different textures and geometries, add them to a scene incrementally.
• Use Object3D transforms (position, rotation, scale) for animation rather than skinned meshes.
• Get user input via AltspaceVR cursor events or the tracking skeleton rather than from the keyboard.
• Limit the number of objects per scene and polygons per object.
• Bake ambient occlusion and other lighting into your models. All models currently render as unlit.

---