Spritoon | Documentation

Actor

An Actor is the root element to a sprite animation using a hierarchy of sprites. It can be moved around by setting the x, y, rotation and scale values and can be flipped horizontally It can automatically moved by setting the motion value. Motion can define x, y, rotation and scale values these are the amount they will change by in 1 second Motion values are in th coordinate system of the root element before scaling An Actor contains layers which are individual sprites in a hierarchy

new Actor(spriteData: Object, frames: Object, image: Image)

Parameters

spriteData (Object) json returned from the spritoon app that describes the nodes and hierarchy of a multi-layered sprite

frames (Object) json for spritesheet that describes the positioning of the individual images

image (Image) the actual image described by the frames json

Example

//this.spriteData is the data downloaded from the Spritoon online app niklever.com/spritoon
let actor = new Actor(this.spriteData.sprites[i], this.spriteData.frames, this.spriteImage);
*

Instance Members

▸ selectAction(indexOrName, motion)

Choose an action from the action list passed in to the Actor constructor. Choose by index or by name

selectAction(indexOrName: string, motion: Object)

Parameters

indexOrName (string) if this value is a string then it is the name of an action in the actions array

motion

(Object
            = null)

(optional) is a object {x:0, y:0} where x and y describe the distance in pixels to travel in one second. *

▸ update(dt)

Call to update the Actor if it has an Action selected

update(dt: number)

Parameters

dt (number) time in seconds since last update *

▸ render(context)

Call to paint this actor to the context passed in

render(context: Object)

Parameters

context (Object) a 2d context for a html canvas *

Action

An Action defines the motion of sprite layers in an Actor

new Action(name: string, sprites: array)

Parameters

name (string) name for this Action

sprites (array) an array of sprites being controlled by this Action *

Key

A channel in an Action is a series of Keys that are attached to sprite. They are used to manipulate the image, x, y, scale, rotation, opacity. After Key one the easing value is used to control the motion

new Key(time: number, value: number, easing: string)

Parameters

time (number) The time that we want this key to occur

value (number) the value to be at at this time

easing

(string
            = "linear")

(optional defaults to linear) see Easing for more details *

Anim

Used to create a frame animation for a multi-framed sprite

new Anim(name: string, options: object)

Parameters

name (string) the name of the animation

options (object) an option object that describes the animation.

Example

let options = {
name: "test",
fps: 25, //default is 30 frames per second if not provided
frames: [1,"..",10], //See the parseFrames method for more information
loop: false, //defaults to true if omitted
motion: {x:100, y:-50}, // defaults to 0,0 if omitted
oncomplete: function(){ console.log('animation completed')}, //Called at animation end, called repeatedly for looping animation
}
*

Instance Members

▸ parseFrames(frames)

[0,"..",12,"s",0,"..",5]]
".." means count up from current index to value indicated by next element in the array
"r.." means count down from current index to value indicated by next element in the array
"..2" means count up in twos from current index to value indicated by next element in the array
"r..2" means count down in twos from current index to value indicated by next element in the array
"hXXX" means hold the previous index for the number of seconds specified by XXX
"s" means loop start - or 0 if not specified
This method is used by the frames parameter of the options object passed to the constructors *

parseFrames(frames: any)

Parameters

frames (any)

▸ reset()

resets the time for this animation to zero and unpauses a paused animation. *

reset()

▸ update(dt)

Call to update an animation called by the AnimSprite if this Anim is attached to a sprite

update(dt: number)

Parameters

dt

(number
            = 0)

(optional) updates the currentTime for an animation *

AnimSprite

A class to handle sprites with frame animations

new AnimSprite(name: string, options: object)

Parameters

name (string) for this sprite

options (object) an options object that passes in the necessary parameters to create the sprite

Example

const options = {
context: context,//A canvas 2d context
image: image,//a sprite sheet
x: 100,
y: 100,
anchor: {0.5, 0.9}, //pivot point halfway across and near bottom of frame from spritesheet
scale: 0.5, //(optional) defaults to 1
opacity: 0.5, //(optional) defaults to 1
rotation: 0.1, //(optional) defaults to 0
backgroundPosition: null, //(optional) defaults to 0,0 allows offset relative to a background location
physicsBody: null, //(optional) defaults to null  expects a Matter.Bodies object
anims: anims, //An array of animations probably created using the Spritoon online app
}
let sprite = new AnimSprite('sprite', options);
*

Instance Members

▸ anim

setter to set the animation it can be a name or a Anim object *

anim

Parameters

value (any)

▸ anim

anim

Returns

object: the current animation *

▸ getAnimNamed(name, a)

getAnimNamed(name: any, a: string): object

Parameters

name (any)

a (string) name that matches an Anim name from the anims array

Returns

object: an animation from the anims array *

▸ animName

animName

Returns

string: the current animation name or none if none set *

▸ moving

moving

Returns

boolean: is the AnimSprite moving *

▸ pauseAnim(secs, hide)

Pauses the current animation for a defined length

pauseAnim(secs: number, hide: boolean)

Parameters

secs (number) the number of seconds to pause the animation

hide

(boolean
            = true)

(optional - defaults to true) hides this sprite while animation is paused *

▸ update(dt)

Call to update the sprite and it's attached animation

update(dt: number)

Parameters

dt (number) time in seconds since last update *

▸ boundingBox

boundingBox

Returns

Rect: a rectangle x,y,w,h that encases the sprite *

▸ hitTest(pt)

hitTest(pt: object): boolean

Parameters

pt (object) a pt x,y that is being tested, often a mouse or touch location

Returns

boolean: true if the pt is inside the bounding box *

▸ render()

Call to render this sprite to the context passed to the constructor *

render()

Sprite

A Sprite is an individual image from the spritesheet

new Sprite(name: any, options: object)

Parameters

name (any)

options (object) an object that describes this sprite

Example

const options{
name: "test",
x: 100,
y: 100,
game: null, //(optional) The game that this sprite is attached to usual in this.sprites array
frameData: frameData, // The frames array from a json file - not used if game is set
image: image, //Spritesheet image - not used if game is set
context: context,
center: null, //if defined it overrides the x,y values and centres the sprite in the game canvas only used if game is defined
frame: "sprite{04}.png", //will replace {04} with index padded to 4 zeroes, {03} would pad to 3 zeroes
index: 1, //The index for the frame image
anchor: {x:0.5, y:0.9}, //(optional - defaults to 0.5,0.5) rotation and scaling center as a ratio of the width and height
scale: 0.5, //(optional - defaults to 1)
opacity: 0.6, //(optional - defaults to 1)
rotation: 0, //in radians
zOrder: 0, (optional - defaults to 0) higher numbers appear infront of lower numbers
// node: used when a sprite node is created by an Actor. 
// config: used when a sprite node is created by an Actor
// parent: used when a sprite node is created by an Actor
// children: used when a sprite node is created by an Actor
}
*

Instance Members

▸ index

index

Parameters

value (any)

null-null (number) sets the frame based on the frame name and this index value *

▸ hitTest(pt)

hitTest(pt: number): boolean

Parameters

pt (number) position x, y to test

Returns

boolean: returns true if pt is in the bounding box for this sprite *

▸ update(dt)

Before a sprite can be displayed update MUST be called

update(dt: number)

Parameters

dt (number) time since last update *

▸ setRest(restore)

$param {boolean} restore (optional defaults to true) used for an Actor to define the rest position from which an action happens. If restore is true then the rest position is reset, if restore is false then the current position, rotation, scale and opacity is saved to the rest object. *

setRest(restore: any)

Parameters

restore

(any
            = true)

▸ render(context, flipped)

renders this sprite to the canvas context

render(context: object, flipped: boolean)

Parameters

context

(object
            = this.context)

(optional context passed to constructor used if missed)

flipped

(boolean
            = false)

(optional defaults to false) *

Vertex

A Vertex is a simple definition that holds an x and y value and allows you to add and subtract Vertices

new Vertex(x: number, y: number)

Parameters

x (number)

y (number) *

Instance Members

▸ add(v)

add another Vertex

add(v: Vertex)

Parameters

v (Vertex) another Vertex *

▸ sub(v)

subtract another Vertex

sub(v: Vertex)

Parameters

v (Vertex) another Vertex *

▸ normalize()

Treat this Vertex as a vector of length 1 *

normalize()

▸ mag

mag

Returns

any: length of this Vertex as though it is a vector *

▸ distanceTo(b)

distanceTo(b: Vertex): number

Parameters

b (Vertex) another Vertex

Returns

number: the distance to Vertex passed in *

Rect

A simple class to define a Rectangle

new Rect(x: number, y: number, w: number, h: number)

Parameters

x

(number
            = 0)

x position

y

(number
            = 0)

y position

w

(number
            = 0)

width

h

(number
            = 0)

height *

Instance Members

▸ left

left

Returns

number: the position of the left edge *

▸ left

left

Parameters

value (any)

sets (number) the position of the left edge *

▸ right

right

Returns

number: the position of the right edge *

▸ right

right

Parameters

value (any)

sets (number) the position of the right edge *

▸ top

top

Returns

number: the position of the top edge *

▸ top

top

Parameters

value (any)

sets (number) the position of the top edge *

▸ bottom

bottom

Returns

number: the position of the bottom edge *

▸ bottom

bottom

Parameters

value (any)

sets (number) the position of the bottom edge *

▸ width

width

Returns

number: the width of the rectangle *

▸ width

width

Parameters

value (any)

sets (number) the width of the rectangle *

▸ height

height

Returns

number: the height of the rectangle *

▸ height

height

Parameters

value (any)

sets (number) the height of the rectangle *

▸ inRect(pt)

inRect(pt: object): boolean

Parameters

pt (object) position x, y

Returns

boolean: true if pt is inside the rectangle *

▸ overlaps(r)

overlaps(r: Rect): boolean

Parameters

r (Rect) another Rect

Returns

boolean: true of Rect r overlaps with this Rect *

Matrix

Simple 2d matrix class used when updating sprites that have parents
[a,c,e]
[b,d,f]
[0,0,1]

new Matrix(a: number, b: number, c: number, d: number, e: number, f: number)

Parameters

a

(number
            = 1)

b

(number
            = 0)

c

(number
            = 0)

d

(number
            = 1)

e

(number
            = 0)

f

(number
            = 0)

*

Instance Members

▸ reset(a, b, c, d, e, f)

If the parameters are not provided then the matrix becomes the identity

reset(a: number, b: number, c: number, d: number, e: number, f: number)

Parameters

a

(number
            = 1)

b

(number
            = 0)

c

(number
            = 0)

d

(number
            = 1)

e

(number
            = 0)

f

(number
            = 0)

*

▸ copy(m)

Copies the passed in Matrix to this one

copy(m: Matrix)

Parameters

m (Matrix) *

▸ plus(m)

Adds the passed in Matrix to this one

plus(m: Matrix)

Parameters

m (Matrix) *

▸ minus(m)

Subtracts the passed in Matrix from this one

minus(m: Matrix)

Parameters

m (Matrix) *

▸ mult(m)

Multiply this matrix with the passed in Matrix

mult(m: Matrix)

Parameters

m (Matrix) *

Easing

Class to handle easing functions. Based on Robert Penner's code.

new Easing(start: number, end: number, duration: number, startTime: number, type: number)

Parameters

start (number) the value at the start of an easing

end (number) the value to change to.

duration (number) the time to elapse in seconds

startTime

(number
            = 0)

(optional defaults to 0) pass in Date.now()/1000 if you want times to be relative to now

type

(number
            = 'linear')

(optional defaults to linear) *

Instance Members

▸ value(time)

value(time: number): number

Parameters

time (number) time from startTime

Returns

number: value between start and end based on the easing method *

▸ linear()

easing method that has the same increment throughout the duration, called by value do not call directly *

linear()

▸ inQuad()

easing method that has a slow start, called by value do not call directly *

inQuad()

▸ outQuad()

easing method that has a slow stop, called by value do not call directly *

outQuad()

▸ inOutQuad()

easing method that has a slow start and slow end, called by value do not call directly *

inOutQuad()

▸ inCubic()

easing method that has a slow start, called by value do not call directly *

inCubic()

▸ outCubic()

easing method that has a slow stop, called by value do not call directly *

outCubic()

▸ inOutCubic()

easing method that has a slow start and slow end, called by value do not call directly *

inOutCubic()

▸ inQuart()

easing method that has a slow start, called by value do not call directly *

inQuart()

▸ outQuart()

easing method that has a slow stop, called by value do not call directly *

outQuart()

▸ inOutQuart()

easing method that has a slow start and slow end, called by value do not call directly *

inOutQuart()

▸ inQuint()

easing method that has a slow start, called by value do not call directly *

inQuint()

▸ outQuint()

easing method that has a slow stop, called by value do not call directly *

outQuint()

▸ inOutQuint()

easing method that has a slow start and slow end, called by value do not call directly *

inOutQuint()

▸ inSine()

easing method that has a slow start, called by value do not call directly *

inSine()

▸ outSine()

easing method that has a slow stop, called by value do not call directly *

outSine()

▸ inOutSine()

easing method that has a slow start and slow end, called by value do not call directly *

inOutSine()

▸ inExpo()

easing method that has a slow start, called by value do not call directly *

inExpo()

▸ outExpo()

easing method that has a slow stop, called by value do not call directly *

outExpo()

▸ inOutExpo()

easing method that has a slow start and slow end, called by value do not call directly *

inOutExpo()

▸ inCirc()

easing method that has a slow start, called by value do not call directly *

inCirc()

▸ outCirc()

easing method that has a slow stop, called by value do not call directly *

outCirc()

▸ inOutCirc()

easing method that has a slow start and slow end, called by value do not call directly *

inOutCirc()

▸ inElastic()

easing method that has a slow start, called by value do not call directly *

inElastic()

▸ outElastic()

easing method that has a slow stop, called by value do not call directly *

outElastic()

▸ inOutElastic()

easing method that has a slow start and slow end, called by value do not call directly *

inOutElastic()

▸ inBack()

easing method that has a slow start, called by value do not call directly *

inBack()

▸ outBack()

easing method that has a slow stop, called by value do not call directly *

outBack()

▸ inOutBack()

easing method that has a slow start and slow end, called by value do not call directly *

inOutBack()

▸ inBounce(t, b)

easing method that has a slow start, called by value do not call directly *

inBounce(t: any, b: any)

Parameters

t

(any
            = this.t)

b

(any
            = this.b)

▸ outBounce(t, b)

easing method that has a slow stop, called by value do not call directly *

outBounce(t: any, b: any)

Parameters

t

(any
            = this.t)

b

(any
            = this.b)

▸ inOutBounce()

easing method that has a slow start and slow end, called by value do not call directly *

inOutBounce()

TextBlock

Paints text inside a bounding rectangle, if autorender is not passed to the options object then it will be rendered to the canvas immediately

new TextBlock(context: object, text: string, rect: Rect, options: object)

Parameters

context (object) a canvas 2d context

text (string) the text to draw

rect (Rect) a rectangle that defines the bounding shape of the text

options

(object
            = {})

an options object that describes the color, alignment, lineHeight, fontSize and font of the text

Example

const options = {
font = "Verdana",
fontSize = 30,
lineHeight = 35,
color = "#ff00aa",
alignment = 'center'
}
const txt = new TextBlock(context, "This is the text to draw\nThis will be on a second line.", new Rect(100,100,200,80), options)
*

Instance Members

▸ render()

renders the TextBlock to the context *

render()

Emitter

Used by a particle effect

new Emitter(options: object)

Parameters

options (object) can contain the following
emissionRate - number of particles to emit per second - defaults to 33
particleCount - the number of particles that the emitter controls - defaults to 100
position - x,y position relative to the top left of the canvas - defaults to 0,0 life - the life time duration of the emitter in seconds - defaults to 3 speed - the distance a particle should move in each screen refresh - defaults to 10 speedVariation - the difference in speed for each particle - defaults to 0.6 angle - the angle of the particle emission in degrees 0 is left, 90 is down, 180 is right and 270 is up angleVariation - the amount of variation from angle that is allowed as a ratio 0-1 - defaults to 1 particleLife - the life time duration of a particle in seconds scaleWithAge - when rendering does the particle size scale up as it goes through its life time - defaults to true additive - should the globalCompositeOperation be 'lighter' - defaults to false canvasOffset - is the emitter relative to an offset position - defaults to 0,0 opacity - the opacity of a particle - defaults to 1 scale - the scale of a particle - defaults to 1 rotation - the angle of a particle - defaults to 0 spin - the angular speed of a particle - defaults to 0 gravity - the gravity applied to a particle - defaults to 0 image - the spritesheet image to use for a bitmap particle json - the json that describes the spritesheet image index - the index into the json that should be used for a particle *

Instance Members

▸ update(dt)

Call to update the particles

update(dt: number)

Parameters

dt (number) time since last refresh *

▸ render(context)

Call to render the particle effect to the context

render(context: object)

Parameters

context (object) a canvas 2d context *

Particle

A simple class to use with an Emitter. Probably not used directly.

new Particle(options: object)

Parameters

options (object) An options object containing the parameters for the particle, see Emitter for details *

Preloader

A class to handle preloading assets

new Preloader(options: object)

Parameters

options (object) An options object that defines the assets and callbacks for onprogress and oncomplete

Example

Button

A class to handle a button

new Button(options: object)

Parameters

options

(object
            = {})

an options object to handle the button
{string} text - the text on this button - defaults to no text {string} font - the font to use - defaults to Verdana {Rect} rect - A Rect that gives the position and size of the Button in canvas coordinates {string} color - the color of the text in css style eg #ffffff would be white {string} background - the color of the background in css style eg #ffffff would be white {number} fontSize - the size of the font in pixels {function} onClick - the code to run when a click occurs *

Instance Members

▸ hitTest(mousePos)

hitTest(mousePos: object): boolean

Parameters

mousePos (object) the x,y position of a click

Returns

boolean: true if in the rectangle of this button *

▸ render(context)

Paints the button to the context

render(context: object)

Parameters

context (object) a canvas 2d context *

SFX

A simple class to handle sound effects and music loops in games

new SFX(options: object)

Parameters

options (object) an options object to handle initialising the class
{object} context - an AudioContext object
{number} volume - a number 0-1 to control the volume - default 1
{boolean} loop - does this sfx loop - default false
{number} fadeDuration - a number that controls the change in volume speed - default 0.5
{boolean} autoPlay - should this sound start automatically on load *

Static Members

▸ supportsVideoType(type)

Does the browser support the sound type

supportsVideoType(type: string)

Parameters

type (string) eg. mp3 or webm *

Instance Members

▸ loop

Setter to set the loop value

loop

Parameters

value (boolean) *

▸ play()

Plays the sound effect *

play()

▸ volume

Setter to set the volume

volume

Parameters

value (number) number between 0 and 1 *

▸ pause()

Pause the playing sound *

pause()

▸ stop()

Stop the playing sound *

stop()