The Scriptor Broker

Integration (Almost) Without Code

The ScriptorBroker is a broadcast receiver that listens to "*" (all broadcasts). Whenever a broadcast is sent, the broker intercepts it, examines the details (e.g., sender, name), and executes the corresponding script if registered.

To create a broker, instantiate the ScriptorBroker class and store the instance in your game controller, room controller, or any other appropriate location:

broker = new ScriptorBroker([filter]);

• If you want the broker to listen to all broadcasts, use the default "*" filter.
• To limit the broadcasts the broker listens to, supply a specific filter when creating the instance.

Start and Stop the Broker

Activate or deactivate the broker as needed using start() and stop().

// Start listening for broadcasts
broker.start();

// Stop listening
broker.stop();

Fully Transparent Operation

Once started, the broker operates transparently and autonomously. It catches broadcasts and executes the associated scripts without requiring further interaction. This design allows for almost codeless integration into your game!

Note: Singleton Behavior

The ScriptorBroker is a singleton class! If you create multiple instances, the most recent one will replace the previous instance.

Important

Keep in mind, that creating a new instance of the broker will drop all registered scripts on all types, equivalent to calling the clear() method on the broker!

How Does It Work

1. Broadcast Interception

When active, the broker captures every broadcast sent via the raptor broadcaster.

2. Sender and Script Matching

It inspects the from field of the broadcast (the sender), retrieves its type, and checks if a script is registered for that type.
See Registering Broker Events.

3. Script Execution

If the type is found and a script with a name equal to the title of the broadcast exists, the broker executes the script, dynamically rebinding the sender as the owner (self.) of the script.

• Scripts using the self. keyword will refer to the broadcast sender.

The $bc variable

If your script gets executed through a broker event, the script may access the entire broadcast instance that has been sent in the script through the $bc variable, which is set by the broker.

You can even stop executing additional scripts by setting handled to true. For more details on how the raptor broadcasts work, see Broadcasting,

// if your broker is registered like this or through "register" on the broker...
#broker your_sender your_broadcast

// ... you may access the broadcast through $bc...
var name = $bc.title

// ... do something with the sender
$bc.from.visible = false

// ...and even stop executing additional callbacks
$bc.handled = true

What About Inheritance?

Good question!

Imagine, you have an object model like this in your game (the + attributes represent broadcasts with attached scripts):

---
title: Monsters
---
classDiagram
    Monster --|> Normal
    Monster --|> Elite
    Monster --|> Boss

    Normal --|> Orc
    Normal --|> Undead

    Elite --|> Orc Captain
    Elite --|> Lich

    Boss  --|> UndeadLord

    Monster: +on_combat_start
    Monster: +on_combat_end
    Monster: +on_attack
    Monster: +on_hit
    Monster: +on_die

    Lich: +on_life_leech
    Lich: +on_hit

    Boss: +on_combat_start
    Boss: +on_combat_end
    Boss: +on_hit

    UndeadLord: +on_combat_start
    UndeadLord: +on_hit

Loading

You can see, that events occur in multiple places, like the on_hit, which triggers for a Monster, a Lich, a Boss and for the UndeadLord.

Inheritance Matters!

If your game enters combat against the UndeadLord, and the player lands a hit, there are two possible outcomes:

• Single Event Execution: Only the on_hit of the UndeadLord triggers
• Chained Event Execution: The on_hit events trigger in sequence from Monster -> Boss -> UndeadLord

Overriding Base Event Definitions

It's your choice!
You can control how events propagate by using the is_override marker:

• With is_override : The chain is broken, and only the current level’s event executes.
• Without is_override: The entire chain of events triggers, following the inheritance hierarchy.

Note

More on this in Registering Broker Events and the Scriptor Broker File Format for detailed instructions.

This approach gives you full control over how events behave, allowing you to design triggers that fit your game’s needs.

Create Less Objects

By leveraging inheritance and Scriptor’s scripting capabilities, you can significantly reduce the number of objects in your game. For example:

• Instead of creating separate objects for each monster type (e.g., Orc, UndeadLord), you can use one generic Monster object.
• Use scripts to define attributes like sprites, animations, sounds, and behaviors dynamically. This approach keeps your game code streamlined while offering greater flexibility. Scripts can handle the unique traits of each entity, keeping your game scalable and easier to maintain.