(Mighty) Lua Event Manager 12/13/2024

(Mighty) Lua Event Manager
blame Knightly

A script to manage event handlers for text based events (like mq2events) and condition based events (like mq2react).



Overview

Lua Event Manager is intended to provide an alternative to mq2events, mq2react and one-off Lua scripts being written for events.

Rather than events with giant, difficult to read macro if statements, proper Lua functions can be written to handle events instead.

Rather than reacts with a YAML file that frequently gets corrupted or breaks from indentation mistakes, more complex conditions and actions can be implemented.

Event definitions are global and stored in a shared lem/settings.lua file. Editing events from multiple characters can overwrite changes if you aren't reloading before making edits on a character.
Event enabled/disabled state is stored per character in a characters own lem/characters/{name}.lua file. Hopefully this allows to more safely enable or disable events across characters.

More info will be available here... eventually.

P.S. Sorry Lemons that I called this thing lem, please forgive me!

Obtaining Events
Browse the list of user submitted LEM events in the event library resource >> here <<.
Events found in the library can be imported from the "Import" menu in the LEM UI. Copy/paste an event import string from the LEM library into the import menu to import an event.
Event import strings are base64 encoded copies of the event code. When importing the event you will be able to view the code for the event. You can also paste the import strings into a site like https://www.base64decode.org/

Installation

Download the contents to your MQ Lua folder.

Usage

Start the script with: /lua run lem
Start the script with the UI hidden:
Available commands:
/lem [help] - display help output
/lem event <eventname> - toggle text event enabled/disabled
/lem cond <eventname> - toggle condition event enabled/disabled
/lem show - show the UI
/lem hide - hide the UI
/lem reload - reload the script (currently by just restarting the script)

Defining Event Categories

Categories provide a way to group up events, to help keep the text and condition events sections organized. Several example categories are pre-defined, and more can be added or removed from the Categories section.

Managing Events



The Text Events and Condition Events sections provide controls for adding, editing and deleting events.
The event list can be filtered by name to help find the event you are looking for.



Full details of an event can be viewed by double clicking the row in the events table or clicking the View Event button.



Adding Text Events



1. Select Text Events and click Add Event....
2. Enter a name for the new event.
3. Enter a pattern for the new event. The pattern can include #*# for wildcard matches or #1# for named matches. Named matches will be passed as arguments to the event handler function.
4. Implement the handler function for the new event. Template code is provided, including a function event_handler. The function arguments should be updated to match the number of arguments matched in the event pattern. The first argument to the event handler is always the complete line which matched the pattern.

Adding Condition Events

1. Select Condition Events and click Add Event....
2. Enter a name for the new event.
3. Implement the `condition` and `action` functions for the new event. The condition function should return a boolean value, true or false.

Editing Event Code

All event implementations are saved to individual Lua files in /lua/lem/events or /lua/lem/conditions. Editing the code in something like Visual Studio Code is probably still going to be easier than editing within an ImGui window.

Writing Events

Lua is a different beast from the macro script most MQ users are familiar with. When adding a new event in LEM, some template code is provided which leaves you with 1-2 functions that need to be implemented in order for the event to function:

Text Events:

• event_handler
  
  Lua:

  local function event_handler()
      -- Implement the handling for the event here.
  end
  The event_handler function implements the actions to take when a text event is triggered. Depending on the event pattern used, this function may take 1 or more arguments. The first argument is always the full line of text which triggered the event. The second through Nth arguments will be the matches for #1# #2# #3# included in the event pattern.

Condition Events:

• condition
  
  Lua:

  ---@return boolean @Returns true if the condition is met, and the action should be executed. Otherwise, returns false.
  local function condition()
      -- Implement the condition to evaluate here.
  end
  The condition function implements the checks for whether some condition is met. In the simplest case, this could be something like return mq.TLO.Me.Class.ShortName() == 'BRD'.
• action
  
  Lua:

  local function action()
      -- Implement the action to perform here.
  end
  The action function implements the actions to take when the condition is met.

Both:

• on_load
  
  Lua:

  local function on_load()
       -- Perform any initial setup here when the event is loaded.
  end
  The on_load function is called when LEM loads an event for the first time, and gives an opportunity for your event to setup some state, if necessary. None of the events that have been created for LEM so far actually use this.

Debugging Events:

To help with debugging events, log statements can be added to the code using Write.Lua by Knightly. Use the Log Level setting on the Settings menu to adjust the log level accordingly.



testevent2.Lua has been updated with example INFO and DEBUG level log statements: