Sprite3D.js


a small library for generating 
and manipulating CSS 3D transforms


NOTICE:


This page is slowly getting outdated. In my spare time, I've been working on a major syntax revision, Firefox compatibility issues and a new version of this page.

Until I get the time to finish all of this, here's a list of the most up to date resources :


"v2" branch on github (featuring a simplified syntax)

A more recent list of examples

Follow me on Twitter for update notices.
 



Overview

Features

Examples

Download

Documentation
 

Overview



Sprite3D wraps HTML elements with the necessary behaviours to easily control their 3D-position using a simple Javascript syntax. To create a Sprite object, you can either supply an existing DOM object or let the library create an empty <div> (you can apply a CSS class to the DOM element after its creation).

As you manipulate "real" HTML elements, you don't need a <canvas> object (and its performance problems), nor a WebGL-enabled browser. And, as 3D transforms are hardware-accelerated, you can get a very decent framerate, even on mobile devices.

3D positionning is achieved via CSS3 3D transforms, which are currently supported by WebKit (Chrome, Safari, iOS, Android 4, BlackBerry) and Firefox 10. Internet Explorer 10 should ship with 3D support, too.

However, due to its wrapping, non-intrusive nature, Sprite3D.js allows for building semantically valid HTML pages, adding the animation layer afterwards, achieving a valuable progressive enhancement effect.

Sprite3D.js has no dependencies, so it can easily be integrated with other JS libs. 
It is provided under the MIT Licence. 

Main Features



AS3-style properties : 
 x, y, z
 rotationX, rotationY, rotationZ
 scaleX, scaleY, scaleZ
 width, height
 alpha


Lots of accessor methods : 
 setPosition(x,y,z) setX(x) setY(y) setZ(z) 
 move(x,y,z) moveX(x) moveY(y) moveZ(z) 
 setRotation(x,y,z) setRotationX(x) setRotationY(y) setRotationZ(z)
 rotate(x,y,z) rotateX(x) rotateY(y) rotateZ(z)
 setScale(x,y,z) setScaleX(x) setScaleY(y) setScaleZ(z)


AS3-style scenography via the addChild() and removeChild() method, children inheriting of their parent's transformations

JS-style method chaining :  
new Sprite3D()
 .setPosition(x,y,z)
 .setRotation(rx,ry,rz)
 .setClassName('class')
 .update();


Basic support for sprite sheets. At this point, all the tiles must have the same size (for one Sprite).
/* CSS : */
.spriteClass {
 background: url("img/sheet.png");
 width: 32px;
 height: 64px;
}

/* JS : */
// one-time set-up :
mySprite.setClassName("spriteClass").setTileSize( 32, 64 );
// then, later :
mySprite.setTilePosition( 0, 3 );
 

Easily manipulate the underlying DOM elements with the domElement and style properties. There's also a bunch of helper methods like setClassName, getClassName, addClassName, removeClassName, setId, getId, setCSS, getCSS and setInnerHTML that let you keep your CSS workflow

Check for browser support using the Sprite3D.isSupported() method
 

Examples


I'm so sorry !
It seems that your browser does not support CSS 3D transforms. 
Please try to view those examples with a recent webkit-based browser, like ChromeorSafari, or you might get strange results...


Hello World

 
Basic example, showing how to create a root container, add a single Sprite3D object, apply a CSS class and x-axis rotation.
 

Hello World 3D

 
A more advanced version of the first example. A simple 3D object is create using four faces, then animated using its container's 3D rotation methods.
 

Particles (kind of)

 
Two containers, some png's, some more pure CSS divs, and rotations all the way.
 

Tweening example

 
Showing how to tween positions and rotations using TweenJS.
 

Events example

 
This might be the base for a simple point-and-touch game for the iPad.
For the Nyan-haters out there, here's a JESUS version.
 

Flower

 
A bit of recursive hierarchy, CSS classes and a simple rotation. That's all it takes to build a flower. The flower parameters are slightly randomized. It mutates randomly when hovered or touched.
 

3D image gallery

 
A classic use of 3D positionning for a spatial image gallery.
 

Canvas demo

 
Combine the ease of 3D positionning with Sprite3D.js and the pleasure of generating graphics using HTML's canvas for even more fun !
 

Sprite Harrier

 
Porting your favorites old school games to HTML 5 is just a no-brainer with Sprite3D.js (just kidding). Chrome has some rendering problems with this one, but [Mobile] Safari doesn't care.
 

Sliding 15 Puzzle

 
Quick prototype for a classic game. 
Update: now fully working, no more dead-ends.
 

OLO Game

 
London-based studio Sennep created a full featured iOS game with HTML5 technologies and Sprite3D. The result is a free touch game that you can install on your device and that's just what Sprite3D was created for.
 

Butterflies

 
Three div's, two png's, a bit of animation. Repeat ten times, add some touch control. 
Demo video here if your browser can't take it.
 

Current dev status


See the above notice.

Download


Get the full project source code on GitHub.

Don't forget to check the "v2" branch with its revamped syntax.

Documentation


The source code has been commented using the jsDoc syntax. Here is the generated reference page (which is also included in the github package).

Credits


Sprite3D.js has been created by boblemarin (@)

Thanks to Grant Skinner's TweenJS, MrDoob's Stats utility, Paul Irish's requestAnimationFrame code, Shane Becker and Daniel Rench for the house cleaning on github, Pixeline and Kooka for their support, and Christian Delfosse for fixing the 15 Puzzle stuff. 

Social stuff


Tweet