LRE Event Alias

tl;dr

With LRE7 you can use a colon in event name like component.on("update:secondHandler", function () {}). It will add an additionnal handler linked to the update event.

Introduction

LRE6 came with a breaking change from original Let's Role system builder engine : while Let's Role allowed only one event per type on a component by keeping only the latest defined event handler, LRE6 was cumulating the event handlers. It allowed the system author to separate rule logics in different event handler.

LRE7 keeps the original Let's Role behavior by keeping the latest event handler. That help installing LRE in a system without breaking the existing code. However LRE7 includes a way to had different event handlers of the same type on a component by using aliases.

Alias syntax

LRE7 accept the colon : in the event type given to on(). The event name is then divided into two parts : the first matching everything before the colon will be the event type, the second part after the colon will be the event alias.

The three following codes does the same thing :

• Original Let's Role script

component.on("update", function (cmp) {
    computeBonusHandler(cmp);
    computeLifePointHandler(cmp);
});

• LRE6 script

component.on("update", computeBonusHandler);
component.on("update", computeLifePointHandler);

• LRE7 script

component.on("update", computeBonusHandler);
component.on("update:lifePoint", computeLifePointHandler);

The functions computeBonusHandler and computeLifePointHandler will be executed as soon as the component is modified.

Event alias triggering

Let's Role offers the six following original events : "click", "update", "mouseenter", "mouseleave", "keyup", "change". You can use aliases with them, the attached handlers will be executed as soon as the original events are triggered.

LRE7 allow you to manually trigger an event, or a specific event alias.

// consider the previous examples
component.trigger("update"); // it will execute computeBonusHandler and computeLifePointHandler
component.trigger("update:lifePoint"); // it will execute ONLY computeLifePointHandler

The other event methods work with event aliases as well, like off(), once().

Disabling events

You can only disable an complete event type, not an event alias specifically. If you disable an event, all its alias will be disabled as well.

component.disableEvent("update:lifePoint"); // it will do nothing
component.disableEvent("update"); // it will do nothing
component.trigger("update:lifePoint"); // computeLifePointHandler is NOT executed

Custom event types

As LRE7 implements the custom event types, you can also aliases with them.

Example :

component.on("customEvent:showHide", showHide);
/* ... */
component.trigger("customEvent"); // it executes showHide function

Handler removing or overwrite

If you want to definitely deactivate an event handler based on a alias, you can use off() like with vanilla Let's Role script.

component.off("update:lifePoint");

If you call on() a second time with the same alias, only the last handler will be kept (it works like vanilla Let's Role script).

component.on("click:event1", function () {
    log("hello");
});
component.on("click:event1", function () {
    log("world");
});
component.trigger("click"); // this will log only "world"

Logging information

If you choose to enable the LRE logs, an error during the execution of an event handler will be logged with additional information including the event alias. It can make debugging much easier (where the error is ? what triggered this code ?)!

Example with logs at Trace level, you can easily see that the error is located at line 5266, raised by clicking on weapon component, in the event aliased computeDamage :

[LRE][TRC] Run events weapon:click
[LRE][TRC]   Run handler weapon:click:computeDamage
[LRE][ERR]     [Event:weapon:click:computeDamage] Unhandled error : T is null at line 5266
[LRE][TRC]   Run handler weapon:click:computeDamage (0ms)
[LRE][TRC] Run events weapon:click (3ms)

LRE customs events

You might encounter some LRE internal events. They are here to implements some advanced features. They are free to use but make sure not to overwrite any internal event handler(their aliases are suffixed with __lre__, you only have to not use this text in event aliases).

More events

LRE provides some more events on some SB entities (component, sheet, …). You can find them in the documentation of each entity.

Why multiple event handlers instead of a single one ?

It is a highly recommended to have the smallest functions you can that do one unique thing (at least everyone should try to reach this goal). With single event handlers it is very difficult to do that properly and for complex RPG rules the very large events can be hard to understand and debug. Having multiple event handlers open the possibility to code and name each small RPG rule and then easily structure your script, decreasing the time you spend struggling on a hidden bug about this wrong skill bonus computation.