Crafty FAQ (draft)

This is a draft FAQ that could eventually be put at craftyjs.com

How do events (bind, trigger) work?

There are two types of event bindings:

• Bindings "owned" by a certain entity (the usual case). These are created by some_entity.bind("PlayerDeath", some_function)
• Global bindings (less common). These are created by Crafty.bind("PlayerDeath", some_function)

Then there are two types of event triggers:

• An entity-specific event trigger (the usual case). You would run some_entity.trigger("PlayerDeath"). It runs the functions bound to PlayerDeath, but ONLY those owned by the same entity, i.e. some_entity.
• A global event trigger (less common). You would run Crafty.trigger("PlayerDeath"). It runs EVERYTHING bound to PlayerDeath, no matter what entity owns it, and also including the global events.

On an HTML5 canvas, I can draw arbitrary lines, shapes, gradients, etc. How do I do that in Crafty?

If you are always drawing the same image, it is usually easier to just load the image file and use the Image component or Crafty.sprite. But if the image changes in too many ways to pre-load, you can do custom canvas drawing. You should make your own component with the custom drawing routine bound to the "Draw" event. Here is a simple example to use as a template. Let's call it "DiagonalLine":

Crafty.c("DiagonalLine", {
    init: function () {
        this.requires("2D, Canvas");
        this.bind("Draw", this._draw_me);
        this.ready = true;
    },
    _draw_me: function (e) {
        var ctx = e.ctx;
        ctx.lineWidth = 2;
        ctx.strokeStyle = "green";
        ctx.beginPath();
        ctx.moveTo(e.pos._x, e.pos._y);
        ctx.lineTo(e.pos._x + 5, e.pos._y + 7);
        ctx.stroke();
    }
});

Crafty.e("DiagonalLine").attr({x: 10, y: 20, w: 5, h: 7});

(The last line is just an example: It draws a diagonal line from (10,20) to (15, 17).)

Keep in mind:

• Whenever the appearance (shape, color, position, etc.) of the drawing changes, be sure to run this.trigger("Change"). Otherwise Crafty does not realize that it needs to redraw. Changing this.x or this.y triggers Change automatically, but other kinds of changes may not.
• An entity with this component needs to have the 2D and Canvas components too, and it needs to have x, y, w, h properties that define an invisible rectangular box which is as big or bigger than the drawing. This is important - it communicates to Crafty where the entity is, so that Crafty can correctly redraw only the parts of the canvas that need to be updated. (If you want, you can make the invisible rectangular box the size of the whole canvas; the only disadvantage of doing this is that it will force Crafty to redraw more entities more often, so the game may run slower.)
• Nothing will draw until you set this.ready = true;
• You should think of e.pos._x as a synonym of this._x, and e.pos._y as a synonym of this._y, but with the special advantage that if you rotate or flip the entity (using the normal Crafty commands, e.g. this.rotation = 90;, this.flip('X');, this.origin('center');, etc.), your drawing will rotate or flip in the correct way.