Broker Events - coldrockgames/doc-scriptor GitHub Wiki

A broker event is defined as a combination of the following elements:

data_type
filter_field
filter_value
broadcast_message
override

As previously mentioned, the ScriptorBroker is a broadcast listener that, by default, listens to * (all broadcasts). This means every broadcast sent in your game, including raptor-internal broadcasts, will be inspected by the broker.

The broker allows you to attach ("hook") scripts to any broadcast by defining a set of rules.

Elements of a Broker Event

Each broker event hook is defined by the following five components:

Element	Type	Example	Description
Data Type	`string`	`"Enemy"`	The name of a script class or game object. This is the sender (the `.from`) of the broadcast message.
Filter Field	`string`	`"name"`	Optional. The name of a field in the sender of the broadcast. NOTE: Call chains are allowed! Like `data.group.name`.
Filter Value	`string`	`"Rogue*"` `"Zombie"`	Required, if "Filter Field" is present, otherwise optional too. The value, the field must have, to launch the script. raptor wildcards are supported.
Broadcast	`string`	`"combat.monster.died"`	Must be the exact name of a broadcast message (the `.title`). Wildcards are not supported here, as each script must hook to a specific broadcast.
Override	`bool`	`true` or `false`	If the event is an override, no base class events can trigger. It replaces them.

Examples in Human Language

1. Filtered Hook

Run a script on a broadcast combat.monster.died for an Enemy object, whose name starts with Rogue.

This hook will trigger for all broadcasts from Enemy objects or their child classes (e.g., Humans, Orcs, Dragons, etc.).
The script will execute only if the name field of the sender starts with "Rogue".

data_type             "Enemy"
filter_field          "name"
filter_value          "Rogue*"
broadcast_message     "combat.monster.died"
override              false

2. Unfiltered Hook with Multiple Triggers

Run a script on a broadcast combat.monster.died for a Boss object, without any additional filter (run on all bosses).

This hook triggers for all Boss objects when they send the combat.monster.died broadcast.
If the dying monster is a Boss, this script runs in addition to any script hooked for Enemy objects.

data_type             "Boss"
filter_field          ""
filter_value          ""
broadcast_message     "combat.monster.died"
override              false

3. Exclusive Hook with Override

Run a script on a broadcast combat.monster.died for a Boss object, and prevent other scripts from triggering when a boss dies.

This can be achieved by adding the same hook as above but setting override = true.
When override is set, this script replaces any other scripts (like the one for Enemy) that would normally run for this broadcast.
override prevents base class triggers to fire, so this only works, if your inheritance chain of the object is "Enemy -> Boss" (Boss must be a child class or base object of Enemy)

data_type             "Boss"
filter_field          ""
filter_value          ""
broadcast_message     "combat.monster.died"
override              true

Read on the next page, how to Register Broker Events.