# Table `Logic`

Saving data, triggering functions, and callbacks for level-specific scripts.

## Functions

AddCallback(point, func) | Register a function as a callback.
RemoveCallback(point, func) | Deregister a function as a callback.
HandleEvent(name, type, activator) | Attempt to find an event set and execute a particular event from it.
EnableEvent(name, type) | Attempt to find an event set and enable specified event in it.
DisableEvent(name, type) | Attempt to find an event set and disable specified event in it.

## Special objects

Lara | A Objects.Moveable representing Lara herself.

## Special tables

LevelVars | A table with level-specific data which will be saved and loaded.
GameVars | A table with game data which will be saved and loaded.
LevelFuncs | A table nested table system for level-specific functions.

## Functions

AddCallback(point, func)
  Register a function as a callback.

  This is intended for module/library developers who want their modules to do stuff during level start/load/end/save/control phase, but don't want the level designer to add calls to `OnStart`, `OnLoad`, etc. in their level script.

  Possible values for `point`:

      -- These take functions which accept no arguments
      PRESTART -- will be called immediately before OnStart
      POSTSTART -- will be called immediately after OnStart

      PRESAVE -- will be called immediately before OnSave
      POSTSAVE -- will be called immediately after OnSave

      PRELOAD -- will be called immediately before OnLoad
      POSTLOAD -- will be called immediately after OnLoad

      PREFREEZE -- will be called before entering freeze mode
      POSTFREEZE -- will be called immediately after exiting freeze mode

      -- These take a LevelEndReason arg, like OnEnd
      PREEND -- will be called immediately before OnEnd
      POSTEND -- will be called immediately after OnEnd

      -- These take functions which accepts a deltaTime argument
      PRELOOP -- will be called in the beginning of game loop
      POSTLOOP -- will be called at the end of game loop

      -- These take functions which accepts an objectNumber argument, like OnUseItem
      PREUSEITEM -- will be called immediately before OnUseItem
      POSTUSEITEM -- will be called immediately after OnUseItem

  The order in which two functions with the same CallbackPoint are called is undefined. i.e. if you register `MyFunc` and `MyFunc2` with `PRELOOP`, both will be called in the beginning of game loop, but there is no guarantee that `MyFunc` will be called before `MyFunc2`, or vice-versa.

  Any returned value will be discarded.

  ### Parameters:

  - point CallbackPoint When should the callback be called?
  - func LevelFunc The function to be called (must be in the LevelFuncs hierarchy). Will receive, as an argument, the time in seconds since the last frame.

  ### Usage:

      LevelFuncs.MyFunc = function(dt) print(dt) end
      TEN.Logic.AddCallback(TEN.Logic.CallbackPoint.PRELOOP, LevelFuncs.MyFunc)

RemoveCallback(point, func)
  Deregister a function as a callback. Will have no effect if the function was not registered as a callback

  ### Parameters:

  - point CallbackPoint The callback point the function was registered with. See AddCallback
  - func LevelFunc The function to remove; must be in the LevelFuncs hierarchy.

  ### Usage:

      TEN.Logic.RemoveCallback(TEN.Logic.CallbackPoint.PRELOOP, LevelFuncs.MyFunc)

HandleEvent(name, type, activator)
  Attempt to find an event set and execute a particular event from it.

  Possible event type values:

      ENTER
      INSIDE
      LEAVE
      LOAD
      SAVE
      START
      END
      LOOP
      USEITEM
      MENU

  ### Parameters:

  - name string Name of the event set to find.
  - type EventType Event to execute.
  - activator Moveable Optional activator. Default is the player object.
EnableEvent(name, type)
  Attempt to find an event set and enable specified event in it.

  ### Parameters:

  - name string Name of the event set to find.
  - type EventType Event to enable.
DisableEvent(name, type)
  Attempt to find an event set and disable specified event in it.

  ### Parameters:

  - name string Name of the event set to find.
  - type EventType Event to disable.

## Special objects

Lara
  A Objects.Moveable representing Lara herself.

## Special tables

TombEngine uses the following tables for specific things.

LevelVars
  A table with level-specific data which will be saved and loaded. This is for level-specific information that you want to store in saved games.

  For example, you may have a level with a custom puzzle where Lara has to kill exactly seven enemies to open a door to a secret. You could use the following line each time an enemy is killed:

      LevelVars.enemiesKilled = LevelVars.enemiesKilled + 1

  If the player saves the level after killing three, saves, and then reloads the save some time later, the values `3` will be put back into `LevelVars.enemiesKilled.`

  This table is emptied when a level is finished. If the player needs to be able to return to the level (like in the Karnak and Alexandria levels in The Last Revelation), you will need to use the GameVars table, below.

  LevelVars.Engine is a reserved table used internally by TombEngine's libs. Do not modify, overwrite, or add to it.

GameVars
  A table with game data which will be saved and loaded. This is for information not specific to any level, but which concerns your whole levelset or game, that you want to store in saved games.

  For example, you may wish to have a final boss say a specific voice line based on a choice the player made in a previous level. In the level with the choice, you could write:

      GameVars.playerSnoopedInDrawers = true

  And in the script file for the level with the boss, you could write:

      if GameVars.playerSnoopedInDrawers then
      	PlayAudioTrack("how_dare_you.wav")
      end

  Unlike LevelVars, this table will remain intact for the entirety of the game.

  GameVars.Engine is a reserved table used internally by TombEngine's libs. Do not modify, overwrite, or add to it.

LevelFuncs
  A table nested table system for level-specific functions.

  This serves a few purposes: it holds the level callbacks (listed below) as well as any trigger functions you might have specified. For example, if you give a trigger a Lua name of "my_trigger" in Tomb Editor, you will have to implement it as a member of this table:

      LevelFuncs.my_trigger = function()
      	-- implementation goes here
      end

  You can organise functions into tables within the hierarchy:

      LevelFuncs.enemyFuncs = {}

      LevelFuncs.enemyFuncs.makeBaddyRunAway = function()
      	-- implementation goes here
      end

      LevelFuncs.enemyFuncs.makeBaddyUseMedkit = function()
      	-- implementation goes here
      end

  There are two special subtables which you should not overwrite:

      LevelFuncs.Engine -- this is for 'first-party' functions, i.e. ones that come with TombEngine.
      LevelFuncs.External -- this is for 'third-party' functions. If you write a library providing LevelFuncs functions for other builders to use in their levels, put those functions in LevelFuncs.External.YourLibraryNameHere

  The following are the level callbacks. They are optional; if your level has no special behaviour for a particular scenario, you do not need to implement the function. For example, if your level does not need any special initialisation when it is loaded, you can just leave out `LevelFuncs.OnStart`.

  The order of loading is as follows:

  1. The level data itself is loaded.
  2. The level script itself is run (i.e. any code you put outside the LevelFuncs callbacks is executed).
  3. Save data is loaded, if saving from a saved game (will empty LevelVars and GameVars and repopulate them with what they contained when the game was saved).
  4. If loading from a save, `OnLoaded` will be called. Otherwise, `OnStart` will be called.
  5. The control loop, in which `OnLoop` will be called once per frame, begins.

  ### Fields:

  - OnStart function Will be called when a level is entered by completing a previous level or by selecting it in the menu. Will not be called when loaded from a saved game.
  - OnLoad function Will be called when a saved game is loaded, just after data is loaded
  - OnLoop function(float) Will be called during the game's update loop, and provides the delta time (a float representing game time since last call) via its argument.
  - OnSave function Will be called when the player saves the game, just before data is saved
  - OnEnd function

    (EndReason) Will be called when leaving a level. This includes finishing it, exiting to the menu, or loading a save in a different level. It can take an `EndReason` arg:

        EXITTOTITLE
        LEVELCOMPLETE
        LOADGAME
        DEATH
        OTHER

    For example:

        LevelFuncs.OnEnd = function(reason)
            if(reason == TEN.Logic.EndReason.DEATH) then
                print("death")
            end
        end

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