Skip to content
VR app framework based on three.js
Branch: master
Clone or download

README.rst

threelet

threelet is a three.js based VR app framework for rapidly making 3D browser/WebVR applications.

Using threelet's built-in features, developers who have a minimal knowledge of three.js can immediately start writing interactive 3D apps with less code.

Some notable features include:

  • built-in render loop manager (with auto VR context switching),
  • function interface .update = (t, dt) => {} for programming temporal 3D scenes, and
  • easy-to-use mouse/vr-controller event listeners.

Basic demos

App demos

Screenshots

Setup

Installation

$ npm install threelet

Loading

ES6:

import Threelet from 'src/index.js';

Script tag:

<script src="dist/threelet.min.js"></script>

Hello world

<canvas id="canvas" style="width: 100%; height: 100%;"></canvas>

<script src="../deps/three.min.js"></script>
<script src="../deps/OrbitControls.js"></script>
<script src="../deps/stats.min.js"></script>

<script src="../../dist/threelet.min.js"></script>

<script>
const threelet = new Threelet({
    canvas: document.getElementById('canvas'),
});

threelet.setup('mod-controls', THREE.OrbitControls);
threelet.setup('mod-stats', window.Stats);

threelet.render(); // first time
</script>

live | source code

https://w3reality.github.io/threelet/examples/simple/img/threelet.png

More usage

Basic

camera, scene and renderer can be automatically/manually configured:

const threelet = new Threelet({canvas: myCanvas});
// now the following objects are all set
//   threelet.camera
//   threelet.scene (with the default axes and a unit lattice)
//   threelet.renderer

scene can be customized as:

const threelet = new Threelet({
    canvas: myCanvas,
    optScene: myScene, // instantiate with a custom scene
});

threelet.scene.add(myObject) // add an object to the scene

specifying render modes (passive, active, and fps-throttled) by the built-in loop controller:

threelet.updateLoop(fps); // render at fps using the looper

threelet.render(); // atomic render manually

programming 3D scene dynamics (example | source):

threelet.update = (t, dt) => {
   // your implementation
};

dispose() terminates the loop and disposes all the scene objects:

threelet.dispose();

Parameters

Calling the constructor with the default parameters looks as:

const threelet = new Threelet({
    canvas: null,
    width: 480,
    height: 320,
    // ---- viewer options ----
    optScene: null,
    optAxes: true, // axes and a unit lattice
    optCameraPosition: [0, 1, 2], // initial camera position in desktop mode
});

Extending the Threelet class (Object-Oriented Programming)

(example | source):

class App extends Threelet {
    // override
    onCreate(params) {
        // ...
    }

    // override
    onUpdate(t, dt) { // note: this method is not called when this.update is defined
        // ...
    }

    // override
    onDestroy() {
        // ...
    }
}

Embedding

Without the canvas parameter, the constructor creates an inline-block div element (threelet.domElement) that is ready to be embedded into a web page. (single case | multiple case)

<div>
    This <span id="viewer"></span> is an inline-block element.
</div>

<script>
const threelet = new Threelet({width: 480, height: 320});
document.getElementById('viewer').appendChild(threelet.domElement);
</script>

High-level input management

(example | source):

threelet.setupMouseInterface({
    onClick: (mx, my) => { /* ... */ },
    onDrag: (mx, my) => { /* ... */ },
    onDragStart: (mx, my) => { /* ... */ },
    onDragEnd: (mx, my) => { /* ... */ },
});

threelet.setupTouchInterface({
    onClick: (mx, my) => { /* ... */ },
    onDrag: (mx, my) => { /* ... */ },
    onDragStart: (mx, my) => { /* ... */ },
    onDragEnd: (mx, my) => { /* ... */ },
});

Low-level event listeners

setting mouse listeners (example | source):

// mx, my: mouse coordinates

threelet.on('mouse-click', (mx, my) => { /* ... */ }); // alias of 'mouse-click-left'
threelet.on('mouse-click-left', (mx, my) => { /* ... */ });
threelet.on('mouse-click-middle', (mx, my) => { /* ... */ });
threelet.on('mouse-click-right', (mx, my) => { /* ... */ });
threelet.on('mouse-down', (mx, my) => { /* ... */ });  // alias of 'mouse-down-left'
threelet.on('mouse-down-left', (mx, my) => { /* ... */ });
threelet.on('mouse-down-middle', (mx, my) => { /* ... */ });
threelet.on('mouse-down-right', (mx, my) => { /* ... */ });
threelet.on('mouse-move', (mx, my) => { /* ... */ });
threelet.on('mouse-up', (mx, my) => { /* ... */ });
threelet.on('mouse-drag-end', (mx, my) => { /* ... */ });

threelet.on('touch-start', (mx, my) => { /* ... */ });
threelet.on('touch-move', (mx, my) => { /* ... */ });
threelet.on('touch-end', (mx, my) => { /* ... */ });
threelet.on('touch-click', (mx, my) => { /* ... */ });
threelet.on('touch-drag-end', (mx, my) => { /* ... */ });

setting VR controller listeners (example | source):

// i: controller index
// x, y: controller touchpad coordinates

threelet.on('vr-touchpad-touch-start', (i, x, y) => { /* ... */ });
threelet.on('vr-touchpad-touch-end', (i, x, y) => { /* ... */ });
threelet.on('vr-touchpad-press-start', (i, x, y) => { /* ... */ });
threelet.on('vr-touchpad-press-end', (i, x, y) => { /* ... */ });

threelet.on('vr-trigger-press-start', (i) => { /* ... */ });
threelet.on('vr-trigger-press-end', (i) => { /* ... */ });

unsetting listeners:

threelet.on(eventName, null);

Raycasting

threelet.raycast(origin, direction, meshes, recursive=false, faceExclude=null);
threelet.raycastFromMouse(mx, my, meshes, recursive=false); // mx, my: mouse coordinates
threelet.raycastFromController(i, meshes, recursive=false); // i: VR controller index

Utils

animation loading (example | source):

// <script src="../deps/GLTFLoader.js"></script>
const data = await Threelet.Utils.loadGLTF(path, file);

// <script src="../deps/inflate.min.js"></script>
// <script src="../deps/FBXLoader.js"></script>
const data = await Threelet.Utils.loadFBX(path);

// <script src="../deps/ColladaLoader.js"></script>
const data = await Threelet.Utils.loadCollada(path);

creating test THREE objects (used in the examples for shortcuts):

const obj = Threelet.Utils.createTestHemisphereLight();
const obj = Threelet.Utils.createTestDirectionalLight();
const obj = Threelet.Utils.createTestCube(size=[0.4, 0.1, 0.4], color=0xff00ff, wireframe=false);
const objs = Threelet.Utils.createTestObjects(offset=[0, 1, -2]);

Plugin features

OrbitControls, stats, and WebVR:

<script src="OrbitControls.js"></script>
<script src="stats.min.js"></script>
<script src="WebVR.js"></script>
threelet.setup('mod-controls', THREE.OrbitControls); // enable controls
threelet.setup('mod-stats', window.Stats); // show the stats meter
threelet.setup('mod-webvr', window.WEBVR); // show the desktop/VR switch button

Sky based on the shaders/sky example in three.js:

<script src="Sky.js"></script>

threelet.setup('mod-sky', THREE.Sky); // show sky with the analytical daylight

Build

$ npm install  # set up build tools
$ npm run build  # generate module files in lib/
You can’t perform that action at this time.