-
Notifications
You must be signed in to change notification settings - Fork 17
Mod Loader API
Heads up: some documentation has been moved to subpages:
- GetScreenCenter
- GetHangarOrigin
- HangarGetSelectedMechs
- GetRealDifficulty
- SetDifficulty
- AddDifficulty
- GetDifficultyId
- GetBaselineDifficulty
- InterpolateColor
- IsColorEqual
- compare_tables
- list_indexof
- rect_intersects
- table:OnSerializationStart
- table:OnSerializationEnd
- RegisterRepairIconReplacement
- GetCurrentRegion
- GetCurrentMission
- IsTestMechScenario
- CreatePilotPersonality
- CreateStructure
- Mission:PreprocessSpawningPawn
- Mission:GetSpawnPointData
- Mission:RemoveSpawnPoint
- Mission:MoveSpawnPoint
- Mission:ChangeSpawnPointPawnType
- Mission:ModifySpawnPoint
- GetParentPath
- UpdateSaveData
- DoSaveGame
- mouseTile
Returns a Point
center of the screen.
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.
Returns a list of pawn types that constitute the currently selected squad. Only works in the hangar.
Returns the real difficulty used by the game (the one used to calculate score). This is a direct reference to the original GetDifficulty
function.
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)
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."
)
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
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
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
.
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)
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'
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.
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.
Argument name | Type | Description |
---|---|---|
r1 |
rect | First rect to test for intersection |
r2 |
rect | Second rect to test for intersection |
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
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
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")
Returns a savedata table holding information about the region the player is currently in. Returns nil
when not in a mission.
Returns a savedata table holding information about the current mission. Returns nil
when not in a mission.
Returns true
if the player is in the test mech scenario. false
otherwise.
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."
}
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 instancePath
is "img/structures/" andImage
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
}
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
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
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))
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))
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")
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 usingMission:ChangeSpawnPointPawn
-
location
- changes the location of this spawn point. Equivalent to usingMission: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"
})
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")
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)
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.
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)