Lua Scripting API Game Triggers - melindil/FTSE GitHub Wiki

What are triggers?

In certain places in the Fallout Tactics code, we may want to add customized behavior. This could be at game startup, when a game variable changed, when an attack takes place, etc. FTSE provides a number of conditions for which a specifically-named Lua function will be called. The Lua code can then make use of the FTSE exported functions, plus any other Lua functionality, to customize behavior of the game engine.

Defined trigger functions in FTSE

OnStart

function OnStart()
  -- your code here
end

OnStart is called at the very beginning of the BOS.EXE startup, just after command line arguments are parsed, and after any hex patches defined in the FTSE configuration file are applied. Because the game has not yet initialized, only a subset of API calls may be made. At present, only the following function(s) can be called:

  • hookexecutor:ReplacePerk
  • logger:log

Example: See the example Custom Perk: Hulk Smash!.

OnLocaleLoad

function OnLocaleLoad()
  -- your code here
end

OnLocaleLoad is called after all of the game's locale .txt files have been loaded. It provides a hook for the Lua code to add new localized strings, so that they do not have to be added directly to the .txt files.

The following API functions can be called from OnLocaleLoad:

  • hookexecutor:AddLocaleString
  • logger:log

Example: See the example Custom Perk: Hulk Smash!.

DefaultStyleChanges

function DefaultStyleChanges(style)
  -- your code here
end

The DefaultStyleChanges trigger is called when the game initialized its color and font settings for menus, buttons, etc. This allows the Lua script to change these (only colors are supported so far).

The "style" parameter is a Style object, which contains functions that allow setting appearance values for the default style elements. See the documentation for Style for more details.

Allowed functions to use inside DefaultStyleChanges:

  • style:*
  • logger:log

Example:

function DefaultStyleChanges(style)
  style:SetColorDefaultText(0.9,0.6,0.0)
  style:SetColorHighlightText(1.0,1.0,0.0)
  style:SetColorOptionsPages(1.0,1.0,1.0)
  style:SetColorPanelTitles(1.0,1.0,1.0)
  style:SetColorBuffs(0.0,0.2,1.0)
  style:SetColorDebuffs(0.0,1.0,0.0)
  style:SetColorTags(0.45,0.3,0)
end

OnLongTick

function OnLongTick(actor)
  -- your code here
end

Inside the Fallout Tactics engine, there is a routine that is called for every Actor object for each 10 seconds of game time that passes. OnLongTick allows the Lua code to execute behaviors for Actors within that routine.

The parameter to the function is an Actor object, which provides information about which actor has reached the 10-second timer, and provides functions for operating with the in-game Actor object.

Since the game engine is guaranteed to have been started prior to this trigger firing, any FTSE function can be called by OnLongTick.

Example: See the example Custom Perk: Hulk Smash!.

OnRadiated

function OnRadiated(actor)
  -- your code here
end

This trigger is called whenever an actor has its radiation counter updated due to standing in/near a radiated area.

The parameter to the function is an Actor object, which provides information about which actor has taken the radiation effect.

Since the game engine is guaranteed to have been started prior to this trigger firing, any FTSE function can be called by OnRadiated.

Example: See the example Custom Perk: Hulk Smash!.

OnVariableChanged

function OnVariableChanged(key,value,campaign)
  -- your code here
end

The OnVariableChanged trigger is called whenever any mission or campaign variable has had its value changed. The variable name is passed in the "key" parameter, its new value passed in the "value" parameter, and the "campaign" parameter is a Boolean flag indicating if the variable changed is a CVAR (true) or mission variable (false).

Since the game engine is guaranteed to have been started prior to this trigger firing, any FTSE function can be called by OnVariableChanged.

Example: See the example Using Mission Variables to Grant Perks.

MsecToDayHMS

function MsecToDayHMS(ms,scale)
  -- your code here
end

This trigger is called whenever the game engine needs to convert its internal millisecond timer to game time. This will allow Lua scripts to redefine time information within the game (e.g. to change the length of minutes, hours, or days).

Note that only minimal testing has been done with changing time calculation, so there may still be bugs in this area.

The "ms" parameter is the current game timer in milliseconds, and the "scale" parameter is a Boolean flag indicating whether the in-game scale factor should be applied in the calculation (one real-time second = 3 seconds on the displayed game time).

The function must return a table with the millisecond timer being expanded into the following fields (all are case sensitive):

  • year (must be 0)
  • month (must be 0)
  • day
  • hour
  • minute
  • second
  • msec

Example: See the example Custom Perk: Night Person.

AddBaseToGameTime

function AddBaseToGameTime(gametime)
  -- your code here
end

This function is called whenever the game needs to convert the days, hours, minutes, and seconds of the game timer into an actual formatted date/time. This includes adding the base start time for the campaign (Jan 1 2197 06:29:00), and counting days into years and months. The trigger allows for Lua code to change these calculations (e.g. to implement a new calendar system).

Note that only minimal testing has been done with changing time calculation, so there may still be bugs in this area.

The single parameter is a table of the expanded game time (as returned by MsecToDayHMS). This table should be modified to the correct values for year, month, day, etc., and that object returned to the caller.

Example: See the example Custom Perk: Night Person.