threestrap

_Use Three.js with zero hassle._

---

Threestrap is a minimal, pluggable bootstrapper for Three.js that gets out of
your way.

While this is definitely a miniature framework, it's not really meant to wrap
_your_ code, but rather the code you don't care about.

Examples:

- Basic Cubes
- Drag/Zoom Controls
- WebGL + CSS 3D
- VR + Controls

Usage

Install via npm:

``sh
npm install threestrap
`

Add build/threestrap.js to your Three.js:

`html



`

Get a threestrap context:

`javascript
const three = new Threestrap.Bootstrap();
`

This will create a full-page Three.js WebGL canvas, initialize the scene and
camera, and set up a rendering loop.

You can access the globals three.scene and three.camera, and bind events on
the three context:

`javascript
// Insert a cube
const mesh = new THREE.Mesh(
new THREE.CubeGeometry(0.5, 0.5, 0.5),
new THREE.MeshNormalMaterial()
);
three.scene.add(mesh);

// Orbit the camera
three.on("update", function () {
var t = three.Time.now;
three.camera.position.set(Math.cos(t), 0.5, Math.sin(t));
three.camera.lookAt(new THREE.Vector3());
});
`

Configuration

Threestrap is made out of plugins that each do one thing. The basic set up of
empty or core gets you a fully-functional canvas in the body or a specific
DOM element.

Empty:

- fallback - Displays a standard message with a link if WebGL is unavailable.
- bind - Enables event/method binding.
- renderer - Creates the THREE.WebGLRenderer (or a given class).
- size - Autosizes canvas to fit or size to given dimensions.
- fill - Removes margin/padding and sets positioning on the element.
- loop - Runs the rendering loop.
- time - Measures time and fps in seconds. Provides clocks.

Core:

- scene - Creates the THREE.Scene
- camera - Creates the THREE.Camera
- render - Renders the global scene and camera directly.
- warmup - Hide canvas for first few frames to avoid stuttering.

Additional plug-ins can be added, or the default set can be overridden on a case
by case basis. empty is a do-it-yourself set up.

Shorthands:

`javascript
// Core only
var three = new Threestrap.Bootstrap();

// Pass in list of plugins
var three = new Threestrap.Bootstrap("core", "stats");
var three = new Threestrap.Bootstrap(["core", "stats"]);

// Insert into specific element
var three = new Threestrap.Bootstrap(element);
var three = new Threestrap.Bootstrap(element, "core", "stats");
var three = new Threestrap.Bootstrap(element, ["core", "stats"]);

// Replace plugins ad-hoc
var three = new Threestrap.Bootstrap(["core", "stats", "render:myRender"]);
`

The following global options are available with these defaults:

`javascript
var three = new Threestrap.Bootstrap({
init: true, // Initialize on creation

element: document.body, // Containing element

plugins: [
// Active plugins
"core", // Use all core plugins
// 'render:myRender' // Ad-hoc overrides
],

aliases: {
// Ad-hoc overrides
// 'render': 'myRender',
// 'alias': ['myFoo', 'myBar']
},
});
`

When init is set to false, initialization only happens when manually calling
three.init(). To destroy the widget, call three.destroy().

Plugins can make objects and methods available on the threestrap context, like
three.Time.now or three.Loop.start().

Plugins

To enable a plug-in, include its name in the plugins field. Plugins are
installed in the given order.

Plug-in specific options are grouped under the plug-in's name:

`javascript
const three = new Threestrap.Bootstrap({
plugins: ["core", "stats"],
size: {
width: 1280,
height: 720,
},
camera: {
fov: 40,
},
});
`

The following aliases are available:

- empty = fallback, bind, renderer, size, fill, loop, time
- core = empty + scene, camera, render, warmup

Events

Threestrap plugins broadcast events to each other, like resize or render.

You can listen for events with .on() and unset them with .off().

`javascript
three.on("event", function (event, three) {});
`

`javascript
var handler = function () {};
three.on("event", handler);
three.off("event", handler);
`

You can also bind events directly to object methods using .bind:

`javascript
const object = {
render: function (event, three) {},
yup: function (event, three) {},
redraw: function (event, three) {},
resize: function (event, three) {},
change: function (event, three) {},
};

// Bind three.render event to object.render(event, three)
three.bind("render", object);

// Bind three.ready event to object.yup(event, three);
three.bind("ready:yup", object);

// Bind object.change event to object.redraw(event, three);
three.bind("this.change:redraw", object);

// Bind window.resize event to object.resize(event, three);
three.bind("window.resize", object);

// Bind DOM element's onchange event to object.change(event, three);
three.bind([element, "change"], object);
``

Docs

- Core reference
- Extra plugins reference
- Write custom plugins

---

Steven Wittens - http://acko.net/