JP SpritePlayer

Library to easily play and control PNG sequences and sprite sheets

Working example creatives can be found on the downloads-examples page.

CDN:

• //cdn.justpremium.com/Justpremium/boilerplate/js/jp-spriteplayer_1.0.1.js

Installation

• Include a script tag in the bottom of the body of your html file:

<script src="//cdn.justpremium.com/Justpremium/boilerplate/js/jp-spriteplayer_1.0.1.js"></script>

API

JPSpritePlayer(configOptions)

Constructor to create a new JPSpritePlayer instance

Parameter	Definition
configOptions	configOptions object required

Properties for the config object:

property	value
targetElement	css selector of the target element required
classPrefix	class prefix from the spritesheet CSS file(s) required (for sprite sheet)
path	base path to PNG sequence images required (for PNG sequence)
fileExt	file extension of the PNG sequence files required (for PNG sequence)
numFrames	total number of frames required
startIndex	the index of the filename or css class the animtion starts from default:1
suffixDigits	minimum digits to make up the filename or css class default:2
indexIncrem	how many frames to jump in one increment default:1

Using a PNG sequence

The following snippet assumes 36 PNG images to be inside assets/frames/ and named 42083.0001.png, 42083.0002.png, 42083.0003.png etc.

PNG Sequence

var config = {
    targetElement:"#three-sixty", 
    path:"assets/frames/42083.00", 
    suffixDigits:2,
    numFrames:36, 
    fileExt:"png"
}
var spritePlayer = new JPSpritePlayer(config);

Using a single sprite sheet

Example sprite sheet CSS

.sprite-frame {overflow:hidden; background-repeat: no-repeat;background-image:url(sprite-sheet.png);}
.frame_000 {width:320px; height:640px; background-position: -0px -0px}
.frame_001 {width:320px; height:640px; background-position: -320px -0px}
.frame_002 {width:320px; height:640px; background-position: -640px -0px}
...

The following snippet assumes a single sprite sheet with CSS classes for 20 frames, in the format shown above.

Sprite sheet with a single sprite image

var config = {
    targetElement:"#sprite-player", 
    classPrefix: "sprite-frame frame_",
    suffixDigits:3,
    numFrames:20
}
var spritePlayer = new JPSpritePlayer(config);

Using multiple sprite sheets

There are limits to the image size a browser can efficiently handle. Sprite sheets should be less than 4096px wide or tall for desktop. For mobile keeping the image to under 2048px is recommended. If your animation requires more pixel real esate, you will need to split it across multiple image sheets.

Example sprite sheet CSS - first sheet

.sprite-1 {overflow:hidden; background-repeat: no-repeat;background-image:url(sprite_0-70.png);}

.Frames_00 {width:320px; height:640px; background-position: -0px -0px}
.Frames_01 {width:320px; height:640px; background-position: -320px -0px}
.Frames_02 {width:320px; height:640px; background-position: -640px -0px}

Example sprite sheet CSS - second sheet

.sprite-2 {overflow:hidden; background-repeat: no-repeat;background-image:url(sprite_71-117.png);}
.Frames_071 {width:320px; height:640px; background-position: -0px -0px}
.Frames_072 {width:320px; height:640px; background-position: -320px -0px}
.Frames_073 {width:320px; height:640px; background-position: -640px -0px}

The following snippet assumes two sprite sheets with CSS classes for 36 frames in the format shown above.

Sprite sheet with multiple sprite images

var config = {
    targetElement:"#sprite-player", 
    classPrefix:[{ index: "0", classPrefix: "sprite-1 Frames_" }, { index: "71", classPrefix: "sprite-2 Frames_" }],
    numFrames:142
}
var spritePlayer = new JPSpritePlayer(config);

play(direction, frameRate)

// play at 30 fps
spritePlayer.play(1, 30);
// play in reverse at 20 fps
spritePlayer.play(-1, 20);

pause()

spritePlayer.pause();

showFrame(index)

spritePlayer.showFrame(10);

setLoop(loop)

spritePlayer.setLoop(true);

setYoyo(yoyo)

spritePlayer.setYoyo(true);

on(evt)

spritePlayer.on("framechange", function(){
    console.log(spritePlayer.currentIndex);
});
spritePlayer.on("ended", function(){
    console.log("animation ended");
});

preRender(func, time, cssProperty)

Start your animation from the func callback to ensure is plays smoothly first time. Only relevant for multi-sheet setups.

spritePlayer.preRender(function() {
    spritePlayer.play();
});

JPSpritePlayer.UseTouchEvents

JPSpritePlayer.UseTouchEvents = false;

Override whether or not the carousel uses touch events or mouse events.

Responsiveness

Sprite sheet animations and PNG sequences normally need to be scaled with css transform to be responsive. Here is an example of how to do this:

var pseudoCss = {
    baseWidth:320, // width defined in the spritesheet css
    width:.9, // decimal percentage width for the sprite player
    maxWidth:300, // max width in pixels
    minWidth:100 // min width in pixels
}
spritePlayerEl.style.transformOrigin = "top left"; // could be set in the CSS
var resizeHandler = function(){
    var scale = spritePlayerEl.offsetParent.clientWidth/pseudoCss.baseWidth * pseudoCss.width;
    var minScale = pseudoCss.minWidth/pseudoCss.baseWidth;
    var maxScale = pseudoCss.maxWidth/pseudoCss.baseWidth;
    scale = Math.min(Math.max(scale, minScale), maxScale);
    spritePlayerEl.style.transform = "scale(" + scale + ")";
}
window.addEventListener("resize", resizeHandler);
document.addEventListener("DOMContentLoaded", resizeHandler)