Kapi is designed to be easily extendible, so you can easily modify it to suit your needs.
Kapi is designed to completely abstract away your animation's state management logic. In every frame, Kapi hands off the current state data to your actors. But what are actors, and how do you make and use them?
For instructions on how to add an actor to your Kapi instance, check out the documentation for kapiInst.add(). This section deals with the ideas behind the actor construct.
Before we can make an actor, we must first define an actor template. An actor template is just the blueprint for how an actor will operate. This is an actor template example:
var circle = {
draw: function (ctx, kapiInst, actorInst){
ctx.beginPath();
ctx.arc(
this.x || 0,
this.y || 0,
this.radius || 0,
0,
Math.PI*2,
true
);
ctx.fillStyle = this.color || '#f0f';
ctx.fill();
ctx.closePath();
return this;
}
}
The format for this is important, as this is how Kapi interfaces with actors. If you found that unhelpful, here's a skeleton of an actor you can use to build off of:
var actorSkeleton = {
draw: function (ctx, kapiInst, actorInst){
// Code that draws stuff to the canvas (`ctx`) goes here
return this;
}
}
You can also have setup and teardown methods in addition to draw, but that is outside of the scope of this section (see kapiInst.add()).
Although you don't have to, it's not a bad idea to attach your actor templates to kapi.actorTemplates. It's just a globally-accessible container that's attached to the kapi constructor function. Doing this will ensure that your actor templates are accessible to any parts of your code that might need them. Here's how that might look:
kapi.actorTemplates.myAwesomeActor = {
draw: function (ctx, kapiInst, actorInst){
// Code that draws stuff to the canvas (`ctx`) goes here
return this;
}
}
Once you have an actor template, you can make actor instances. For example, if circle is an actor template, you can make as many instances of circle as you need. To create an instance of an actor, pass an actor template into kapiInst.add(). A reference to the new instance is returned from the method call. You can also get a reference to the actor instance from the Kapi instance at any time with kapiInst.getActor(). Actor instances have all of the methods and properties that are documented in the actor documentation page.
Kapi has only one tweening method built into the core: linear. (This is Robert Penner's Linear tweening equation). You can add whatever tweening methods you like, as long as they follow the same format. Here's the code for Linear:
// Params are as follows:
// t = current time
// b = start value
// c = change in value
// d = duration
kapi.tween = {
linear: function (t, b, c, d) {
// no easing, no acceleration
return c * t / d + b;
}
};
For convenience, a selection of Robert Penner's tweening equations can be found in kapi.tweens.js. For even more convenience, the contents of this file are also in the main source file and also in the standard minified build. If you feel you don't need these extra equations, you can safely delete them from the files.
If you would like to add more tweens, just attach them to the kapi.tween object. Here's an example of how to add a tween; Robert Penner's "easeInOutQuint," in this case:
kapi.tween.easeInQuint = function (t, b, c, d) {
t /= d;
return c * t * t * t * t * t + b;
};