How messaging works
The platformer engine uses a component-based structure for entities. This means an entity's functionality is determined by the pieces (called components) that make it up. These components are designed to be self-contained and reusable in multiple types of entities. Thus components, for the sake of re-usability, do not directly call functions in other components. Instead, components use a loosely-coupled messaging system to handle communication between components in a single entity and between components across entities.
The messaging system is built into an entity, such that whenever an entity receives a message (ie. a message is triggered on an entity), the message is handled by all of the entity's components that are listening for that message. An entity knows which components are listening for which messages because the components themselves bind appropriate handlers to the messages. Which messages a component binds to is set by the list of event handlers sent to the component factory:
platformer.createComponentClass({
id: 'NameOfComponent',
constructor: function(definition){},
events: {
"load": function(resp){
// Run event handling code here
}
// List additional handlers if needed
}
});
To communicate with another component on an entity, a component sends a message to its owner entity. The entity will then pass it onto the listening component.
The function that does this is trigger() or triggerEvent() if it's a single event ("trigger" can accept strings, arrays, and event objects). The call would look something like this:
this.owner.trigger('message-name', messageData, false);
'message-name' is the message id that the other component is listening for. 'messageData' is the content of the message. This can be a value or an object. The third parameter turns the message tracking on or off for this message. The message tracking will log the message contents to the JavaScript console. You can also turn message debugging on when you send messageData that is an object with a 'debug: true' key/value pair.
To send a message between two entities, there are a few methods we use. If you are creating a component and have a reference to the entity that you need to talk to you can simply do:
entity.trigger('message-name', messageData);
Thus calling the message on only that entity.
If you don't have a reference to the entity you need to send a message to or are building out an entity using components, there are several components that can be used to manage messages between entities: RelayGame, EntityContainer, and Relaylinker.
So, to send a message from one entity to another, you could add a RelayGame component to the entity sending the message and use its game-wide broadcast feature to send a message to the Scene which would then pass the message to its layers. In the layer you add the message id of your message to the EntityContainer definition so that the message will be sent to all the entities contained inside. Or for a more direct connection, set up a RelayLinker with the same linkId on each entity that should be in on a given conversation. In this way, the entity listening for a given message will receive it.
