{{draft}}
Whitestorm.js is a framework built on the top of Three.js technology, enhanced by features such as a built-in Physics engine — a modified Physi.js that acts as a wrapper around Ammo.js (Bullet Physics ported to JavaScript) with usage of web-workers technology — and a plugin system providing useful modularity. In this article we show how you can get started with Whitestorm.js.
Environment setup
Whitestorm.js can be used in Node applications, and included in client-side projects either manually or as a bower component. Let's look at how we can do this.
Node
- Run
npm install whitestormjs. - Import the whitetormjs module to your app and start using it, as demonstrated below:
import * as WHS from 'whitestormjs';
const world = new WHS.World({
background: {
color: 0xDDDDDD
}
});
// ...
Bower
- Run
bower install whitestormjs - Include whitetormjs in your app as follows:
<script src="bower_components/whitestormjs/build/whitestorm.js"></script>
Manual
- Make a copy of the WhitestormJS library file in your app directory.
- Include a {{htmlelement("script")}} element in your HTML {{htmlelement("head")}} (or after your {{htmlelement("body")}}) to apply the Whitestorm JavaScript to your HTML:
<script src="{path_to_lib}/whitestorm.js"></script>
Developing a Whitestorm app
Let's look at how we can create a quick sample Whitestorm app.
Getting started
Create a new index.html file in a new directory. Use our simple template if you don't already have one handy.
Follow the {{anch("Manual")}} insrtructions above to apply the Whitestorm library to your HTML.
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).
That's how combination of world & cube code looks in your browser:
You can try it right now:
{{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.
Conclusion
Whitestorm.js framework wil be best suitable for complex 3D browser games that rely on calculating objects transforms by collisions between them and other physics features. But flexibility of Whitestorm.js allows you to use it's API without parts you don't need, so usage in games that don't rely on physics on even basic apps or just beatiful websites is also welcome cause you can use whitestorm.light.js that is more lightweight than whitestorm.js.
Links
- WhitestormJS website / API
- Github (Feel free to contribute)
- Playground
Tutorials
- Developing a street basketball game. Part I: Getting workflow ready
- Developing a street basketball game. Part ll: Throw a ball into a basket.
- Developing a street basketball game. Part lll: Level selecting and stats