Crafty Core

src/core/core.js#L80-L91

Events

NewEntityName [entity name = {String}]
After setting new name for entity
NewComponent [Component = {String}]
when a new component is added to the entity
RemoveComponent [Component = {String}]
when a component is removed from the entity
Remove
when the entity is removed by calling .destroy()

A set of methods added to every single entity.

Methods

Back to top

.addComponent()

src/core/core.js#L259-L288
public this .addComponent(String componentList)
componentList

A string of components to add separated by a comma ,

public this .addComponent(String Component1[, .., String ComponentN])
Component#

Component ID to add.

Adds a component to the selected entities or entity.

Components are used to extend the functionality of entities. This means it will copy properties and assign methods to augment the functionality of the entity.

For adding multiple components, you can either pass a string with all the component names (separated by commas), or pass each component name as an argument.

If the component has a function named init it will be called.

If the entity already has the component, the component is skipped (nothing happens).

Example

this.addComponent("2D, Canvas");
this.addComponent("2D", "Canvas");
Back to top

.attr()

src/core/core.js#L520-L569

Events

Change [Data = {key: value}]
when properties change
public this .attr(String property, Any value[, Boolean silent[, Boolean recursive]])
property

Property of the entity to modify

value

Value to set the property to

silent

If you would like to supress events

recursive

If you would like merge recursively

Use this method to set any property of the entity.

public this .attr(Object map[, Boolean silent[, Boolean recursive]])
map

Object where each key is the property to modify and the value as the property value

silent

If you would like to supress events

recursive

If you would like merge recursively

Use this method to set multiple properties of the entity.

Setter options:

  • silent: If you want to prevent it from firing events.
  • recursive: If you pass in an object you could overwrite sibling keys, this recursively merges instead of just merging it. This is false by default, unless you are using dot notation name.first.
public Any .attr(String property)
property

Property of the entity to modify

[Returns]

Value - the value of the property

Use this method to get any property of the entity. You can also retrieve the property using this.property.

Example

this.attr({key: "value", prop: 5});
this.attr("key"); // returns "value"
this.attr("prop"); // returns 5
this.key; // "value"
this.prop; // 5

this.attr("key", "newvalue");
this.attr("key"); // returns "newvalue"
this.key; // "newvalue"

this.attr("parent.child", "newvalue");
this.parent; // {child: "newvalue"};
this.attr('parent.child'); // "newvalue"
Back to top

.bind()

src/core/core.js#L726-L762
public this .bind(String eventName, Function callback)
eventName

Name of the event to bind to

callback

Method to execute when the event is triggered

Attach the current entity (or entities) to listen for an event.

Callback will be invoked when an event with the event name passed is triggered. Depending on the event, some data may be passed via an argument to the callback function.

The first argument is the event name (can be anything) whilst the second argument is the callback. If the event has data, the callback should have an argument.

Events are arbitrary and provide communication between components. You can trigger or bind an event even if it doesn't exist yet.

Unlike DOM events, Crafty events are executed synchronously.

Example

this.attr("triggers", 0); //set a trigger count
this.bind("myevent", function() {
    this.triggers++; //whenever myevent is triggered, increment
});
this.bind("UpdateFrame", function() {
    this.trigger("myevent"); //trigger myevent on every frame
});
Back to top

.clone()

src/core/core.js#L970-L980
public Entity .clone(void)
[Returns]

Cloned entity of the current entity

Method will create another entity with the exact same properties, components and methods as the current entity.

Back to top

.defineField()

src/core/core.js#L1019-L1047
public this .defineField(String property, Function getCallback, Function setCallback)
property

Property name to assign getter & setter to

getCallback

Method to execute if the property is accessed

setCallback

Method to execute if the property is mutated

Assigns getters and setters to the property. A getter will watch a property waiting for access and will then invoke the given getCallback when attempting to retrieve. A setter will watch a property waiting for mutation and will then invoke the given setCallback when attempting to modify.

Example

var ent = Crafty.e("2D");
ent.defineField("customData", function() {
   return this._customData;
}, function(newValue) {
   this._customData = newValue;
});

ent.customData = "2" // set customData to 2
Crafty.log(ent.customData) // prints 2
Back to top

.destroy()

src/core/core.js#L1053-L1060
public this .destroy(void)

Will remove all event listeners and delete all properties as well as removing from the stage

Back to top

.each()

src/core/core.js#L886-L909
public this .each(Function method)
method

Method to call on each iteration

Iterates over found entities, calling a function for every entity.

The function will be called for every entity and will pass the index in the iteration as an argument. The context (value of this) of the function will be the current entity in the iteration.

Example

Destroy every second 2D entity

Crafty("2D").each(function(i) {
    if(i % 2 === 0) {
        this.destroy();
    }
});
Back to top

.freeze()

src/core/core.js#L1079-L1106
public this .freeze()

Events

Freeze
Directly before the entity is frozen

Freezes the entity. A frozen entity will not receive events or be displayed by graphics systems. It is also removed from the spatial map, which means it will not be found by collisions, raycasting, or similar functions.

This method may be called upon a collection of entities.

Note: Because the entity no longer listens to events, modifying its properties can result in an inconsistent state.

If custom components need to handle frozen entities, they can listen to the "Freeze" event, which will be triggered before the event system is disabled.

Example

// Freeze all entities with the Dead component
Crafty("Dead").freeze();

See Also

Back to top

.get()

src/core/core.js#L921-L949
public Array .get()
[Returns]

An array of entities corresponding to the active selector

public Entity .get(Number index)
[Returns]

an entity belonging to the current selection

index

The index of the entity to return. If negative, counts back from the end of the array.

Example

Get an array containing every "2D" entity

var arr = Crafty("2D").get()

Get the first entity matching the selector

// equivalent to Crafty("2D").get()[0], but doesn't create a new array
var e = Crafty("2D").get(0)

Get the last "2D" entity matching the selector

var e = Crafty("2D").get(-1)
Back to top

.getId()

src/core/core.js#L480-L497
public Number .getId(void)
[Returns]

the ID of this entity.

For better performance, simply use the this[0] property.

Example

Finding out the ID of an entity can be done by returning the property 0.

   var ent = Crafty.e("2D");
   ent[0]; //ID
   ent.getId(); //also ID
Back to top

.getName()

src/core/core.js#L237-L254
public this .getName(String name)
[Returns]

A human readable name for debugging purposes.

Get the human readable name for debugging purposes.

Example

var ent = Crafty.e().setName("Player");
var name = ent.getName();
Back to top

.has()

src/core/core.js#L502-L515
public Boolean .has(String component)
component

The name of the component to check

[Returns]

true or false depending on if the entity has the given component.

For better performance, simply use the .__c object which will be true if the entity has the component or will not exist (or be false).

Back to top

.one()

src/core/core.js#L799-L812
public Number one(String eventName, Function callback)
eventName

Name of the event to bind to

callback

Method to execute upon event triggered

[Returns]

ID of the current callback used to unbind

Works like Crafty.bind, but will be unbound once the event triggers.

See Also

Back to top

.removeComponent()

src/core/core.js#L433-L452
public this .removeComponent(String Component[, soft])
component

Component to remove

soft

Whether to soft remove it (defaults to true)

Removes a component from an entity. A soft remove (the default) will only refrain .has() from returning true. Hard will remove all associated properties and methods.

Example

var e = Crafty.e("2D,DOM,Test");
e.removeComponent("Test");        //Soft remove Test component
e.removeComponent("Test", false); //Hard remove Test component
Back to top

.requires()

src/core/core.js#L407-L428
public this .requires(String componentList)
componentList

List of components that must be added

public this .addComponent(String component1, String component2[, .. , ComponentN])
Component#

A component to add

Makes sure the entity has the components listed. If the entity does not have the component, it will add it.

(In the current version of Crafty, this function behaves exactly the same as addComponent. By convention, developers have used requires for component dependencies -- i.e. to indicate specifically that one component will only work properly if another component is present -- and used addComponent in all other situations.)

Back to top

.setName()

src/core/core.js#L213-L229
public this .setName(String name)
name

A human readable name for debugging purposes.

Set a human readable name for debugging purposes.

Example

var ent = Crafty.e().setName("Player");
Back to top

.setter()

src/core/core.js#L1000-L1014
public this .setter(String property, Function callback)
property

Property to watch for modification

callback

Method to execute if the property is modified

Will watch a property waiting for modification and will then invoke the given callback when attempting to modify.

This feature is deprecated; use .defineField() instead.

See Also

Back to top

.timeout()

src/core/core.js#L695-L715
public this .timeout(Function callback, Number delay)
callback

Method to execute after given amount of milliseconds

delay

Amount of milliseconds to execute the method

The delay method will execute a function after a given amount of time in milliseconds.

Essentially a wrapper for setTimeout.

Example

Destroy itself after 100 milliseconds

this.timeout(function() {
this.destroy();
}, 100);
Back to top

.toArray()

src/core/core.js#L681-L690
public this .toArray(void)

This method will simply return the found entities as an array of ids. To get an array of the actual entities, use get().

See Also

Back to top

.toggleComponent()

src/core/core.js#L344-L369
public this .toggleComponent(String ComponentList)
ComponentList

A string of components to add or remove separated by a comma ,

public this .toggleComponent(String Component1[, .., String componentN])
Component#

Component ID to add or remove.

Add or Remove Components from an entity.

Example

var e = Crafty.e("2D,DOM,Test");
e.toggleComponent("Test,Test2"); //Remove Test, add Test2
e.toggleComponent("Test,Test2"); //Add Test, remove Test2
var e = Crafty.e("2D,DOM,Test");
e.toggleComponent("Test","Test2"); //Remove Test, add Test2
e.toggleComponent("Test","Test2"); //Add Test, remove Test2
e.toggleComponent("Test");         //Remove Test
Back to top

.trigger()

src/core/core.js#L851-L869
public this .trigger(String eventName[, Object data])
eventName

Event to trigger

data

Arbitrary data that will be passed into every callback as an argument

Trigger an event with arbitrary data. Will invoke all callbacks with the context (value of this) of the current entity object.

Note: This will only execute callbacks within the current entity, no other entity.

The first argument is the event name to trigger and the optional second argument is the arbitrary event data. This can be absolutely anything.

Unlike DOM events, Crafty events are executed synchronously.

Back to top

.unbind()

src/core/core.js#L823-L838
public this .unbind(String eventName[, Function callback])
eventName

Name of the event to unbind

callback

Function to unbind

Removes binding with an event from current entity.

Passing an event name will remove all events bound to that event. Passing a reference to the callback will unbind only that callback.

Back to top

.uniqueBind()

src/core/core.js#L779-L792
public Number .uniqueBind(String eventName, Function callback)
eventName

Name of the event to bind to

callback

Method to execute upon event triggered

[Returns]

ID of the current callback used to unbind

Works like Crafty.bind, but prevents a callback from being bound multiple times.

See Also