vue-spritecore
A lightweight fully fledged Vuejs sprite-sheet animation render engine in a compact SFC plugin format
Table of contents
Installation
npm install --save vue-spritecore
Default import
Install for all the components (global registration):
Vue components: App template: '<App/>'
Use within a specific component (local registration):
Vue
Usage
Generate your spritesheet
spritesheet
: must be a valid image file (reccomended .png)json
: animation-data in JSON Array format
You can generate the spritesheet also through any of the following online tools:
Add the component
<vue-spritecore v-bind:id="'animation-id'" v-bind:spritesheet="require('./assets/spritesheet.png')" v-bind:json="require('./assets/animation-data/spritesheet-data.json')" v-bind:autoplay="true" v-bind:loop="true" v-on:ready="ready" ref="animation" ></vue-spritecore>
Wait for the animation to be ready then start animating
export default { name: 'app', mounted: function(){ }, methods: { ready: function(){ this.$refs.animation.play(); }, }}
Example
Props and methods syntax example
<template> <div id="app"> <vue-spritecore v-bind:id="'animation-id'" v-bind:spritesheet="require('./assets/spritesheet.png')" v-bind:json="require('./assets/animation-data/spritesheet-data.json')" v-bind:autoplay="true" frameSorting="asc" v-bind:scaleX="0.6" v-bind:scaleY="0.6" v-bind:loop="true" v-bind:lowerBound="0" v-bind:upperBound="100" v-on:ready="ready" v-on:animationStarted="animationStarted(...arguments)" v-on:animationStopped="animationStopped(...arguments)" v-on:animationReset="animationReset(...arguments)" v-on:animationOver="animationOver(...arguments)" ref="animation" ></vue-spritecore> </div></template> <script> export default { name: 'app', mounted: function(){ this.$refs.animation.play(); //play the animation from frame _lowerBound_ to _upperBound_ this.$refs.animation.play(5, 40); //play the animation from frame 5 to frame 40 this.$refs.animation.stop(); //stop(freeze) the animation this.$refs.animation.reset(); //reset the animation at frame _lowerBound_ this.$refs.animation.reset(10); //reset the animation at frame 10 this.$refs.animation.playLegacy(30); //play the animation through the legacy animator with constant framerate of 30 }, methods: { ready: function(){ console.log('animation ready'); }, animationStarted: function(startFrame, stopFrame){ console.log('animation started:['+startFrame+','+stopFrame+']'); }, animationStopped: function(frame){ console.log('animation stopped at frame: '+frame); }, animationReset: function(frame){ console.log('animation resetted at frame: '+frame); }, animationOver: function(frame){ console.log('animation over at frame:'+frame); }, }}</script>
Props
spritesheet
(required) : path to the animation sprite-sheetjson
(required): path to the json animation dataid
: render canvas idframeSorting
: frame sorting method when arranging the frames from the provided json. It determines the animation direction.scaleX
: animation scale on the x-axisscaleY
*: animation scale on the y-axisautoplay
: automatic animation playloop
: restart animation automatically at lowerBoundlowerBound
: global animation start frame cursorupperBound
: global animation end frame cursor
Name | Required | Type [ allowable params ] | Default |
---|---|---|---|
spritesheet | true | String | - |
json | true | String | - |
id | false | String | vue-spritecore-canvas |
frameSorting | false | String [ 'asc', 'desc'] | 'asc' |
scaleX | false | Number | 1 |
scaleY | false | Number | 1 |
autoplay | false | Boolean | false |
loop | false | Boolean | true |
lowerBound | false | Number | 0 |
upperBound | false | Number | animationLength |
Methods
play(from, to)
: plays the animation from frame (from) to frame (to) . If no parameter is provided the animation is played from lowerBound to upperBoundstop()
: stops (freezes) the animation at the point in time it's invokedreset(to)
: resets the animation at frame (to) . If no parameter is provided the animation is resetted at frame lowerBoundplayLegacy(frameRate)
: plays the animation through the legacy animator at a constant framerate (frameRate)
Name | Arguments | Default |
---|---|---|
play | from (optional), to (optional) |
from: lowerBound, to: animationLength |
stop | - | - |
reset | to (optional) | to: lowerBound |
playLegacy | framerate (optional) | 60 |
In most of the cases it is not recommended to run the animation at a predefined constant framerate (through the playLegacy method) using a delta time based timing fn. A good explanation has already been given here .
Note: playLegacy() doesn't support autoplay or loop yet. The autoplay props utilize the default render method that allows the browser to optimize the animation framerate .
Events
ready
: assets has been loaded and animation is readyanimationStarted
: animation startedanimationStopped
: animation stoppedanimationReset
: animation has been resetanimationOver
: animation is over
Name | Arguments |
---|---|
ready | - |
animationStarted | startFrame, stopFrame |
animationStopped | frame |
animationReset | frame |
animationOver | frame |