Sprite

To improve loading performance you usually put multiple images in the same image file, and then split it up in the code. This display object allows you to do that pretty easy. It also allows you to make an animation based on the frames in the image. It is a flexible object that lets you use it both as split still images and animations. It can generate the frames for you, based on a few parameters, or you can specify each frame manually.

Methods

start() (deprecated in version 2.0.0)
startAnimation() (since version 2.0.0)
stop() (removed in version 2.0.0)
stopAnimation() (since version 2.0.0)

Properties

active : Boolean: Determines whether or not the animation is running.
autostart : Boolean: Specifies if the animation should start automatically when the image is loaded. If this is false, you will need to use the method start() to start the animation.
direction : String: Specifies in which direction the autogeneration will create the frames. Can be either "x" or "y". Default: "x"
duration : Number: The number of milliseconds each frame in the animation should be shown. This property is only used if generate is set to true.
frame : Number: The current frame that will be drawn.
frames : Array: Contains all the frames in the sprite. This can be autogenerated by setting generate to true (see that property for more info) when creating the object. If it is manually specified, you need to know that every array item is an object, containing at least two properties, x and y which defines where in the sprite sheet the frame is. Optional properties are w and h for the width and height of the that frame. There can also be a d property, which is the duration for that frame in milliseconds, if the sprite is animating.
generate : Boolean: If this is set to true, the frames will be autogenerated based on the properties width, height, direction, offset_x and offset_y. Only the first two properties are required, the others have default values. Letting oCanvas generate the frames for you restricts it a bit, since all frames need to have the same size.
height : Number: The height each frame will have. This is used both if generate is set to true, and if the h property is missing when specifying the frames manually in the frames property.
image : String or HTMLImageElement: If a string is specified, it is interpreted as a path to the image. If it is an HTMLImageElement, it will use that image.
loaded : Boolean: Describes if the image has loaded yet.
loop : Boolean: If set to true, the animation will start from the beginning when the end is reached, thus creating a loop.
numFrames : Number (since version 2.0.0): Used when automatically generating frames with the generate property. With this property set, only that many frames will be generated.
offset_x : Number: An optional horizontal offset which will be used when generate is set to true. This can be used if your image file contains multiple sprite sheets combined into one.
offset_y : Number: An optional vertical offset which will be used when generate is set to true. This can be used if your image file contains multiple sprite sheets combined into one.
width : Number: The width each frame will have. This is used both if generate is set to true, and if the w property is missing when specifying the frames manually in the frames property.

Examples

Example 1

We start by creating a new core instance. Then we create an image object which will show the entire sprite sheet image. Then we create the actual sprite and specify that we want to generate the frames, based on the width, height and direction that we specify. We also specify that this object is going to show the first frame when drawn. Then we clone this sprite twice and change the position and frame number to show other frames. Now we have split up one image file into different objects in an easy way.

View Example

Code

var canvas = oCanvas.create({
	canvas: "#canvas"
});

var image = canvas.display.image({
	x: 177,
	y: 80,
	origin: { x: "center", y: "center" },
	image: "img/sprite.png"
});

var sprite_1 = canvas.display.sprite({
	x: 144,
	y: 137,
	image: "img/sprite.png",
	generate: true,
	width: 20,
	height: 20,
	direction: "x",
	frame: 1
});
var sprite_2 = sprite_1.clone({
	x: 167,
	frame: 2
});
var sprite_3 = sprite_1.clone({
	x: 190,
	frame: 3
});

canvas.addChild(image);
canvas.addChild(sprite_1);
canvas.addChild(sprite_2);
canvas.addChild(sprite_3);

Output

Example 2

We start by creating a new core instance. Then we create the actual sprite and specify that we want to generate the frames for the sprite animation, based on the width, height and direction that we specify. We also specify the duration for each frame. At the end, we start the sprite animation. If we would not run that start method, only the first frame would be drawn.

View Example

Code

var canvas = oCanvas.create({
	canvas: "#canvas"
});

var sprite = canvas.display.sprite({
	x: 177,
	y: 137,
	origin: { x: "center", y: "center" },
	image: "img/sprite.png",
	generate: true,
	width: 20,
	height: 20,
	direction: "x",
	duration: 60
});

canvas.addChild(sprite);

sprite.start();

Output

Example 3

We start by creating a new core instance. Then we create the actual sprite and specify the exact positions for the frames. We also specify that this object is going to show the first frame when drawn. Then we clone this sprite twice and change the position and frame number to show other frames. Now we have split up one image file into different objects in an easy way.

View Example

Code

var canvas = oCanvas.create({
	canvas: "#canvas"
});

var sprite_1 = canvas.display.sprite({
	x: 144,
	y: 137,
	image: "img/sprite.png",
	frames: [
		{ x: 0, y: 0 },
		{ x: 80, y: 0 },
		{ x: 140, y: 0 }
	],
	width: 20,
	height: 20,
	frame: 1
});

var sprite_2 = sprite_1.clone({
	x: 167,
	frame: 2
});
var sprite_3 = sprite_1.clone({
	x: 190,
	frame: 3
});

canvas.addChild(sprite_1);
canvas.addChild(sprite_2);
canvas.addChild(sprite_3);

setInterval(function() {
	canvas.redraw();
}, 1000 / 60);

Output