[LUA] Event listening in a match

[Lazin3ss]

Running lua code in a match is useful for being able to gather character info, get the status of a match, set certain data to characters (maps, state numbers, life, etc), change the music and/or draw things on the screen (GUI mostly), among other things.

This kind of code can be thought as "listening" in Java/JavaScript, where you "listen" for events to happen in the match and perform actions accordingly. In this case, we'll use character debug triggers to do this kind of match listening.

Start by creating a new lua module file in external/mods, you usually want to have all your in-dev mods in this folder.

Inside this module, we'll start by writing our inital listening function statement:

local function f_matchListener()
    -- Do stuff here
end

We want to make this function local, as to avoid overwriting other functions that might use the same identifier.

This function will contain all the code that will be run while the match is going on. In this case, we wanna do something simple like getting the name of the character who loses more than 700 HP in the first round, then kill it.

To get this kind of information, we have to first loop through all possible characters in a match and examine them. For that, we can use "trigger redirector" functions, which are just funcs to select the player that will be affected by the trigger debug functions.

local firstToLoseHP = ""

local function f_matchListener()
    -- Get character data
    if roundno() == 1 then
        for i = 1, 8 do
            player(i) -- Select player to examine
            if life() < 300 and firstToLoseHP == "" then
                firstToLoseHP = name()
                setLife(0)
            end
        end
    end
end

Generally, looping through all 8 possible characters is okay performance-wise, even if the match has less than 8 chars. Having said that, you can still optimize the for loop by first getting the total number of existing characters in the match.

local firstToLoseHP = ""
local totalPlayers = 0

local function f_matchListener()
    -- Get total players in this match
    if totalPlayers == 0 then
        for i = 1, 2 do -- Only check initial characters from both teams
            player(i)
            totalPlayers = totalPlayers + numpartner() + 1
        end
    end
   
    -- Get character data
    if roundno() == 1 then
        for i = 1, totalPlayers do
            player(i) -- Select player to examine
            if life() < 300 and firstToLoseHP == "" then
                firstToLoseHP = name()
                setLife(0)
            end
        end
    end
end

Since we declared some local variables outside of the scope of the function, we need a way to reset them, so we can ensure they'll work in the next match. We'll add a new function that will be in charge of this:

local function f_resetData()
    firstToLoseHP = ""
    totalPlayers = 0
end

At this point, we have everything we want for our event listening. The next step is to use hook functions available in base scripts (external/script) to hook this code into the main loop() lua function (that runs once per frame in a match). This function can be found at external/script/global.lua.

We'll start by hooking f_matchListener() using hook.add():

-- Hook list, hook name, function (as value)
hook.add("loop", "getCharLife", f_matchListener)

We also want to hook f_resetData() somewhere where it'll only be executed once. launchFight() hook, which is run just once before any match starts, seems like a good choice:

hook.add("launchFight", "resetCharLifeData", f_resetData)

But actually, this could be troublesome, since launchFight() isn't called again when a match is reset using F4. To circumvent this, we'll instead call f_resetData at the start of f_matchListener using debug triggers.

More details about hook functions can be found here.

With this, our code is finished. Here's the final result:

-- Variables
local firstToLoseHP = ""
local totalPlayers = 0

-- Functions
local function f_resetData()
    firstToLoseHP = ""
    totalPlayers = 0
end

local function f_matchListener()
    -- Reset data at the start of the match
    if roundno() == 1 and roundstate() == 0 then
        f_resetData()
    end
    -- Get total players in this match
    if totalPlayers == 0 then
        for i = 1, 2 do -- Only check initial characters from both teams
            player(i)
            totalPlayers = totalPlayers + numpartner() + 1
        end
    end
   
    -- Get character data
    if roundno() == 1 then
        for i = 1, totalPlayers do
            player(i) -- Select player to examine
            if life() < 300 and firstToLoseHP == "" then
                firstToLoseHP = name()
                setLife(0)
            end
        end
    end
end

-- Hooks
hook.add("loop", "getCharLife", f_matchListener)