Diorama is a framework for running multiple micro-apps out of a single AltspaceVR enclosure. It handles most of tedious stuff that every app needs, like setting up the render loop, scaling the enclosure, and loading models/textures, and lets you get right to the meat of your idea.
- Compartmentalized code for different micro-apps ("dioramas")
- Easy-to-use asset loader and cache
- Reduces boilerplate code
- Encourages best practices
- Includes web browser preview mode
<html>
<head>
<script src="https://cdnjs.cloudflare.com/ajax/libs/three.js/r74/three.js"></script>
<script src="http://sdk.altvr.com/libs/altspace.js/0.18.2/altspace.min.js"></script>
<script src="../lib/ColladaLoader.js"></script>
<script src="../dist/diorama.js"></script>
</head>
<body>
<script>
// this is a "diorama"
var globe = {
initialize: function(env, root, assets){
// passed the enclosure info, a scene root (in meter scale),
// and the requested assets
root.rotateX(-Math.PI/2);
root.add(assets.models.globe);
},
assets: {
models: {globe: 'models/globe.dae'}
}
};
var diorama = new Diorama();
diorama.start(globe);
</script>
</body>
</html>
Arguments:
options
[Object] - An object with any of the following properties:bgColor
[color] - The background color of the preview. Can be a hexidecimal or a CSS style string. Defaults to0xAAAAAA
.gridOffset
[Array] - The preview grid's 3D position. Defaults to [0,0,0].fullspace
[boolean] - Tells the app to occupy the full space viarequestFullspace()
.
Returns: Diorama
This class is the entrypoint into the framework. When you create an instance of Diorama, the enclosure and space information is saved into the instance, and it sets up a new empty cache.
Arguments: The diorama objects you want to run
Returns: None
Loads the assets for the requested dioramas, and calls their initialize
functions. Also starts the render loop.
Arguments: A diorama asset manifest
Returns: A Promise that resolves with the requested assets
This function is already called by Diorama.start
, but is included here for flexibility. Give it the list of assets you want, and it will start them loading (from cache if available), and return a promise that will resolve when the assets are done loading.
Diorama objects are required to have only one property: a function initialize
. You may also want to provide an asset manifest (assets
).
This is the kickoff point for your diorama. Given the space information (env
), a scene root (root
), and your assets (assets
), construct your scene here. For best compatibility with other dioramas, it is recommended that you do not access any scene node above the root you are given.
env
[Object] - The concatenated responses ofaltspace.getEnclosure()
andaltspace.getSpace()
.root
[Object3D] - The root of your diorama, in meter scale. If you want your diorama placed somewhere in the room other than in the center of the enclosure, set theroot.position
.assets
[Object] - Contains themodels
andtextures
requested by your diorama. Seeassets
below.
Specify the matrix transformation of the diorama's root, of the form accepted by THREE.Matrix4.fromArray().
Specify the vertical position of the root relative to the enclosure. Defaults to "middle".
Specify the models and textures that you need for your diorama here. This object can contain a models
object and/or a textures
object. Each of these sub-objects should contain identifiers for the assets as property names, and URLs to the assets as property values.
For example, if you wanted to load an OBJ file at './models/mymodel.obj', you might have this as an assets manifest:
"assets": {
"models": {
"mymodel": "./models/mymodel.obj"
},
"textures": {
"mytexture": "./textures/blah.png"
}
}
You would then access this model at assets.models.mymodel
in your initialize
function.
Specifies whether the user tracking skeleton is required by the module. If any loaded module requires it, it will be initialized, added to the scene, and passed to the modules via env.skeleton
. Defaults to false
.