Simple Event Framework

Simple Event Framework

Engine level asynchronous event messaging between redscript and lua code. Add custom listeners, and send custom payloads. Finally be able to talk across code in a reliable way - at engine speed!

[img]https://i.ibb.co/8RM8ZnY/overview.png[/img]
[size=4]Engine level asynchronous event messaging between redscript and lua code. Add custom listeners, and send custom payloads. Finally be able to talk across code in a reliable way - at engine speed![/size]

[code]player:SendEventMessage("BaseStatusEffect.SimpleEventMessage",{"Payload1","Payload2","Payload3"})[/code]

[img]https://i.ibb.co/21RrS11y/install.png[/img]
[size=4]Via mod manager or unzip into game directory.[/size]

[img]https://i.ibb.co/7x6jSjnM/usage.png[/img]

lua
[code]> sef = GetMod("SimpleEventFramework")
> function mylistener(message) for i,tag in ipairs(message) do print("HANDLER:",tag.value) end end
> sef:AddEventMessageListener("BaseStatusEffect.SimpleEventMessage",mylistener)
> player:SendEventMessage("BaseStatusEffect.SimpleEventMessage",{"One","Two","Three"})[/code]
redscript
[code]module SimpleEventFramework.Example

import SimpleEventFramework.System.*

public class MyListenerClass extends ListenerCallback {
  public func Call() -> Void {
    for tag in this.tags {
        FTLog("[MyListenerClass] tag "+this.event+":"+NameToString(tag));
    }
    StatusEffectHelper.RemoveStatusEffect(this.player, t"BaseStatusEffect.SimpleEventMessage");
  }
}

@wrapMethod(PlayerPuppet)
protected cb func OnGameAttached() -> Bool {
    let ret: Bool  = wrappedMethod();

    let eventFramework = SimpleEventFramework.GetInstance(this);
    if IsDefined(eventFramework) {
        let listener: ref<MyListenerClass> = new MyListenerClass();
        listener.event = "BaseStatusEffect.SimpleEventMessage";
        eventFramework.AddEventMessageListener(listener);
    }

    return ret;
}[/code][size=2]NOTE: From r6/scripts/SimpleEventFramework/Example.reds[/size]

[size=4][b]Message Objects[/b][/size]

Message objects are based on Tweak records for BaseStatusEffects, as this framework uses status effects to pass messages through the engine. One is provided for you [color=#c27ba0]BaseStatusEffect.SimpleEventMessage[/color] however, you are free to clone that into your own message types with pre-defined debugTags. This acts as a container for message payloads that are carried as tag strings in the debugTags section of the record.

[code]BaseStatusEffect.SimpleEventMessage:
  debugTags: []
  duration: BaseStats.InfiniteDuration
  dynamicDuration: False
  gameplayTags: []
  immunityStats: []
  isAffectedByTimeDilationNPC: True
  isAffectedByTimeDilationPlayer: True
  maxStacks: RTDB.StatusEffect_inline0
  packages: []
  reapplyPackagesOnMaxStacks: False
  removeAllStacksWhenDurationEnds: False
  removeOnStoryTier: False
  replicated: False
  savable: True
  SFX: []
  statusEffectType: BaseStatusEffectTypes.Misc
  stopActiveSfxOnDeactivate: True
  $type: gamedataStatusEffect_Record
  VFX: [][/code]When you send a message, you specify the base message record id and then a list of tags (the payload) you want carried with your message.

[size=4][b]Registering Listeners[/b][/size]

[size=4]Listeners are registered on the message object id. And when that message (type) is triggered, the payload tags are passed along to each listener.

From the example above (lua)[/size]

[code]sef:AddEventMessageListener("BaseStatusEffect.SimpleEventMessage",mylistener)[/code][size=4]and the listener is a function[/size]
[code]function mylistener(message) for i,tag in ipairs(message) do print("HANDLER:",tag.value) end end[/code][size=4]
It works slightly different in redscript as shown in the example further up.[/size]

[b][size=4]Consuming/Removing Messages[/size][/b]

[size=4]It is your responsibility to consume (i.e. remove) the message after you have processed it in your code. This is done as follows[/size]

[size=4]lua[/size]
[code]StatusEffectHelper.RemoveStatusEffect(Game.GetPlayer(), "BaseStatusEffect.SimpleEventMessage")[/code][size=4]redscript[/size]
[code]StatusEffectHelper.RemoveStatusEffect(player, t"BaseStatusEffect.SimpleEventMessage");[/code]
[img]https://i.ibb.co/zHjrfCGz/docs.png[/img]
[color=#c27ba0][size=5][b]Simple Event Framework API Documentation[/b][/size][/color]

[size=4][b]Class: SimpleEventFramework[/b][/size]
The core scriptable system managing event distribution and listeners.

[b]GetInstance[/b]
[font=Courier New][color=#00BFFF]public[/color] [color=#00BFFF]static[/color] [color=#00BFFF]func[/color] GetInstance(obj: [color=#FF1493]ref[/color]<[color=#FF1493]GameObject[/color]>) -> [color=#FF1493]ref[/color]<[color=#FF1493]SimpleEventFramework[/color]>[/font]
Retrieves the active instance of the SimpleEventFramework.
[list]
[][b]obj[/b]: Any valid [font=Courier New][color=#FF1493]GameObject[/color][/font] with access to the GameInstance (e.g., the player).[/]
[/list]
[b]SendEvent[/b]
[font=Courier New][color=#00BFFF]public[/color] [color=#00BFFF]func[/color] SendEvent(message: [color=#FF1493]String[/color], tags: [color=#FF1493]array[/color]<[color=#FF1493]String[/color]>) -> [color=#FF1493]Void[/color][/font]
Sends an immediate event using a status effect.
[list]
[][b]message[/b]: The TweakDB ID of the event message (e.g., [font=Courier New][color=#FF69B4]"BaseStatusEffect.SimpleEventMessage"[/color][/font]).[/]
[][b]tags[/b]: A list of string tags to pass to listeners.[/]
[/list]
[b]SendDelayedEvent[/b]
[font=Courier New][color=#00BFFF]public[/color] [color=#00BFFF]func[/color] SendDelayedEvent(message: [color=#FF1493]String[/color], tags: [color=#FF1493]array[/color]<[color=#FF1493]String[/color]>, delay: [color=#FF1493]Float[/color]) -> [color=#FF1493]Void[/color][/font]
Sends an event after a specified delay.
[list]
[][b]message[/b]: The TweakDB ID of the event message.[/]
[][b]tags[/b]: A list of string tags to pass to listeners.[/]
[][b]delay[/b]: Time in seconds to wait before sending the event.[/]
[/list]
[b]AddEventMessageListener[/b]
[font=Courier New][color=#00BFFF]public[/color] [color=#00BFFF]func[/color] AddEventMessageListener(listener: [color=#FF1493]ref[/color]<[color=#FF1493]ListenerCallback[/color]>) -> [color=#FF1493]Void[/color][/font]
Registers a listener callback that will be triggered when an event matches the listener's specified event string.
[list]
[][b]listener[/b]: A reference to a [font=Courier New][color=#FF1493]ListenerCallback[/color][/font] object.[/]
[/list]
[line]

[size=4][b]PlayerPuppet Extensions[/b][/size]

[b]SendEventMessage[/b]
[font=Courier New][color=#00BFFF]public[/color] [color=#00BFFF]func[/color] SendEventMessage(message: [color=#FF1493]String[/color], tags: [color=#FF1493]array[/color]<[color=#FF1493]String[/color]>) -> [color=#FF1493]Void[/color][/font]
A convenient method added to [font=Courier New][color=#FF1493]PlayerPuppet[/color][/font] to quickly send an event without manually looking up the framework system.
[list]
[][b]message[/b]: The TweakDB ID of the message.[/]
[][b]tags[/b]: An array of strings representing tags associated with the event.[/]
[/list]
[line]

[size=4][b]Class: ListenerCallback[/b][/size]
A class that you can extend or instantiate to listen to events. Inherits from [font=Courier New][color=#FF1493]DelayCallback[/color][/font].

[b]Properties[/b]
[list]
[][font=Courier New][color=#00BFFF]public[/color] [color=#00BFFF]let[/color] event: [color=#FF1493]String[/color];[/font] - The event message ID you want to listen for.[/]
[][font=Courier New][color=#00BFFF]public[/color] [color=#00BFFF]let[/color] tags: [color=#FF1493]array[/color]<[color=#FF1493]CName[/color]>;[/font] - Populated automatically by the framework with the tags sent alongside the event when triggered.[/]
[/list]
[b]Methods[/b]
[font=Courier New][color=#00BFFF]public[/color] [color=#00BFFF]func[/color] Call() -> [color=#FF1493]Void[/color][/font]
The callback function executed when the event is triggered. Override this to add your custom execution logic.