whitestormjs/whs.js

:rocket: 🌪 Super-fast 3D framework for Web Applications 🥇 & Games 🎮. Based on Three.js

• Documentation
• Examples
• Contributions/Trello
• Donate / OpenCollective

Community chat. Join us!

Table of content

• Basic setup
  • npm
• Featured projects
• Features
• Donate
• Why?

New releases

whs is currently at v2 major version. We had plans for v3 yet but development isn't active. So v2 will probably remain the main stable version until further notice.

We try to publish minor update releases for bug fixes, we will review PRs.

NPM

# Install npm version
$ npm install whs

For [email protected] (Three.js r92) use @beta tag

# Install npm version
$ npm install whs@beta

Basic setup

Download the minified library or link the one from CDN

<script src="js/three.min.js"></script>
<script src="js/whs.min.js"></script>

The code below makes a WHS.App instance which handles all your modules and components for better work with WebGL. This one creates a scene, camera and renderer - we add the following modules to the App.

const app = new WHS.App([
  new WHS.ElementModule(), // Apply to DOM.
  new WHS.SceneModule(), // Create a new THREE.Scene and set it to app.

  new WHS.DefineModule('camera', new WHS.PerspectiveCamera({ // Apply a camera.
    position: new THREE.Vector3(0, 0, 50)
  })),

  new WHS.RenderingModule({bgColor: 0x162129}), // Apply THREE.WebGLRenderer
  new WHS.ResizeModule() // Make it resizable.
]);

app.start(); // Run app.

Featured projects

Features

• 💎 Simple in usage
• 🚀 Speeds up 3D scene prototyping
• 🔌 Component based scene graph
• 💣 Simple integration of any high performance physics even with Worker (Multithreading)
• 💫 Automatization of rendering
• 🆕 ES2015+ based
• 🔷 Extension system (modules)
• 📦 Webpack friendly
• ✔️ Integrated Three.js rendering engine
• 💞 Work with whs.js and Three.js at the same time

External Modules

Name	Status	Description
physics-module-ammonext		Physics module based on Ammo.js

Donate

Backers

Support us with a monthly donation and help us continue framework development🎉 and adding new features💡🎁.

whs.js's Issues

[Bug] Object controls

Cannot control object position, rotation or scale with it's scope.
Example

horse = game.addMorph('assets/models/morph/horse.js',{
  pos: {
    x: 0, y: 0, z: 0
  },
  scale: {
    x: 0.1, y: 0.1, z: 0.1
  }
});
horse._pos.x = 10; //Doesn't do anything, even tried from chrome's console
horse.mesh.position.x = 10; //Works instead

I suggest making scope._pos the same as mesh.pos

[Improve] Engine structure.

To-do:

• Fix code style in:
  • src/libs/firstPersonControls.js (Remove unnecessary varibles, unused lines of code) (Follow guidelines)
  • src/Objects/addObject.js (Unused code. Complexity.) (Follow guidelines)
  • src/Skybox/addSkybox.js (Unused code. Complexity.) (Follow guidelines)
  • src/Shaders/ShaderTerrain.js (Remove commented code) (Follow guidelines)
  • src/Controls/FPSControls.js (Unused code. Complexity.) (Follow guidelines)
  • Other files in src/ folder. (Follow guidelines)
    • API/*
    • Ground/*
    • Objects/*
    • Controls/*
    • Plugins/*
    • Wagner/*
    • Watchers/*

Guidelines:

• Follow code style guides:
  • Mr.doob
  • Google
• Each line of code should not be longer than 80 symbols
• https://www.codacy.com/app/siteprogcom/WhitestormJS/dashboard
• After you fixed one file:
  • Write CSF. {filenamehere} to current version in CHANGELOG.md file.
  • Commit with msg CSF. {filenamhere} #25 or just CSF.
• Engine structure:
  • src/libs/firstPersonControls.js -> src/Controls/FPSControls.js (Wrap code from 1 file to 2 file)
  • Fix filenames in src/folder :
    • FirstSecondWord.js
    • in src/libs/ keep them like they are. (already done).
  • Clean gulpfile.
  • Remove src/API/Def.js.
  • src/API/IsSame.js-> src/API/RemoveDuplicateFaces.js (Wrap code from 1 file to 2 file)
  • Remove src/API/Loaders.js and src/API/Shape.js (Reason: they are too small)
  • Sort unsorted files.
  • Remove jquery library.
  • Remove assets/ folder.
  • Remove src/API/RotateBody.js (Reason: no need since cannonjs -> physijs)
  • src/libs/OrbitControls.js (Fix parameter.)
  • src/Watchers/Watch.js -> src/API/Watch.js
• Code structure:
  • src/API/Wrap.js (move scope.remove, scope.retrieve to construct prototype).
  • src/Objects/addObject.js ([Remove] move scope.remove, scope.retrieve toconstruct prototype).
  • Remove dependencies from jQuery (jQuery -> DOM)
  • src/API/Texture.js (defaults for properties).
  • api.def -> $.extend
  • src/whitestorm.js (Use api from src/Watchers/Watch.js)
  • scope.visible -> scope.mesh
  • scope.body - remove.

[Improve] Use aria attributes

Accessible Rich Internet Applications (ARIA)

Use accessibility attributes like aria-label to provide meaningful information for people with visual disabilities.

For more information go to ARIA in HTML

What files to fix:
examples/basic.html
examples/basic_material.html
examples/basic_model.html
examples/fps.html
examples/plugin_example.html
examples/skybox.html
examples/stone_wall.html
or any new example *.html file

How To Do it:
Examples are on Mozilla website Web Technology For Developers

How to test it:

1. Install Vorlon.JS

2. add the following line into your test HTML file:

'< script src="http://localhost:1337/vorlon.js" >' '< /script >'

3. Once Vorlon.JS is done installing, run the server:

$ vorlon

4. With the server is running, open http://localhost:1337 in your browser to see the Vorlon.JS dashboard.

5. Open your test html file, and it should appear on the Vorlon.JS dashboard.

6. In the dashboard, click on the button Best Practice: Accessibility and check the
   use aria attributes

[Improve] Add lang attr on HTML tag

Lang attribute on HTML tag helps people finding out if they will understand content without having to get deep into it.

For more information go to W3

What files to fix:
examples/basic.html
examples/basic_material.html
examples/basic_model.html
examples/fps.html
examples/plugin_example.html
examples/skybox.html
examples/stone_wall.html
or any new example *.html file

How To Do it:
Add language attribute, for example, lang="fr"

How to test it:

1. Install Vorlon.JS

2. add the following line into your test HTML file:

'< script src="http://localhost:1337/vorlon.js" >' '< /script >'

3. Once Vorlon.JS is done installing, run the server:

$ vorlon

4. With the server is running, open http://localhost:1337 in your browser to see the Vorlon.JS dashboard.

5. Open your test html file, and it should appear on the Vorlon.JS dashboard.

6. In the dashboard, click on the button Best Practice: Accessibility and check the
   add lang attr on HTML tag

[Improve] Try bundling your files

Multiple http requests makes your site slower, especially on mobile devices.

What files to fix:
examples/basic.html
examples/basic_material.html
examples/basic_model.html
examples/fps.html
examples/plugin_example.html
examples/skybox.html
examples/stone_wall.html
or any new example *.html file

How To Do it:
Preliminary tests with Vorlon.JS show that there are more than 5 scripts files in a page with the recommendation "consider bundling your scripts".

How to test it:

1. Install Vorlon.JS

2. add the following line into your test HTML file:

'< script src="http://localhost:1337/vorlon.js" >' '< /script >'

3. Once Vorlon.JS is done installing, run the server:

$ vorlon

4. With the server is running, open http://localhost:1337 in your browser to see the Vorlon.JS dashboard.

5. Open your test html file, and it should appear on the Vorlon.JS dashboard.

6. In the dashboard, click on the button Best Practice: PERFORMANCE and check the
   try bundling your files

[Improve] README update

We need to make README looks more friendly.
Example of good README:

Make a water component

I think the idea of water on terrain looks good.
LINKS
Physics: https://github.com/kripken/ammo.js/
Water shader: https://github.com/jbouny/ocean

[Improve] Need to add more textures.

Please add 128x128, 512x512, 1024x1024 textures to assets/textures/

[Improve] WHS.Shape/WHS.Light remove() need to set null to it's root.

Remove funtion only removes object from scene now:

remove() {

    this.root.scene.remove( this.mesh );

    return this;

}

It should remove object also from WHS.World's children array and remove object's (shape's/light's) root value.

[Improve] Make a plugin for wagner effects and post-effects system.

Reason: We need to move wagner to plugins, because now user need to add Wagner libraries each time, even he doesn't need it.

Improvement: Less libraries and data processing for apps, who don't use Wagner effects.

Wagner effects will be in their own repository.

[Bug] Shader doesn't compile on FPS example (Linux/Chrome)

The FPS example is broken on several Linux distributions. Attached is a console log.

[Design] #blocker div looks primitive

Blocker div haven't changed since we made fps example. I think you may need to change design (css)
For example i like example something like this

Examples of good design (my choice 👍 😄 ):

[Improve] Preload for projects/examples

We will make a preload function or api for filling screen with animated gif or loading state while project is loading. This is just for beauty.

For example with this:

But you can choose another variant like:

• http://github.hubspot.com/pace/docs/welcome/
• https://ihatetomatoes.net/create-custom-preloading-screen/
• http://bradsknutson.com/blog/display-loading-image-while-page-loads/

[Improve] Use meta viewport

Use meta viewport tag to choose how your website will get scaled on smaller devices like phones.

What files to fix:
examples/basic.html
examples/basic_material.html
examples/basic_model.html
examples/fps.html
examples/plugin_example.html
examples/skybox.html
examples/stone_wall.html
or any new example *.html file

How To Do it:
Define at least

How to test it:

1. Install Vorlon.JS

2. add the following line into your test HTML file:

'< script src="http://localhost:1337/vorlon.js" >' '< /script >'

3. Once Vorlon.JS is done installing, run the server:

$ vorlon

4. With the server is running, open http://localhost:1337 in your browser to see the Vorlon.JS dashboard.

5. Open your test html file, and it should appear on the Vorlon.JS dashboard.

6. In the dashboard, click on the button Best Practice: MOBILE WEB
   and check the use meta viewport tag.

[Bug] Basic model example is broken

The basic model example is broken.

On run the following error occurs: Uncaught ReferenceError: opt is not defined

This is because of a slight mismatch in src/Objects/addModel.js.

An undeclared variable opt is referred to on line 20 and line 36.

Presumably, this should be referring to WHS.init.prototype.addModel's options parameter instead.

[Improve] Define platform icons

Platform icons helps user pinning your website with an icon that fits well on mobile device home.

What files to fix:
examples/basic.html
examples/basic_material.html
examples/basic_model.html
examples/fps.html
examples/plugin_example.html
examples/skybox.html
examples/stone_wall.html
or any new example *.html file

How To Do it:
add Apple - iOS icons by adding link tags like
'< link rel="apple-touch-icon-precomposed" href="youricon" sizes="57x57" />'

add Microsoft - Windows tiles by adding meta tags like
'< link name="msapplication-square150x150logo" content="yourimage" />'

How to test it:

1. Install Vorlon.JS

2. add the following line into your test HTML file:

'< script src="http://localhost:1337/vorlon.js" >' '< /script >'

3. Once Vorlon.JS is done installing, run the server:

$ vorlon

4. With the server is running, open http://localhost:1337 in your browser to see the Vorlon.JS dashboard.

5. Open your test html file, and it should appear on the Vorlon.JS dashboard.

6. In the dashboard, click on the button Best Practice: MOBILE WEB
   and check the define platform icons

[Bug] api.extend doesn't support deep objects.

It must be:

{
 a: {
  v:3,
  z:2
 }
}

[Improve] WHS.PointLight and WHS.SpotLight need to be updated.

There are some properties like exponent and decay that need to be applied to these lights.

[Bug] Cannon.js wireframe and three.js terrrain generation with vertexShader are different

I mean that our cannon.js terrain is generated by heightfield and have more points than it need.

How to solve: change heightfield size (make smaller) and use scale.
But the problem is that cannon.js objects don't support scaling.

Issue: schteppe/cannon.js#239

[Bug] MouseEvent Polyfill for browsers

Currently script won't work correctly because missed 1 thing:

if( !MouseEvent.prototype.hasOwnProperty('movementX') && // false
    !MouseEvent.prototype.hasOwnProperty('mozMovementX') ) { // true
 // Will be true

It checks for moz in chrome, and return false. Correct one:

if( !MouseEvent.prototype.hasOwnProperty('movementX') || // false
    !MouseEvent.prototype.hasOwnProperty('mozMovementX') ) { // true
 // Wll be false, because chrome allready support it.

[Engine] Physics change

Links:

• https://github.com/skeelogy/ifc-ar-flood
• http://cg.skeelogy.com/skunamijs/
• http://cg.skeelogy.com/skarfjs/
• http://cg.skeelogy.com/skulptjs/

Date: After new year.

[Improve] Update Three.js version (r74)

We need to update three.js dependencies. Latest revision is 74. Also it will solve problem #19

[Bug] Make WHS.Smooth to be infinite and WHS.Plane to be just ok

(Will write desc soon.)

[Improve] Update three.js version to r75

There is new version of threee.js out and we need update it. I'll create a new branch called three.js#75 and will work there.

[Bug] Autoresize bug

Width/height "100%" works inproperly.

[Improve] Fix JSDoc.

Whitestorm.js must provide jsdoc for each class or component.

For classes:

• es2015

[Improve] Should we use a CDN?

Should we use a CDN such as jsDelivr for hosting WhitestormJS?

I've dealt with jsDelivr before, and can easily add WhitestormJS to their services.

[Improve] Code style.

Guys, i have MANY troubles with my code style ;(
So i will be glad if somebody help me in developing engine.
Contributors sought!

All code in src folder. Compile with gulp build command.

You need:

• Contact me. [email protected]
• Edit code in src folder.
• Publish your change.
• Contact me again.

TODO:

• Line wrap.
• Prototypes fix.
• Restructurize libs.

[Improve] Improve libraries support.

I need to remove:

• this/scope.threejs -> THREE
• this/scope.cannonjs -> CANNON
• this/scope.wagnerjs -> WAGNER

[Improve] Incorrect use of prefixes

Ensure you use all vendor prefixes and unprefixed version for HTML5 CSS properties.

For more information see CSS3 animation Property

What files to fix:
examples/basic.html
examples/basic_material.html
examples/basic_model.html
examples/fps.html
examples/plugin_example.html
examples/skybox.html
examples/stone_wall.html
or any new example *.html file

How To Do it:
For an example, a test with Vorlon.JS will show what is missing and need to be added to:
inline
#animation
animation : missing -webkit-animation

How to test it:

1. Install Vorlon.JS

2. add the following line into your test HTML file:

'< script src="http://localhost:1337/vorlon.js" >' '< /script >'

3. Once Vorlon.JS is done installing, run the server:

$ vorlon

4. With the server is running, open http://localhost:1337 in your browser to see the Vorlon.JS dashboard.

5. Open your test html file, and it should appear on the Vorlon.JS dashboard.

6. In the dashboard, click on the button * Best Practice: WEB STANDARDS*
   and check the incorrect use of prefixes

[Bug] improve Shadowmap: bias, acne..

New shadows are still unstable. We need to improve shadowmap.
I can't find right value for scope.visible.shadowBias property. Default for solving this problem is 0.05 But in my example it looks not so good.
Some posts, that i found about this problem:

• http://www.fabiensanglard.net/shadowmapping/index.php
• mrdoob/three.js#6420
• mrdoob/three.js#7359
• mrdoob/three.js#5554

What i also found is: https://searchcode.com/codesearch/view/9474428/ - this can help me to write shadowmap without modifying threejs object vertices.

[Bug] Readme badges don't work

Here is what i see:

[Bug] Broken example link on website; broken examples

Hi,

I have some problems on http://whitestormjs.xyz/.

The link to the bottom right example is broken:
http://192.241.128.187/current/examples/basic_object.html
and the link top right gives me this error message on the console:
"Uncaught TypeError: api.construct is not a function"

Best,
Dirk

[Bug] FPS Example not working in Safari

[Improve] api.construct and basic shapes to es6 classes.

Links:

• https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Classes#Class_declarations
• http://javascriptplayground.com/blog/2014/07/introduction-to-es6-classes-tutorial/

[Bug] Build 117 (0594835) fails on travis-ci

I changed quotes to new ones (`) and now travis-ci throws new js parse error.
MDN about quotes
gulp build throws same error.

Result of 0594835.

[Improve] Add more tests

When I set up our test script, I just added a couple of tests; all these do is make sure that there are no syntax errors in the compiled output.

Tests are run by Mocha.

Here's an example of a more comprehensive test suite.

[Bug] Everything breaks in < Chrome 45 due to use of Object.assign

As the title states, due to the use of ES6 feature Object.assign here and here it becomes impossible to use WhitestormJS in any version of Chrome under 45.

Browser compatibility.

We can fix this by including this polyfill.

[Improve] Change terrain generation.

I love this example of @mrdoob and i will change my terrain generation script.

EDIT

Terrain moved to a component

[Improve] Material Options needs "wrap"

Write function that wraps material from options into THREE.js material.

[Bug] Babel adds "use strict"; code doesn't work!

Console logs:

whitestorm.js:1225 Uncaught TypeError: Cannot set property 'SimpleWorker' of undefined
game.js:5 Uncaught TypeError: Cannot read property 'init' of undefined

[Fix] Clean unused uniforms in terrain shader

Now uniforms looks like:

            "enableDiffuse1"  : { type: "i", value: 0 },
            "enableDiffuse2"  : { type: "i", value: 0 },
            "enableSpecular"  : { type: "i", value: 0 },
            "enableReflection": { type: "i", value: 0 },

            "tDiffuse1"    : { type: "t", value: null },
            "tDiffuse2"    : { type: "t", value: null },
            "tDetail"      : { type: "t", value: null },
            "tNormal"      : { type: "t", value: null },
            "tSpecular"    : { type: "t", value: null },
            "tDisplacement": { type: "t", value: null },

            "uNormalScale": { type: "f", value: 1.0 },

            "uDisplacementBias": { type: "f", value: 0.0 },
            "uDisplacementScale": { type: "f", value: 1.0 },

            "diffuse": { type: "c", value: new THREE.Color( 0xeeeeee ) },
            "specular": { type: "c", value: new THREE.Color( 0x111111 ) },
            "shininess": { type: "f", value: 30 },
            "opacity": { type: "f", value: 1 },

            "uRepeatBase"    : { type: "v2", value: new THREE.Vector2( 1, 1 ) },
            "uRepeatOverlay" : { type: "v2", value: new THREE.Vector2( 1, 1 ) },

            "uOffset" : { type: "v2", value: new THREE.Vector2( 0, 0 ) }

We have some unused ones in code. We need to remove them.

[Improve] Update Core.js with es6 features and fix code style.

Just made a brief review of Core.js file, and noticed that we use too much code in one function, we need to make it more simple and understandable for developers who want to look in code.

ES6 features to use: https://github.com/lukehoban/es6features

[Bug] WHS.Ring and WHS.Torus are similar objects.

Now WHS.Ring and WHS.Torus are same objects, but we need to make them different. Because ring is a 2D shape, and Torus is 3D.

[Bug] Adding AmbientLight to scene breaks the build

GAME.ambient_light = GAME.AmbientLight {
    light: { color: 0x080808 }
}

Throws:
Uncaught TypeError: Cannot read property 'mapSize' of undefined

[Bug] FOG doesn't work

Fog doesn't work on FPS example.
Need to improve shader in src/GROUND/addGround.js

UPDATE

src/Components/Fog.js

[Improve] Commit messages

Slang.

• WIP -> Work in progress.
• CSF -> Code style fix.
• README -> Readme.md update. (license, ... - the same).

[Improve] Use responsive approaches

Even if your website target only certain devices, you may have users with unexpected devices or screen ratio.

For more information see Responsive Web Design

What files to fix:
examples/basic.html
examples/basic_material.html
examples/basic_model.html
examples/fps.html
examples/plugin_example.html
examples/skybox.html
examples/stone_wall.html
or any new example *.html file

How To Do it:
Check if your css (either files or inline) use any media queries.
Check if your link tags use any media queries.

How to test it:

1. Install Vorlon.JS

2. add the following line into your test HTML file:

'< script src="http://localhost:1337/vorlon.js" >' '< /script >'

3. Once Vorlon.JS is done installing, run the server:

$ vorlon

4. With the server is running, open http://localhost:1337 in your browser to see the Vorlon.JS dashboard.

5. Open your test html file, and it should appear on the Vorlon.JS dashboard.

6. In the dashboard, click on the button Best Practice: MOBILE WEB and check the
   use responsive approaches

Add WebWorkers

Let's add WebWorkers, because preloading animation stops when javascript makes calculations.

Issue: https://github.com/WhitestormJS/whs.preload/issues/1

Stackoverflow: http://stackoverflow.com/questions/7300632/how-to-keep-animated-gif-running-while-doing-intense-calculations

[Bug] Grass doesn't work

WHS.init.prototype.addGrass needs height values.

Breaks at line 52.