@sicmutils/threestrap
v0.4.0
Published
Minimal Three.js Bootstrapper
Downloads
1
Readme
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:
Usage
Install via npm:
npm install @sicmutils/threestrap
Add build/threestrap.js
to your Three.js:
<script src="three.js"></script>
<script src="threestrap.js"></script>
Get a threestrap context:
var 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:
// Insert a cube
var 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 theTHREE.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 theTHREE.Scene
camera
- Creates theTHREE.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:
// 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:
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()
.
Builds
- threestrap.js: Full build (but still requires three.js)
- threestrap-core.js: Core only, requires three.js + lodash
- threestrap-extra.js: Extra plugins
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:
var 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()
.
three.on("event", function (event, three) {});
var handler = function () {};
three.on("event", handler);
three.off("event", handler);
You can also bind events directly to object methods using .bind
:
var 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
Steven Wittens - http://acko.net/