Mod Loader API - itb-community/ITB-ModLoader GitHub Wiki

Heads up: some documentation has been moved to subpages:

Table of Contents

 

Global

 

GetScreenCenter

Returns a Point center of the screen.

 

GetHangarOrigin

Returns a Point representing hangar origin - a reference point that can be used by modded UI to position itself in the hangar in relation to game's own UI.

 

HangarGetSelectedMechs

Returns a list of pawn types that constitute the currently selected squad. Only works in the hangar.

 

GetRealDifficulty

Returns the real difficulty used by the game (the one used to calculate score). This is a direct reference to the original GetDifficulty function.

 

SetDifficulty

Argument name Type Description
difficultyLevel number The new difficulty level to set

Sets difficulty of the game to the specified level. Default valid arguments:

  • DIFF_EASY
  • DIFF_NORMAL
  • DIFF_HARD
  • DIFF_VERY_HARD
  • DIFF_IMPOSSIBLE

Example:

SetDifficulty(DIFF_VERY_HARD)

 

AddDifficulty

Argument name Type Description
id string Id of the new difficulty that also serves as its global variable name (eg. DIFF_HARD)
level number Non-negative integer level of the new difficulty.
tipTitle string Title displayed in the hangar when user hovers over this difficulty
tipText string Text displayed in the hangar when user hovers over this difficulty

Adds a new difficulty level to the game, taking care of minutae like updating texts and enemy spawners.

If there already exists a difficulty level with the same value as the level argument, the old difficulty (and all difficulties above it) will be shifted one level up to make room for the difficulty being added. Eg. adding a new difficulty as DIFF_EASY (0) will change DIFF_EASY to have a value of 1 (DIFF_NORMAL to 2, etc).

Custom difficulty levels use the same vek spawning and score rules as the vanilla difficulty level directly below them. Eg. adding a "Very Hard" difficulty level will have additional alpha Vek and increase score by 50%. Adding a "New Normal" that is between vanilla "Normal" and "Hard" will use normal vek spawning and normal score. This is called a baseline difficulty level. To get it programmatically, use GetBaselineDifficulty.

Example:

AddDifficulty(
	"DIFF_VERY_HARD",
	#DifficultyLevels, -- adds as a new highest difficulty
	"Very Hard Mode",
	"Intended for veteran Commanders looking for a challenge."
)

 

GetDifficultyId

Argument name Type Description
level number Difficulty level whose id is to be returned. Defaults to value returned by GetDifficulty() if omitted.

Returns the id of the specified difficulty level.

Example:

LOG(GetDifficultyId(DIFF_EASY)) -- prints DIFF_EASY

 

GetBaselineDifficulty

Argument name Type Description
level number Difficulty level to get the baseline difficulty for. Defaults to value returned by GetDifficulty() if omitted.

Returns the baseline difficulty level for the specified level.

A baseline difficulty level is the vanilla difficulty level that is immediately below the one specified. Eg. a custom difficulty of level 2 would sit between DIFF_NORMAL and DIFF_HARD, so its baseline difficulty level would be DIFF_NORMAL.

Example:

LOG(GetBaselineDifficulty(DIFF_VERY_HARD)) -- prints value of DIFF_HARD

 

IsVanillaDifficultyLevel

Argument name Type Description
level number Difficulty level to check. Defaults to value returned by GetDifficulty() if omitted.

Returns true if the level specified in argument is a vanilla difficulty level (DIFF_EASY, DIFF_NORMAL, DIFF_HARD), accounting for shifting done by AddDifficulty.

 

InterpolateColor

Argument name Type Description
startColor userdata Color (sdl.rgb/sdl.rgba) to start interpolating from
endColor userdata Color (sdl.rgb/sdl.rgba) to interpolate to
t number Number value in range [0, 1], specifying the intensity of endColor (0 means 100% startColor, 1 means 100% endColor)

Linearly interpolates between two color values.

Example:

local c1 = sdl.rgb(255, 0, 0) -- red
local c2 = sdl.rgb(0, 0, 255) -- blue
local c3 = InterpolateColor(c1, c2, 0.66) -- purple (84, 0, 168)

 

IsColorEqual

Argument name Type Description
c1 userdata First Color (sdl.rgb/sdl.rgba) to compare
c2 userdata Second Color (sdl.rgb/sdl.rgba) to compare

Compares two Color instances for equality.

Example:

local c1 = sdl.rgb(255, 0, 0) -- red
local c2 = sdl.rgb(0, 0, 255) -- blue
LOG(IsColorEqual(c1, c2)) -- prints 'false'

 

compare_tables

Argument name Type Description
tbl1 table First table to compare
tbl2 table Second table to compare

Compares two distinct tables for equality, checking member table fields recursively using the same function. Fields that cannot be compared (eg. userdata) are ignored. Does not explicitly account for metatables. Returns true if both tables hold the same data, false otherwise.

 

list_indexof

Argument name Type Description
list table List to search
value object The value to look for

Returns index of the value object in the specified list, or nil if not found.

 

rect_intersects

Argument name Type Description
r1 rect First rect to test for intersection
r2 rect Second rect to test for intersection

 

table:OnSerializationStart

Argument name Type Description
t table A helper table used to store temporarily removed fields

Every table that is saved to GAME, and defines this function, will have this function called whenever the game is being saved. This effectively allows to temporarily prune unserializable fields (such as raw pawn references), or transient data that should not be saved to the savefile (for example when creating custom Missions).

The t argument can be used to save the field before it is removed. The same table is then passed on to OnSerializationEnd callback, allowing to restore the field.

Example:

mytable = {}
mytable.transientField = "qwe"
mytable.OnSerializationStart = function(self, t)
	t.transientField = self.transientField
	self.transientField = nil
end

-- OR

MyMission.transientField = "qwe"
funtion MyMission:OnSerializationStart(t)
	t.transientField = self.transientField
	self.transientField = nil
end

 

table:OnSerializationEnd

Argument name Type Description
t table A helper table used to store temporarily removed fields

Every table that is saved to GAME, and defines this function, will have this function called whenever the game is being saved. This effectively allows to temporarily prune unserializable fields (such as raw pawn references), or transient data that should not be saved to the savefile (for example when creating custom Missions).

The t argument can be used to retrieve fields that were removed in OnSerializationStart callback.

Example:

mytable = {}
mytable.OnSerializationEnd = function(self, t)
	self.transientField = t.transientField
end

-- OR

function MyMission:OnSerializationEnd(t)
	self.transientField = t.transientField
end

 

RegisterRepairIconReplacement

Argument name Type Description
personalityId string Id of the pilot personality whose repair icon is to be replaced (sans the Pilot_ prefix, eg. Original)
iconPath string Path to the image that will replace the repair icon. Either in the game archives, or in the mod directory.

This function allows to define repair skill replacement icons that will be drawn on top of the vanilla repair icon.

Caveats:

  • Replacement icon shows up when the pilot of the last selected mech had a replacement registered, is deselected, and then another mech is hovered over without being selected.

Example:

RegisterRepairIconReplacement("Original", "img/weapons/repair_mantis.png")

 

GetCurrentRegion

Returns a savedata table holding information about the region the player is currently in. Returns nil when not in a mission.

 

GetCurrentMission

Returns a savedata table holding information about the current mission. Returns nil when not in a mission.

 

IsTestMechScenario

Returns true if the player is in the test mech scenario. false otherwise.

 

CreatePilotPersonality

Argument name Type Description
label string Personality label used in debug messages. Generally should be the same as the personality id
name string Name of the pilot (the person). Leave as nil for a randomly generated name (eg. for corporation pilots)

Creates an instance of PilotPersonality, which are entries in the Personality table. Useful for creating pilots and pilot dialogs purely through lua, without having to mess with ITB's CSV format.

Example:

local id = "MyPilot"
Personality[id] = CreatePilotPersonality(id)
-- You can now start adding dialog entries for this pilot
Personality[id]["Gamestart"] = {
  "This is a dialog line that's played when this is the pilot we're starting the game with.",
  "This is another dialog line. The game selects a random line from this list."
}

 

CreateStructure

Argument name Type Description
structureDefinitions table Definitions for the structure

Creates a structure with the specified structureDefinitions.

structureDefinitions is a table with the following fields:

Field Type Description
Id string A unique id for the structure
Name string The display name of the structure
Path string Directory path relative to your mod's root directory
Image string Base name of the structure image files
ImageOffset Point An offset for the structure images
Reward number The reward type recieved when protecting this structure in a mission

 

  • Make sure the Id you choose is unique, to avoid potential collisions with structures from other mods.
  • Path is a directory path; not a full path to any image files.
  • Image is not the full filename of any structure image. Structures can have an "on" state and a "broken" state. If for instance Path is "img/structures/" and Image is "bar", then the function will look for structure image files "img/structures/bar_on.png" and "img/structures/bar_broken.png"; add them to the game, and associate them with this structure.
  • ImageOffset The offset describes where to start drawing the structure image files, measured from the top corner of a board tile the structure is located in.

Valid Reward types:

Reward Description
REWARD_REP Rewards 1 reputation
REWARD_POWER Rewards 1 power
REWARD_TECH Rewards 1 core

 

Example:

CreateStructure{
	Id = "Str_Bar_Example",
	Name = "Old Earth Bar Example",
	Path = "img/structures/",
	Image = "bar",
	ImageOffset = Point(-28,-8),
	Reward = REWARD_REP
}

 

Mission:PreprocessSpawningPawn

Argument name Type Description
pawn userdata Pawn that will be spawned

Preprocesses a pawn that will be spawned on the board before its spawn point is created. This function can optionally return a Point instance to override the pawn's spawn location.

It might be possible to use this function to spawn damaged pawns, or pawns afflicted with a certain status (fire, acid, etc.), but this was not tested.

Default implementation does nothing. This function can be overridden by modded Missions to implement customized spawning logic.

Example:

function MyMission:PreprocessSpawningPawn(pawn)
	if pawn:GetType() == "Leaper1" then
		return Point(0, 0) -- force all Leapers to spawn at the top corner of the map during this mission.
	end
end

 

Mission:GetSpawnPointData

Argument name Type Description
point userdata Point on the game board, for which spawn data is to be returned

Returns spawn data of the specified point, or nil if there's no Vek spawning at that location.

Contents of the table:

Field Type Description
location userdata Point on the game board where the spawn is located
type string Type of the enemy that will be spawned
id number Id of the pawn that will be spawned. However, neither Board nor Game are aware of it before it's added to the board, so it's not particularly useful.
turns number Number of turns the spawn has been on the board (in case it's blocked repeatedly)

Example:

local p = Point(3, 5)
local spawnData = Mission:GetSpawnPointData(p)
if spawnData then
	LOG("Vek spawning at ".. p:GetString() ..": ".. spawnData.type)
else
	LOG("No Vek are spawning at ".. p:GetString())
end

 

Mission:RemoveSpawnPoint

Argument name Type Description
point userdata Spawn point location to remove

Removes the vek spawn at the specified location. The vek that was supposed to be spawned will not appear on the game board. Does nothing if there's no vek spawning at that location.

Example:

Mission:RemoveSpawnPoint(Point(3, 5))

 

Mission:MoveSpawnPoint

Argument name Type Description
point userdata Spawn point location to be moved
to userdata Location to move the spawn point to.

Moves the specified spawn point to the specified location. Does nothing if there's no vek spawning at that location.

Example:

Mission:MoveSpawnPoint(Point(3, 5), Point(3, 6))

 

Mission:ChangeSpawnPointPawnType

Argument name Type Description
point userdata Spawn point location to be changed
newPawnType string Type of the pawn that will be spawned at this spawn point

Changes the type of pawn that will be spawned at the specfiied location. Has no effect if the specified location is not an existing spawn point.

Example:

Mission:ChangeSpawnPointPawnType(Point(3, 5), "Leaper1")

 

Mission:ModifySpawnPoint

Argument name Type Description
point userdata Spawn point location to be changed
newSpawnData table Table containig new values for the spawn point

Modifies the specified spawn point, setting its properties to the values specified in the table passed in argument. Useful when you need to modify several properties of a single spawn point at once. This function has no effect if the specified location is not an existing spawn point.

Valid fields for the table passed in argument are:

  • type - sets the type of the pawn that will spawn at this spawn point. Equivalent to using Mission:ChangeSpawnPointPawn
  • location - changes the location of this spawn point. Equivalent to using Mission:MoveSpawnPoint
  • turns - overwrites the internal value storing how long the spawn point has been on the board (can be used to figure out how many times it's been blocked)

Example:

Mission:ModifySpawnPoint(Point(3, 5), {
	location = Point(5, 3),
	type = "Leaper1"
})

 

GetParentPath

Argument name Type Description
path string Path to a file or folder, separated with forward slashes: /

Takes the specified path (either a file or directory), and returns the parent directory.

Example:

LOG(GetParentPath("some_mod/cool_path/my_module"))
-- Prints 'some_mod/cool_path/'

-- The ellipsis (...), when outside of any function and in a file loaded via require(),
-- returns the path to the file that is being loaded
local dir = GetParentPath(...)
require(dir .. "another_module")

 

UpdateSaveData

Argument name Type Description
fn function Function that receives and manipulates the loaded save data

Loads the current save file into a table and passes it to the function received in argument. This allows limited save file manipulation, mostly to make runtime changes "stick" when reloading the game. Keep in mind that not all data can be modified at runtime, meaning that the actual game state will overwrite your changes to the save file the next time the game decides to save.

Example:

UpdateSaveData(function(save)
	-- Set reputation to 1000
	-- No way to modify the runtime reputation value through lua, so
	-- this change will be overwritten by the game.
	save.SquadData.money = 1000
end)

 

DoSaveGame

Forces the game to save the current board state. Only works during missions. Useful when you make changes to pawn via scripts, and need them to stick through reloads, which normally doesn't happen immediately, leading to potential desync in actual and saved states.

Example:

Pawn:SetAcid(true)
DoSaveGame()
-- If you restart the game now (without moving the pawn or doing anything else), the pawn will still be acided.

 

mouseTile

Returns the board tile that the mouse cursor is currently over, or nil if the mouse cursor is not over the board. Since this is calculated by converting screen-space position of the mouse cursor, and not obtained directly from the game, the highlighted point returned by this function may be different than the point highlighted by the game's own interface - this happens near the edges of tiles, and is typically a matter of single-pixel differences.

Example:

local point = mouseTile()
LOG("Currently hovering over", point)