Broadcasting

The Broadcasting subsystem in raptor consists of three main components:

Class	Description
Sender	This is your main object. The Sender is kind of a radio-station, sending out broadcasts to all listening receivers. Just create a new Sender() and add receivers to it. NOTE: gml-raptor creates one Sender in the GAMECONTROLLER object. It can be accessed through the BROADCASTER macro. This macro will always point to a valid Sender.
Receiver	When using the add_receiver function of your sender, a receiver is built with the given name, message_filter and callback. Use remove_receiver with its name to stop receiving messages in its callback.
Broadcast	Use the send function on a sender to send out a broadcast message. It contains three members: from - the sender of the broadcast title - the name of the broadcast (this one must pass the message_filter of a receiver) data - optional struct that holds any additional data for this broadcast.

How to use the subsystem: If you want to send something, just create a new Broadcast(...) and call Sender.send(broadcast).

Here is a small example:

var snd = new Sender();
snd.add_receiver("achievement_counter", "*_died", my_achievement_counter_function);

... when a monster dies you could invoke

snd.send(self, "dragon_died");

The message_filter

In larger games, there are many messages sent through the senders and a receiver normally does not need to catch all of them. As an example, the achievement receiver in the code shown above shall only count, when a monster dies, so it receives only messages that end with _died.

The title of a message is a string defined by you. So you should set up a naming system for your messages to make them filterable.

Supported filter types

The message_filter uses the string_match function from the string utilities script, which is also part of raptor. This function supports four types of wildcards:

Wildcard	Syntax	Description
*anything	* at the beginning	Matches all string that end with "anything"
anything*	* at the end	Matches all string that start with "anything"
*anything*	* at the beginning and the end	Matches all string that contain "anything"
anything	No * at all	Exact match

The constructors

Sender

var snd = new Sender();

The Sender has no constructor parameters. You can create as many as you like.

Receiver

Receiver(_name, _message_filter, _callback = undefined, _one_shot = false)

var rcv = new Receiver("super-receiver", "*message*", myCallbackFunction);

Every receiver must have a unique name for a Sender, so it can find specific receivers if needed.
The second parameter is the message_filter which defines the messages that will be received by the third parameter:
The callback_function. This gets invoked whenever a message is sent that matches the filter.
The callback receives 1 parameter: The Broadcast instance that has been sent.

The last parameter, one_shot allows you to create special "receive only 1 message"-receivers. Sometimes it happens in games that you want to track only the next occurrence of something. This is, where this parameter becomes handy, as you can create a one-shot receiver, which will be automatically removed after it received a message.

---

⚠️ PRO TIPP
If your callback function returns true, this receiver will be removed after processing the message. This is a comfortable shortcut to remove a receiver, after its work is done. As an example, if the achievement "Kill 100 Monsters" is reached, this receiver no longer must count dying monsters, so it can be removed.
Instead of keeping the receiver in an instance variable and then referencing it from within the callback, simply return true, when the work is done.

If the callback function doesn't return anything, the receiver stays in the queue (which is the default).

---

Broadcast

Broadcast(_from, _title, _data = undefined)

var bc = new Broadcast(self, "my-cool-event", { eventData : someCoolArray });

You need to provide the sender (the object instance sending the event). This parameter may be set to undefined if no sender is available.
The second parameter contains the title of the broadcast and will be matched against all message_filters of the receivers in the Sender.
The third parameter is optional, but may provide here any struct to be delivered to the receivers.