Skip to content

modApi

Jump to bottom Edit New page
tos-x edited this page Mar 10, 2023 · 18 revisions

Table of Contents

 

Animation Helpers

Helper functions to create animations in bulk.

 

modApi:createAnimations

Argument name Type Description
animDefs table Definitions of the animations being created

The animDefs object, passed as first argument, is a list of table objects we will refer to as animDef objects. All animDef objects in the animDefs object must have a named table key. This key will become the name of the animation.

The animDef objects must have the following fields:

Field Type Description
Image string Path to the image file, with "img/" omitted

 

The animDef objects may have the following additional fields:

Field Type Default Description
Base string "Animation" Alternate base animation
PosX number 0 X Offset from the top corner of a tile
PosY number 0 Y Offset from the top corner of a tile
NumFrames number 1 Number of frames to divide the image into in horizontal direction
Height number nil Number of color variations to divide the image into
Loop boolean false Whether the animation loops
Time number 1.0 Time in seconds to display each frame
Layer number LAYER_SKY Defined animation layer - LAYER_BACK, LAYER_FRONT, LAYER_SKY or LAYER_FLOOR
Sound string "" Path to sound played when creating the animation
Frames number table nil Table of frame to display in order
Lengths number table nil Table of duration to display each frame
CenterX number nil Alternate way to set PosX. Which pixel x should align to the center of a tile
CenterY number nil Alternate way to set PosY. Which pixel y should align to the center of a tile

 

Adds animations for all defined animDef objects.

Example:

modApi:createAnimations{
	example_deployment_arrow = {
		Image = "combat/deployment_arrow.png",
	},
	example_deployment_swap = {
		Image = "combat/deployment_swap.png",
	},
}

 

modApi:createMechAnimations

Argument name Type Description
animDefs table Definitions of the animations being created

The animDefs object, passed as first argument, is a list of table objects we will refer to as animDef objects. All animDef objects in the animDefs object must have a named table key. This key will become the name of the animation.

Adds mech animations for all defined animDef objects.

Internally creates animations like modApi:createAnimations with a few exceptions:

  • If Base is not defined in an animation, the base MechUnit will be used, which is the default animation base for mech units
  • If Image is not defined in an animation, Image will be set to "units/player/"..key..".png"

 

Example:

modApi:createVekAnimations{
	example_enemy = {
		-- Image will automatically be set to "units/aliens/example_enemy.png"
		PosX = 0,
		PosY = 0,
	},
	example_enemya = {
		-- Image will automatically be set to "units/player/example_enemya.png"
		PosX = 0,
		PosY = 0,
	},
}

 

modApi:createVekAnimations

Argument name Type Description
animDefs table Definitions of the animations being created

The animDefs object, passed as first argument, is a list of table objects we will refer to as animDef objects. All animDef objects in the animDefs object must have a named table key. This key will become the name of the animation.

Adds vek animations for all defined animDef objects.

Internally creates animations like modApi:createAnimations with a few exceptions:

  • If Base is not defined in an animation, the base EnemyUnit will be used, which is the default animation base for enemy units
  • If Image is not defined in an animation, Image will be set to "units/aliens/"..key..".png"

 

Example:

modApi:createMechAnimations{
	example_mech = {
		-- Image will automatically be set to "units/player/example_mech.png"
		PosX = 0,
		PosY = 0,
	},
	example_mecha = {
		-- Image will automatically be set to "units/player/example_mecha.png"
		PosX = 0,
		PosY = 0,
	},
}

 

Asset Helpers

Helper functions to append assets in bulk to resource.dat.

 

modApi:appendAssets

Argument name Type Description
appendPath string Path inside resource.dat where your assets should be placed
path_relativeToMod string Path relative to the mod's resource path
prefix string A prefix to add to each image file when appended

Appends all image files in the directory specified by path_relativeToMod. The path_relativeToMod is relative to the mod folder of the mod calling this function.

The images will be placed inside resource.dat at the location specified by appendPath, in order for the game to be able to access the images.

An optional argument prefix can be specified to prefix all files added with this string, in order to make them more unique, avoiding collisions with other mods.

Example:

modApi:appendAssets("img/units/player/", "img/units/player/", "example_")

 

modApi:appendBotAssets

Alias of modApi:appendBotUnitAssets

 

modApi:appendBotUnitAssets

Argument name Type Description
path_relativeToMod string Path relative to the mod's resource path
prefix string A prefix to add to each image file appended from the mod

Calls modApi:appendAssets("img/units/snowbots/", path_relativeToMod, prefix)

Places all images in the correct place for bot unit images, which is "img/units/snowbots/"

Example:

modApi:appendBotUnitAssets("img/units/snowbots/", "example_")

 

modApi:appendCeoPortraitAssets

Argument name Type Description
path_relativeToMod string Path relative to the mod's resource path
prefix string A prefix to add to each image file appended from the mod

Calls modApi:appendAssets("img/portraits/ceo/", path_relativeToMod, prefix)

Places all images in the correct place for ceo portrait images, which is "img/portraits/ceo/"

Example:

modApi:appendCeoPortraitAssets("img/portraits/ceo/", "example_")

 

modApi:appendCombatAssets

Argument name Type Description
path_relativeToMod string Path relative to the mod's resource path
prefix string A prefix to add to each image file appended from the mod

Calls modApi:appendAssets("img/combat/", path_relativeToMod, prefix)

Places all images in the correct place for combat images, which is "img/combat/"

Example:

modApi:appendCombatAssets("img/combat/", "example_")

 

modApi:appendCombatIconAssets

Argument name Type Description
path_relativeToMod string Path relative to the mod's resource path
prefix string A prefix to add to each image file appended from the mod

Calls modApi:appendAssets("img/combat/icons/", path_relativeToMod, prefix)

Places all images in the correct place for combat images, which is "img/combat/icons/"

Example:

modApi:appendCombatIconAssets("img/combat/icons/", "example_")

 

modApi:appendEffectAssets

Argument name Type Description
path_relativeToMod string Path relative to the mod's resource path
prefix string A prefix to add to each image file appended from the mod

Calls modApi:appendAssets("img/effects/", path_relativeToMod, prefix)

Places all images in the correct place for effect images, which is "img/effects/"

Example:

modApi:appendEffectAssets("img/effects/", "example_")

 

modApi:appendEnemyPortraitAssets

Argument name Type Description
path_relativeToMod string Path relative to the mod's resource path
prefix string A prefix to add to each image file appended from the mod

Calls modApi:appendAssets("img/portraits/enemy/", path_relativeToMod, prefix)

Places all images in the correct place for effect images, which is "img/portraits/enemy/"

Example:

modApi:appendEnemyPortraitAssets("img/portraits/enemy/", "example_")

 

modApi:appendEnemyUnitAssets

Argument name Type Description
path_relativeToMod string Path relative to the mod's resource path
prefix string A prefix to add to each image file appended from the mod

Calls modApi:appendAssets("img/units/aliens/", path_relativeToMod, prefix)

Places all images in the correct place for effect images, which is "img/units/aliens/"

Example:

modApi:appendEnemyUnitAssets("img/units/aliens/", "example_")

 

modApi:appendMechAssets

Alias of modApi:appendPlayerUnitAssets

 

modApi:appendMissionUnitAssets

Argument name Type Description
path_relativeToMod string Path relative to the mod's resource path
prefix string A prefix to add to each image file appended from the mod

Calls modApi:appendAssets("img/units/mission/", path_relativeToMod, prefix)

Places all images in the correct place for effect images, which is "img/units/mission/"

Example:

modApi:appendMissionUnitAssets("img/units/mission/", "example_")

 

modApi:appendNpcPortraitAssets

Argument name Type Description
path_relativeToMod string Path relative to the mod's resource path
prefix string A prefix to add to each image file appended from the mod

Calls modApi:appendAssets("img/portraits/npcs/", path_relativeToMod, prefix)

Places all images in the correct place for effect images, which is "img/portraits/npcs/"

Example:

modApi:appendNpcPortraitAssets("img/portraits/npcs/", "example_")

 

modApi:appendPassiveWeaponAssets

Argument name Type Description
path_relativeToMod string Path relative to the mod's resource path
prefix string A prefix to add to each image file appended from the mod

Calls modApi:appendAssets("img/weapons/passives/", path_relativeToMod, prefix)

Places all images in the correct place for effect images, which is "img/weapons/passives/"

Example:

modApi:appendPassiveWeaponAssets("img/weapons/passives/", "example_")

 

modApi:appendPilotPortraitAssets

Argument name Type Description
path_relativeToMod string Path relative to the mod's resource path
prefix string A prefix to add to each image file appended from the mod

Calls modApi:appendAssets("img/portraits/pilots/", path_relativeToMod, prefix)

Places all images in the correct place for effect images, which is "img/portraits/pilots/"

Example:

modApi:appendPilotPortraitAssets("img/portraits/pilots/", "example_")

 

modApi:appendPlayerUnitAssets

Argument name Type Description
path_relativeToMod string Path relative to the mod's resource path
prefix string A prefix to add to each image file appended from the mod

Calls modApi:appendAssets("img/units/player/", path_relativeToMod, prefix)

Places all images in the correct place for effect images, which is "img/units/player/"

Example:

modApi:appendPlayerUnitAssets("img/units/player/", "example_")

 

modApi:appendVekAssets

Alias of modApi:appendEnemyUnitAssets

 

modApi:appendWeaponAssets

Argument name Type Description
path_relativeToMod string Path relative to the mod's resource path
prefix string A prefix to add to each image file appended from the mod

Calls modApi:appendAssets("img/weapons/", path_relativeToMod, prefix)

Places all images in the correct place for effect images, which is "img/weapons/"

Example:

modApi:appendWeaponAssets("img/weapons/", "example_")

Assets

Functions related to assets in resource.dat.

 

modApi:appendAsset

Argument name Type Description
resource string Path inside resource.dat where your asset should be placed. Use forward slahes (/).
filePath string Path to the asset in local filesystem. A common practice is to prepend self.resourcePath (which is the root directory of your mod) to the path.

Adds an asset (image or font) to the game (by putting it into resources/resource.dat file). All calls to this function must be inside your mod's init function.

Example:

modApi:appendAsset("img/weapons/Whip.png",self.resourcePath.."/weapons/Whip.png")

 

modApi:copyAsset

Argument name Type Description
src string Path inside resource.dat, specifying the file to be copied. Use forward slahes (/).
dst string Path inside resource.dat, specifying the destination the file will be copied to.

Copies an existing asset within the resource.dat archive to another path within the resource.dat archive. Can overwrite existing files. All calls to this function must be inside your mod's init function.

Example:

-- replaces reactor core image with The Button
modApi:copyAsset("img/weapons/support_destruct.png", "img/weapons/reactor_core.png")

 

modApi:readAsset

Argument name Type Description
resource string Path inside resource.dat where your asset should be placed. Use forward slahes (/).

Reads the specified file from the resource.dat archive, and returns its contents as a string. Throws an error if the file could not be found. All calls to this function must be inside your mod's init function.

Example:

modApi:readAsset("img/units/player/mech_punch.png")

 

modApi:writeAsset

Argument name Type Description
resource string Path inside resource.dat where your asset should be placed. Use forward slahes (/).
content string String content to be written to the file

Writes a file with the specified content to the resource.dat archive, either creating a new file or overwriting one if it already exists. All calls to this function must be inside your mod's init function.

 

Configuration and Save Data

Functions related to reading and writing data in save data, including mod configuration.

 

modApi:addGenerationOption

Argument name Type Description
id string Identifier for the option
name string Name of the option that will be shown to the player
tip string Tooltip text shown when hovering over this option. Can be nil.
data table Table describing the option. Defaults to a checkbox option if omitted.

Adds a new configuration option to the mod that is currently being initialized by the mod loader.

Example:

local function init(self)
	modApi:addGenerationOption(
		"someCheckbox",
		"Some Checkbox Option",
		"This is a checkbox option that can be switched on and off. It is unchecked by default.",
		{ enabled = false }
	)

	modApi:addGenerationOption(
		"someCheckbox2",
		"Another Checkbox Option",
		"This is a checkbox option that can be switched on and off. It is checked by default.",
		{}
	)

	modApi:addGenerationOption(
		"someDropdown",
		"Some Dropdown Option",
		"This is a dropdown in which the user can select one of multiple values.",
		{
			-- Internal values of the options
			values = { 1, 2, "a string", true },

			-- Names of the options that will be shown to the player.
			-- Defaults to a string representation of the entry from `values` table
			-- if there's no entry in the `strings` table at the corresponding index.
			strings = { "Option 1", "Option 2", "Option 3", "Option 4" },

			-- Tooltips for the options that will be shown to the player.
			-- Defaults to no tooltips if omitted (either the entire table,
			-- or entry for a particular option). Can pad with nil if no
			-- tooltips are desired for earlier options.
			tooltips = { "Tooltip for Option 1", nil, "Tooltip for Option 3" },

			-- The value that is selected by default.
			-- Defaults to the first entry in the `values` table if omitted.
			value = "a string"
		}
	)
end

local function load(self, options, version)
	if options["someCheckbox"].enabled then
		LOG("Some Checkbox Option is checked")
	end

	if options["someCheckbox2"].enabled then
		LOG("Another Checkbox Option is checked")
	end

	LOG("Selected multivalue option: " .. options["someDropdown"].value)
end

 

modApi:loadSettings

Reloads the settings file to have access to selected settings from in-game lua scripts. Generally you shouldn't have to call this, the mod loader reloads the file on its own and stores the result in global Settings table.

If you need to be notified when settings change, see settingsChangedHook.

Example:

local settings = modApi:loadSettings()

 

modApi:loadProfile

Reloads profile data of the currently selected profile. Generally you shouldn't have to call this, the mod loader reloads the profile data on its own and stores the result in global Profile table.

Example:

local profile = modApi:loadProfile()

 

modApi:readModData

Argument name Type Description
id string Key the data will be saved as in the modded settings table

Reads the object under the specified key from modcontent.lua file in game's savedata directory.

Example:

local diff = modApi:readModData("CustomDifficulty")

 

modApi:writeModData

Argument name Type Description
id string Key the data will be saved as in the modded settings table
obj object A lua object to store in the modded settings table

Stores the specified object under the specified key in modcontent.lua file in game's savedata directory.

Example:

local diff = GetDifficulty()
modApi:writeModData("CustomDifficulty", level)

 

modApi:readProfileData

Argument name Type Description
id string Key of the data to be retrieved from the modded profile table

Reads the object under the specified key from modcontent.lua file in the currently selected profile's directory.

Example:

local diff = modApi:readProfileData("CustomDifficulty")

 

modApi:writeProfileData

Argument name Type Description
id string Key the data will be saved as in the modded profile table
obj object A lua object to store in the modded profile table

Stores the specified object under the specified key in modcontent.lua file in the currently selected profile's directory.

Example:

local diff = GetDifficulty()
modApi:writeProfileData("CustomDifficulty", level)

 

modApi:getCurrentMod

Returns the table of the mod that's currently being initialized or loaded. Throws an error when attempting to use outside of metadata, init or load contexts.

 

modApi:getModOptions

Argument name Type Description
id string Id of the mod for which you want to retrieve options. Optional, required when called outside of mod initialization context.

Returns the options table of the mod that's currently being initialized or loaded. When used outside of metadata, init or load contexts, this function requires providing the id of the mod you're interested in.

IMPORTANT NOTE: Due to a bug, this function will always cause an error when no mod id is specified.

Example:

-- in init() function, or functions called from it
local options = modApi:getModOptions()

-- in other functions
local options = modApi:getModOtions("my_mod_id")

 

Content

Functions related to adding content to the vanilla game.

 

modApi:addMap

Argument name Type Description
mapPath string Path to the map file.

Copies the specified map to the game's maps/ directory. Cannot overwrite default (vanilla) maps. Call in your mod's init() function.

This function ignores the file's parent directories, and only takes the filename into consideration. some/long/path/to/mymap.map and path/mymap.map will both be copied to maps/mymap.map.

Example:

local function init(self)
	modApi:addMap(self.resourcePath .. "maps/somemap.map")
end

 

modApi:addSquad

Argument name Type Description
squad table A table with 4 values - text identifier of the squad, followed by three mech text identifiers. Each mech mentioned must exist as a global variable, created similarly to game's mechs in pawns.lua file. Optional: id can also be specified in order to link the squad to an achievement
name string Name of the squad displayed to user.
desc string Description of the squad displayed to user.
icon string Icon used in custom squad selection UI.

Adds a new squad to the game.

Example:

modApi:addSquad(
    {
        id = "AUTO_Chess",
        "Chess Squad",
        "AUTO_King",
        "AUTO_Knight",
        "AUTO_Rook"
    },
    "Chess Squad",
    "Chess piece themed mechs.",
    self.resourcePath.."/icon.png"
)

 

modApi:addWeaponDrop

This function can be invoked using either named or positional arguments.

Positional

Argument name Type Description
id string ID of the weapon to add, should be the name of a global variable containing a skill
enabled boolean Sets the default enabled status of this weapon. Defaults to true if unset.

Adds a weapon to the weapon deck, causing it to appear in shops, time pods, and perfect island bonuses.

The enabled parameter will determine the default enabled status of this weapon, though that can be overridden by the Weapon Deck UI. If called multiple times with the same ID, the latest value will overwrite earlier values unless enabled is unset.

Example:

modApi:addWeaponDrop("MyWeapon", true)

Named (2.7.0+)

Argument name Type Description
id string ID of the weapon to add, should be the name of a global variable containing a skill
shop boolean/string Sets whether this weapon is available in shops at the end of islands.
pod boolean/string Sets whether this weapon is available in time pods and as perfect island rewards.

Adds a weapon to the weapon deck, appearing in shops and time pods based on the passed arguments.

Both pod and shop can be set to true, false, "normal", or "advanced". true makes it available in both normal and advanced edition weapon decks. false makes it available in neither. "normal" and "advanced" make it available in only the respective deck.

Example:

modApi:addWeaponDrop{id = "MyWeapon", pod = true, shop = "advanced" }

modApi:getWeaponDeck

Gets the full list of weapons that will be added to the weapon deck at the start of new runs.

 

modApi:isDefaultWeapon

Argument name Type Description
id string ID of the weapon to add, should be the name of a global variable containing a skill

Returns true if the weapon is available in the weapon deck in the default (vanilla) game. Returns false for mod added weapons or vanilla weapons that are normally unavailable.

 

modApi:addPilotDrop

Argument name Type Description
id string ID of the pilot to add, should be the name of a global variable containing a pilot.
pod boolean/string Sets whether this pilot is available in time pods and as perfect island rewards.
recruit boolean Sets whether this pilot is available as one of the two starting recruits.
ftl boolean Sets whether this pilot is available in secret FTL time pods.

Adds a pilot to be available in time pods, perfect island rewards, FTL time pods, and as a starting recruit. By default, all pilots in Pilot_Recruits are automatically added to the recruit deck, and all pilots in PilotListExtended (from CreatePilot) are automatically added to the time pod deck if their rarity is nonzero. By default, pilots are not added to the FTL time pod deck.

pod can be set to true, false, "normal", or "advanced". true makes it available in both normal and advanced edition pilot decks. false makes it available in neither. "normal" and "advanced" make it available in only the respective deck. This feature is not available for recruits or FTL pilots.

Example:

modApi:addPilotDrop{id = "Pilot_ID", pod = "advanced" }
modApi:addPilotDrop{id = "FTL_ID", pod = false, ftl = true }

 

modApi:deltaTime

Returns time between frames in milliseconds. For 60 FPS, this is 16ms. For 30 FPS, this is 33ms.

 

modApi:elapsedTime

Returns the amount of time that has passed since the game has been launched, in milliseconds.

 

modApi:loadIntoEnv

Argument name Type Description
path string Path to the file to load.
envTable table The environment the file will be loaded to. Will hold all global variables the file defines. Can be omitted, defaulting to an empty table.

Loads the specified file, loading any global variable definitions into the specified table instead of the global namespace (_G). The file can still access variables defined in _G, but not write to them by default (unless specifically doing _G.foo = bar).

Return value of the loaded file is ignored by this function.

Example:

local env = modApi:loadIntoEnv("some/file.lua")
GlobalVar = env.var1       -- this variable will be accessible globally
local localVar = env.var2  -- this variable will not

 

modApi:runInEnv

Argument name Type Description
script string or function The script to execute, either in the form of a string or an argumentless function.
envTable table The environment the script will be executed in. Will hold all global variables the script defines. Can be omitted, defaulting to an empty table.

Executes the function or script inside of a sandboxed environment, (hopefully completely) separate from the "real" environment used by the game.

This function returns 3 values, in the specified order:

  • the table that served as the global table for the script, which holds all globals it defined;
  • boolean value indicating whether an error occurred during the script's exeuction;
  • result of the script's execution (if it returned any value, and no error occurred), or error text if an error occurred.

Example 1:

local env, ok, result = modApi:runInEnv("return 5")

if ok then
	-- happy path, use the script's result
	LOG(5 + result)
else
	-- script failed, handle errors
	LOG(result)
end

Example 2:

local myVar = 5
local function myScript()
	myVar = 10
	LOG("Value of myVar in script's environment:", myVar)
end

local env, ok, result = modApi:runInEnv(myScript)
LOG("Value of myVar in real environment:", myVar)

 

modApi:isVersion

Argument name Type Description
version string Version to test
comparedTo string Version to compare the first argument to. Defaults to mod loader's version if omitted.

Returns true if version argument is less than or equal to comparedTo. False otherwise.

Example:

if modApi:isVersion("2.1.1") then
	LOG("Mod loader is version 2.1.1 or higher.")
end

-- ...

someModVersion = "1.2"
if modApi:isVersion("1.1", someModVersion) then
	LOG("someMod is version 1.1 or higher, we can use stuff added in this version")
else
	LOG("Whoops, someMod is lower version than 1.1, we need to use some compatibility fall-back plan, or we just fail to load.")
end

 

Pop Events

Functions related to working with pop events in the game.

 

modApi:addPopEvent

Argument name Type Description
event string Event id, text identifier specifying which exactly event is being extended. Possible values for event are: "Opening", "Closing", "Closing_Dead", "Closing_Perfect", "Closing_Bad", "Threatened", "Killed", "Shielded", "Frozen"
msg string Text displayed to user. Inside the string, #squad and #corp can be used to refer to current squad name and coropration name respectively.

Registers PopEvent, the text shown near cities when certain actions happen ("The mechs are here, we're saved!", "Get away from the windows!").

 

modApi:setPopEventOdds

Argument name Type Description
event string Event id
msg number A number from 0 to 100 indicating the probability of the PopEvent happening.

Sets the probability of the PopEvent occuring.

 

modApi:addOnPopEvent

Argument name Type Description
fn function Function to be called when the event occurs.

Registers the function to be called when a PopEvent occurs. This function is called with 5 arguments, once for each text in the PopEvent.

Arguments to the function are:

Argument name Type Description
text string The text to be displayed to user.
texts table List of all texts registered for that event (and the first argumkent is one of them).
i number index of text in texts list.
event string Event id.
count number How many texts the game is expecting.

The function should modify (or leave as it is) and return its first argument - the text displayed to user.

Example:

function modApi:addOnPopEvent(function(text, texts, i, event, count)
    return text.."!!!"
end)

 

Scheduling

Functions related to scheduling logic around game timing.

 

modApi:scheduleHook

Argument name Type Description
msTime number Time in which the function is to be invoked, in milliseconds. Measured from the moment this function is called
fn function Argumentless function which will be invoked when the amount of time specified in the first argument has elapsed.

Schedules a function to be invoked at a later time. This can be used to perform delayed operations, mostly related to UI or mod management, or as a way to work around some hooks' limitations.

Keep in mind that these hooks are not retained when the player exits the game, so hooks scheduled to happen in a long time (like a minute) may end up never being executed if the player quits the game in the meantime.

Example:

LOG("This message is printed right away!")

modApi:scheduleHook(1000, function()
	LOG("This message is printed a second later!")
end)

 

modApi:conditionalHook

Argument name Type Description
conditionFn function Argumentless predicate function evaluated once every frame
fn function Argumentless function which will be invoked when the function specified by conditionFn argument returns true.
remove boolean Whether the hook should be removed once it is triggered. Defaults to true if omitted.

Registers a conditional hook which will be executed once the condition function associated with it returns true. By default, the hook is removed once it is triggered.

Example:

-- This hook gets fired when a Combat Mech is selected
modApi:conditionalHook(
	function()
		return Pawn and Pawn:GetType() == "PunchMech"
	end,
	function()
		LOG("Punch mech selected")
	end
)

 

modApi:runLater

Argument name Type Description
fn function Argumentless function which will be invoked on game's next update step.

Executes the function on the game's next update step. Only works during missions.

Calling this during game loop (either in a function called from missionUpdate, missionUpdateHook, or as a result of previous runLater) will correctly schedule the function to be invoked during the next update step (not the current one).

Example:

local pawn = Board:GetPawn(Point(0, 0))

local d = SpaceDamage(Point(0, 0))
d.iFire = EFFECT_CREATE
Board:DamageSpace(d)

LOG(pawn:IsFire()) -- prints false, the tile's Fire status was
                   -- not applied to the pawn yet (this happens
                   -- during the game's update step)

modApi:runLater(function()
	LOG(pawn:IsFire()) -- prints true, the game already went
	                   -- through its update step and applied
	                   -- the Fire status to the pawn
end)

 

String Utilities

Functions for working with strings.

 

modApi:splitString

Argument name Type Description
input string The string to be split
separator string The string to split by. Defaults to whitespace if omitted

Splits the input string around the provided separator string, and returns a table holding the split string. Does not include empty strings.

 

modApi:splitStringEmpty

Argument name Type Description
input string The string to be split
separator string The string to split by. Defaults to whitespace if omitted

Splits the input string around the provided separator string, and returns a table holding the split string. Includes empty strings.

 

modApi:trimString

Argument name Type Description
input string The string to be trimmed

Trims leading and trailing whitespace from the string.

Example:

LOG(modApi:trimString("   some text !   ")) -- prints 'some text !'

 

modApi:stringStartsWith

Argument name Type Description
input string The string to test
prefix string The prefix string that the input string should be starting with

Returns true if the input string starts with the prefix string.

Example:

local string = "PunchMech"
if modApi:stringStartsWith(string, "Punch") then
	LOG("It does")
end

 

modApi:stringEndsWith

Argument name Type Description
input string The string to test
suffix string The suffix string that the input string should be ending with

Returns true if the input string ends with the suffix string.

Example:

local string = "PunchMech"
if modApi:stringEndsWith(string, "Mech") then
	LOG("It does")
end

 

Texts and Localization

Functions for adding texts to the game or working with localization.

 

modApi:addWeapon_Texts

Argument name Type Description
tbl table Table with as many key-value string pairs as you need.

Registers strings related to weapons with the game.

Weapons you create in mods are stored in global variables, and you use names of those variables to equip pawns. For every weapon, the game requires some strings to be defined, or can misbehave, or even crash. If a weapon is stored in vartable WeaponName, the game expects strings WeaponName_Name and WeaponName_Description to be registered. If a weapon has one upgrade, WeaponName_Upgrade1 and WeaponName_A_UpgradeDescription must be registered, and with two upgrades, the game requires two more strings: WeaponName_Upgrade2 and WeaponName_B_UpgradeDescription. The description for each string is in the table below.

String Description
WeaponName_Name Name of the weapon displayed to user.
WeaponName_Description Description of the weapon displayed to user.
WeaponName_Upgrade1 Short description of the first upgrade. Make it less than about 12 characters, or it won't fit
WeaponName_A_UpgradeDescription Long description of the first upgrade.
WeaponName_Upgrade2 Short description of the second upgrade. Same restrictions apply.
WeaponName_B_UpgradeDescription Long description of the second upgrade.

Example:

modApi:addWeapon_Texts({
	AUTO_Rook_Cannon_Name = "Cross Cannons",
	AUTO_Rook_Cannon_Description = "Fires a projectile in all 4 directions, damaging and pushing on impact.",
	AUTO_Rook_Cannon_Upgrade1 = "Directional",
	AUTO_Rook_Cannon_A_UpgradeDescription = "Fire in three directions instead of four, with increased damage in one direction. Pushes self in the remaining direction.",
	AUTO_Rook_Cannon_Upgrade2 = "+1 Damage",
	AUTO_Rook_Cannon_B_UpgradeDescription = "Increases damage dealt by 1.",
	
	AUTO_Knight_Move_Name = "Knight Smite",
	AUTO_Knight_Move_Description = "Jumps to a location, killing any unit unfortunate enough to be there.",
})

A possibly more convenient way to use this function is to put all your weapon strings into a single file, text_weapons.lua:

return {
	AUTO_Rook_Cannon_Name = "Cross Cannons",
	AUTO_Rook_Cannon_Description = "Fires a projectile in all 4 directions, damaging and pushing on impact.",
	AUTO_Rook_Cannon_Upgrade1 = "Directional",
	AUTO_Rook_Cannon_A_UpgradeDescription = "Fire in three directions instead of four, with increased damage in one direction. Pushes self in the remaining direction.",
	AUTO_Rook_Cannon_Upgrade2 = "+1 Damage",
	AUTO_Rook_Cannon_B_UpgradeDescription = "Increases damage dealt by 1.",
	
	AUTO_Knight_Move_Name = "Knight Smite",
	AUTO_Knight_Move_Description = "Jumps to a location, killing any unit unfortunate enough to be there.",
}

And then add them to the game using:

modApi:addWeapon_Texts(require(self.scriptPath.."text_weapons"))

 

modApi:getLanguageIndex

Returns the index of the currently loaded language.

 

modApi:getLanguageDisplayName

Argument name Type Description
languageIndex number Index of the language to check, defaults to modApi:getLanguageIndex()

Returns the display name for the given language by index.

 

modApi:getLanguageId

Argument name Type Description
languageIndex number Index of the language to check, defaults to modApi:getLanguageIndex()

Returns the unique string ID of the given language by index.

 

modApi:setText

Argument name Type Description
id string Identifier of the text to be added or replaced
text string New text

Sets a new text for the specified identifier. This can be used to override any text in the game. Texts set this way are cleared whenever mods are loaded.

 

modApi:loadPersonalityCSV

Argument name Type Description
fileList table Table with two keys, file specifying the path to the .csv file to load, and start, specifying the last row containing csv comments, etc. - or, in other words, the row after which actual data starts

Loads a .csv file with pilot/CEO dialogs, and inserts them into Personality global table.

Example:

local path = mod_loader.mods[modApi.currentMod].scriptPath

local filelist = {
    -- The value of 'start' depends on the exact structure of your .csv file.
    -- For reference, see /scripts/personalities/ in the game's own scripts
    { file = GetWorkingDir() .. path .."/personalities/Pilots.csv", start = # }
}

modApi:loadPersonalityCSV(filelist)

 

Gameplay

Functions related to gameplay

 

modApi:getHoveredSkill

Returns the base skill table of the skill being displayed as a tipimage, or nil if no tipimage is displayed.

 

modApi:isHoveredSkill

Argument name Type Description
skill table The skill we want to check

Returns true if a tipimage is being displayed for the specified base skill table. false otherwise.

 

modApi:isTipImage

Returns true if any tipimage is being displayed. false otherwise.

 

modApi:getFocusedPawn

Returns the base pawn type table of the pawn being focused, or nil if no pawn is being focused.

focused here means when a pawn is either hovered or selected; and the game draws the ui for the pawn's pilot, traits and weapons at the bottom left of the screen, during a mission (including test mech scenario).

 

modApi:isPawnFocused

Argument name Type Description
pawnTable table The base pawn type table we want to check

Returns true if a pawn with the specified pawn type table is being focused. false otherwise.

focused here means when a pawn is either hovered or selected; and the game draws the ui for the pawn's pilot, traits and weapons at the bottom left of the screen, during a mission (including test mech scenario).

 

modApi:isAnyPawnFocused

Returns true if any pawn is being focused. false otherwise.

focused here means when a pawn is either hovered or selected; and the game draws the ui for the pawn's pilot, traits and weapons at the bottom left of the screen, during a mission (including test mech scenario).

 

Add a custom footer
Add a custom sidebar
Clone this wiki locally