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.World
object. 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 specifycontainer
property 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.Shape
class 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