W

Commented, full
(23kb) Minified, full
(8.1kb, 2.6kb zipped) Minified, lite
(5.8kb, 2.0kb zipped)
_{No built-in models or smooth shading}

or load it in HTML:

<script src=//xem.github.io/W/dist/w1.0.full.min.js></script>

// Start the framework
W.reset(canvasElement);

// Set clear color ("#fff" by default)
W.clearColor("#rgb");

// Set camera
// Settings: position (x, y, z), angle (rx, ry, rz), fov
W.camera({x, y, z, rx, ry, rz, fov});

// Set light direction
W.light({x, y, z});

// Set ambient light's force (between 0 and 1)
W.ambient(f);

// Create a group of objects: name, position, rotation
W.group({n, x, y, z, rx, ry, rz});

// Draw a built-in 3D object
// Settings: group, name, size, position, rotation, background, texture, smooth...
let settings = {g, n, size, x, y, z, rx, ry, rz, b, t, mix, s, ns, mode};
W.plane(settings);
W.billboard(settings);
W.cube(settings);
W.pyramid(settings);
W.sphere(settings);

// Add and draw a custom 3D model (see the OBJ file loader below)
W.add("custom_model", { vertices, uv, indices });
W.custom_model(settings);

// Move/resize a group or object: name, position, rotation, animation, delay (in ms)
W.move({n, size, x, y, z, rx, ry, rz, a}, delay);

// You can also use M to set a custom transformation matrix
W.move({n, M}, delay);

// Move camera / light: settings, animation, delay
W.camera({x, y, z, rx, ry, rz, a}, delay);
W.light({x, y, z, a}, delay);

// Delete an element: name, delay
W.delete(n, delay);

1) Setup
First, create a HTML5 canvas

<canvas id=canvasElement>

and call

W.reset(canvasElement)

.
By default, the camera is placed at [0,0,0], looking at the -Z axis, with a 30 degrees FoV.
The scene contains an ambient light and a directional light pointing to the bottom: [0, -1, 0].
You can set the camera's position, rotation and FoV using

W.camera({x, y, z, rx, ry, rz, fov})

.
You can set the directional light using

W.light({x, y, z})

and the ambient light leved using

W.ambient(n)

.
You can change the background color using

W.clearColor(c)

(where c is a hex RGB/RGBA string).
No need to start a render loop, the canvas is redrawn after each screen refresh.


2) Draw built-in 3D models
The full version of the framework includes 5 built-in shapes:

W.plane

,

W.billboard

,

W.cube

,

W.pyramid

and

W.sphere

.
(Billboards are planes that always face the camera, and can be used to show sprites or particles for example.)
The shapes settings can contain the following values:

{g, n, size, w, h, d, x, y, z, rx, ry, rz, b, t, mix, s, mode}

• n: name (required if you want to transform the object later)
• g: parent group (if a group is set, the model will be transformed relatively to this group)
• w, h, d or size (size sets w, h and d to the same value. Otherwise, w, h and d can be set individually. Default: 1)
• x, y, z: position (default: 0, 0, 0)
• rx, ry, rz: rotation (default: 0, 0, 0)
• b: background color (a "#rgb" or "#rgba" hex value. The "#" is optional. Default: "888")
• t: background texture (an IMG, CANVAS or VIDEO element present in the DOM)
• mix: if both b and t are set, a mix value between 0 and 1 can be used to mix the color and texture (0: fully textured, 1: fully colored)
• s: enable smooth shading (requires the full version of the framework. Default: false)
• mode: drawing mode ("LINE_LOOP", "TRIANGLES", etc. Default: "TRIANGLES")
• M: custom transformation matrix (Array(16), replaces x, y, z, rx, ry, rz)
• ns: by default, the shape will be shaded according to the directional light, but it can be disabled with this "no shading" option

Groups can be created using

W.group({n, x, y, z, rx, ry, rz})

(or

W.group({n, M})

) and can be nested.

Edit on Codepen

3) Draw custom 3D models
Besides the built-in shapes, W can also import and display custom 3D models.
You'll need:

• An array of vertices coordinates: [x, y, z, x, y, z, ...],
• Optionally: an array of uv texture coordinates: [u, v, u, v, ...] (if the model is textured),
• Optionally: an array of indices (if the model uses indexed buffers). W.js supports both indexed and unindexed models!
• Optionally: an array of normals (if you don't want to use the built-in flat/smooth normals)

Add the new model using

W.add("custom_shape", {vertices, uv, indices})

and draw it using

W.custom_shape(settings)

.
Custom models can be drawn with the same settings as the built-in ones (group, size, position, rotation, background, shading...).
Flat shading is applied by default, smooth shading is only available in the full version of the framework.
OBJ files can be converted into W custom models using the following online tool: OBJ2JS!

Edit on Codepen


4) Transformations and animation
The groups and 3D shapes can be moved and transformed using

W.move({n, size, x, y, z, rx, ry, rz, b, t, a}, delay)

.
If a

delay

is provided, the transformation will be done after that delay in milliseconds. (0 by default)
If an

a

parameter is provided, the transformation will be animated. The animation will last for

a

milliseconds. (0 by default)

The camera can be moved and animated using

W.camera({x, y, z, rx, ry, rz, a}, delay)

.
The directional light can be moved and animated with

W.light({x, y, z, a}, delay)

.

Edit on Codepen


5) Advanced techniques

• You can set a custom projection matrix with

  W.projection=new DOMMatrix([...])

  .
  The example below shows how to use an orthographic projection.

Edit on Codepen

• You can set a custom transform matrix to any object with

  W.move({n, M:[...]})

  . (animation is not possible in that case)
  The example below shows how to perform asix-based rotations.

Edit on Codepen

• All the scene's objects can be used as a group and have other objects attached to it. The camera can also be put in a group.
• The camera itself can be used as a group (to create a HUD or a skybox), or put inside a group (to make a 1st or 3rd person view).
  The example below shows how to attach the camera to a moving character and attach a plane (the ground) to the camera.

Edit on Codepen

• Items can be attached or detached from a group anytime using

  W.move({g /* group / null */ })

  .

Edit on Codepen




Related projects and demos:

• Peach castle example by Xem
• Free rotation cube example by Xem and RandyTayler
• Haxe externs by Gogoprog + a 32kb shmup game.
• Modern JS version by Valerioageno