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).
{{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.