Whitestorm.js is a framework built on the top of Three.js technology. It's main distinction is existance of built-in Physics engine. Basically, it is a modified Physi.js, API wrapper around Ammo.js (Bullet Physics ported to JavaScript) with usage of web-workers technology. Next main addition is a plugin system based Whitestorm.js modularity. Developers can share their plugins & components and include them in really big projects.
Environment setup
Node
- Run
npm install whitestormjs - Import whitetormjs module to your app and start using:
import * as WHS from 'whitestormjs';
const world = new WHS.World({
background: {
color: 0xDDDDDD
}
});
// ...
Bower
- Run
bower install whitestormjs - Include whitetormjs to your browser:
<script src="bower_components/whitestormjs/build/whitestorm.js"></script>
Browser
Include a script tag linking the WhitestormJS library in your head or after your body:
<script src="{path_to_lib}/whitestorm.js"></script>
Development
Fast explanation:
- Make a javascript file or use
<script>tag to develop main app. - Now you can work with WhitestormJS framework and make a 3D scene.
- Make a
WHS.Worldobject. It will process all other objects added to world (it's children). - World renders in a
<canvas>tag and we need add it to DOM. To do this - simply specifycontainerproperty in WHS.World. It's default:document.body. - Another object is
WHS.Sphere. It is a basic component for THREE'sTHREE.SphereGeometry. It is based onWHS.Shapeclass that wraps API for working with meshes. You can specify position (pos), rotation (rot), scale, material and all mesh-related stuff right in this class.
const world = new WHS.World({
stats: "fps", // fps, ms, mb or false if not need.
autoresize: "window", // Call autoresize when app window is resized.
gravity: { // Physic gravity.
x: 0,
y: -100,
z: 0
},
camera: {
z: 50 // Move camera.
},
container: document.body
});
const sphere = new WHS.Sphere({ // Create sphere object.
geometry: { // It will create a THREE.SphereGeometry(3)
radius: 3
},
mass: 10, // Mass of physics object.
material: { // Material
color: 0xffffff,
kind: 'basic' // THREE.MeshBasicMaterial
},
pos: { // Position vector.
x: 0,
y: 100,
z: 0
}
});
sphere.addTo(world); // Add Sphere to world.
world.start(); // Start animations and physics simulation.
There is also explanation for usage with webpack
Creating a world
When you create a world in Whitestorm.js it automatically creates THREE.Scene, WebGL renderer and applies camera. But don't worry, all of them you can access simply as: world.scene, world.renderer, world.camera. WHS.World is highly editable class. All parameters are non-required and have their own default values. Check or change them you can in WHS.World.defaults. See all of them
const world = new WHS.World({
background: {
color: 0xffffff
},
camera: {
z: 50
},
gravity: {
y: -100
}
});
Using physics in Whitestorm.js is not required. You may rather use whitestorm.light.js build that is without included Ammo.js and physics part.
Rendering a box
Same rule with defaults is also related to other classes. Each mesh consist of geometry & material. As we make a WHS.Box component - our geometry is THREE.BoxGeometry. If you know Three.js - you would probably ask: What if i want to use THREE.BoxBufferGeometry? - The answer is a buffer property.
const cube = new WHS.Box({
geometry: {
width: 10,
height: 10,
depth: 10
},
material: {
kind: 'basic',
color: 0x0095DD
},
rot: {
x: 0.4,
y: 0.2
}
});
cube.addTo(world);
cube.addTo() method is used to apply this box to a specific world object that will render it and process collisions, "z-index" (Calculated by camera direction and other objects positions), it's color on rendered image (can depend on lights & shadows of other objects).
{{JSFiddleEmbed("https://jsfiddle.net/4phf4oty/1/","","350")}}
This JSFiddle uses whitestorm.light.js (A version without built-in physics). You may also check the one with physics: https://jsfiddle.net/g2s5bgrL/
Components & Plugins
Almost each whitestorm.js class is a component. Box, Sphere, Tetrahedron - all these are components, but basic (simple Three.js geometries based on WHS.Shape).
Adding custom components is also welcome. To develop your own plugin/component you have to install generator-whs-plugin and follow it's instruction:
- Make a new repository.
- Install Yeoman:
npm install -g yo - Install Whitestorm.js plugin generator:
npm install -g generator-whs-plugin - Run
yo whs-plugin. - Edit files in src/ for your needs. You will see already defined plugin source there, just change it as you want.
Playground
Playground is where you can create a basic whitestormjs app without downloading a WhitestormJS or setting up a project. You can also share your app with others by clicking “share” button and then you can share it in twitter, facebook or just copy to clipboard.