Crafty.c()

src/core/core.js#L1854-L1928
public void Crafty.c(String name, Object component)
name

Name of the component

component

Object with the component's properties and methods

Creates a component where the first argument is the ID and the second is the object that will be inherited by entities.

Specifically, each time a component is added to an entity, the component properties are copied over to the entity.

  • In the case of primitive datatypes (booleans, numbers, strings) the property is copied by value.
  • In the case of complex datatypes (objects, arrays, functions) the property is copied by reference and will thus reference the components' original property.
  • (See the two examples below for further explanation) Note that when a component method gets called, the this keyword will refer to the current entity the component was added to.

A handful of methods or properties are treated specially. They are invoked in partiular contexts, and (in those contexts) cannot be overridden by other components.

  • required: A string listing required components, which will be added to the component before init() runs.
  • init: A function to be called when the component is added to an entity
  • remove: A function which will be called just before a component is removed, or before an entity is destroyed. It is passed a single boolean parameter that is true if the entity is being destroyed.
  • events: An object whose properties represent functions bound to events equivalent to the property names. (See the example below.) The binding occurs directly after the call to init, and will be removed directly before remove is called.
  • properties: A dictionary of properties which will be defined using Object.defineProperty. Typically used to add setters and getters.

In addition to these hardcoded special methods, there are some conventions for writing components.

  • Properties or methods that start with an underscore are considered private.
  • A method with the same name as the component is considered to be a constructor and is generally used when you need to pass configuration data to the component on a per entity basis.

Example

Crafty.c("Annoying", {
    _message: "HiHi",
    init: function() {
        this.bind("UpdateFrame", function() { alert(this.message); });
    },
    annoying: function(message) { this.message = message; }
});

Crafty.e("Annoying").annoying("I'm an orange...");

To attach to the "UpdateFrame" event using the events property instead:

Crafty.c("Annoying", {
    _message: "HiHi",
    events: {
        "UpdateFrame": function(){alert(this.message);}
    }
    annoying: function(message) { this.message = message; }
});
Warning

In the examples above the field _message is local to the entity. That is, if you create many entities with the Annoying component, they can all have different values for _message. That is because it is a simple value, and simple values are copied by value. If however the field had been an object or array, the value would have been shared by all entities with the component, because complex types are copied by reference in javascript. This is probably not what you want and the following example demonstrates how to work around it.

Crafty.c("MyComponent", {
    _iAmShared: { a: 3, b: 4 },
    init: function() {
        this._iAmNotShared = { a: 3, b: 4 };
    },
});

See Also