# Lua utility module `EventSequence`

Event sequence - a chain of functions to call at specified times, modeled after TRNG's organizers.

Works atop the Timer, and so is updated automatically pre-OnControlPhase, and saved automatically when the game is saved.

Example usage:

    local EventSequence = require("Engine.EventSequence")

    -- These will be called by the sequence
    LevelFuncs.HealLara = function()
        Lara:SetHP(Lara:GetHP()+10)
    end

    local nSpawned = 0
    LevelFuncs.SpawnBaddy = function(baddy, name, pos)
        local myBaddy = TEN.Objects.Moveable(baddy, name..nSpawned, pos, nil, 0)
        myBaddy:Enable()
        nSpawned = nSpawned + 1
    end

    -- This function triggers the sequence
    LevelFuncs.TriggerSequence = function(obj)
        local posSteve = TEN.Objects.GetMoveableByName("stevePosNullmesh"):GetPosition()
        local posChris = TEN.Objects.GetMoveableByName("chrisPosNullmesh"):GetPosition()
        local mySeq = EventSequence.Get("my_seq")
        if not mySeq then
            mySeq = EventSequence.Create("my_seq",
                false, -- does not loop
                {seconds = true, deciseconds = true}, -- timer format, see Timer for details
                6, -- seconds until call the function specified in next arg
                LevelFuncs.HealLara, -- first function to call. If we don't need to pass any arguments, we can just pass the function
                2.1, -- seconds until the next function, after the previous one has been called
                {LevelFuncs.SpawnBaddy, TEN.Objects.ObjID.BADDY1, "steve", posSteve}, -- if we DO want to pass arguments to the function to be called, we give a table with the function (LevelFuncs.SpawnBaddy in this case) followed by the args to pass to it
                0.5,
                {LevelFuncs.SpawnBaddy, TEN.Objects.ObjID.SAS_CAIRO, "chris", posChris},
                1,
                LevelFuncs.HealLara)
        end

        -- event sequences are inactive to begin with and so need to be started
        mySeq:Start()
    end

## Functions

Create(name, loop, timerFormat[, ...]) | Create (but do not start) a new event sequence.
Get(name) | Get an event sequence by its name.
mySequence:SetPaused(p) | Pause or unpause the sequence.
mySequence:IsPaused() | Get whether or not the sequence is paused
mySequence:Start() | Begin or unpause a sequence.
mySequence:Stop() | Stop the sequence.
mySequence:IsActive() | Get whether or not the sequence is active

## Functions

Create(name, loop, timerFormat[, ...])
  Create (but do not start) a new event sequence.

  ### Parameters:

  - name string A label to give the sequence; used to retrieve the timer later as well as internally by TEN.
  - loop bool if true, the sequence will start again from its first timer once its final function has been called
  - timerFormat table or bool same as in Timer. This is mainly for debugging. This will not work properly if another sequence or timer is showing a countdown.
  - ... a variable number of pairs of arguments - a time in seconds, followed by the function (must be defined in the LevelFuncs table) to call once the time has elapsed, followed by another duration in seconds, another function name, etc. You can specify a function either by its name as a string, or by a table with the function name as the first member, followed by its arguments (see above example). (optional)

  ### Returns:

  EventSequence The inactive sequence.
Get(name)
  Get an event sequence by its name.

  ### Parameters:

  - name string The label that was given to the sequence when it was created

  ### Returns:

  EventSequence The sequence
mySequence:SetPaused(p)
  Pause or unpause the sequence. If showing the remaining time on-screen, its color will be set to yellow (paused) or white (unpaused).

  ### Parameters:

  - p bool if true, the sequence will be paused; if false, it will be unpaused
mySequence:IsPaused()
  Get whether or not the sequence is paused

  ### Returns:

  bool true if the timer is paused, false if otherwise
mySequence:Start()
  Begin or unpause a sequence. If showing the remaining time on-screen, its color will be set to white.
mySequence:Stop()
  Stop the sequence.
mySequence:IsActive()
  Get whether or not the sequence is active

  ### Returns:

  bool true if the sequence is active, false if otherwise

generated by TEN-LDoc (a fork of LDoc 1.4.6)