Skip to content

Mod Loader Hooks

Jump to bottom Edit New page
Lemonymous edited this page Aug 24, 2021 · 19 revisions

Table of Contents

 

 

modApi

 

pawnSelectedHook

Argument name Type Description
pawn userdata Pawn being selected

Fired when a pawn is selected.

Example:

local hook = function(pawn)
	LOGF("Pawn %s was now selected!", pawn:GetMechName())
end

modApi:addPawnSelectedHook(hook)

 

pawnDeselectedHook

Argument name Type Description
pawn userdata Pawn being deselected

Fired when a pawn is deselected.

Example:

local hook = function(pawn)
	LOGF("Pawn %s was now deselected!", pawn)
end

modApi:addPawnDeselectedHook(hook)

IMPORTANT NOTE: Exiting the game to the main menu while a pawn is selected will not cause this hook to fire. If a reference to the selected pawn is held, it is recommended to also register a gameExitedHook to free up the reference. Calling methods on a dereferenced pawn will crash the game.

 

pawnFocusedHook

Argument name Type Description
pawnType string Pawn type of pawn being focused

Fired when a pawn is 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).

Example:

local hook = function(pawnType)
	LOGF("PawnType %s is now being focused!", pawnType)
end

modApi:addPawnFocusedHook(hook)

 

pawnUnfocusedHook

Argument name Type Description
pawnType string Pawn type of pawn being unfocused

Fired when a pawn is unfocused. 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).

Example:

local hook = function(pawnType)
	LOGF("PawnType %s was now unfocused!", pawnType)
end

modApi:addPawnUnfocusedHook(hook)

 

preMissionAvailableHook

Argument name Type Description
mission table A table holding information about the current mission

Fired right before a mission becomes available for selection on the island map.

Example:

local hook = function(mission)
	LOG("New mission is about to be made available!")
end

modApi:addPreMissionAvailableHook(hook)

 

postMissionAvailableHook

Argument name Type Description
mission table A table holding information about the current mission

Fired when a mission becomes available for selection on the island map.

Example:

local hook = function(mission)
	LOG("New mission is now available!")
end

modApi:addPostMissionAvailableHook(hook)

 

preEnvironmentHook

Argument name Type Description
mission table A table holding information about the current mission

Fired right before effects of the mission's environment (tidal waves, cataclysm, etc) are executed.

Example:

local hook = function(mission)
	LOG("The environment is about to do its thing!")
end

modApi:addPreEnvironmentHook(hook)

 

postEnvironmentHook

Argument name Type Description
mission table A table holding information about the current mission

Fired after the effects of the mission's environment (tidal waves, cataclysm, etc) are executed.

Example:

local hook = function(mission)
	LOG("The environment has done its thing!")
end

modApi:addPostEnvironmentHook(hook)

 

nextTurnHook

Argument name Type Description
mission table A table holding information about the current mission

Fired at the start of each turn, once for each team.

Both player and enemy have their own turns, so the function will be called twice after the user presses next turn button. Convenient built-in functions to call in the hook are Game:GetTurnCount(), which returns how many turns have passed, and Game:GetTeamTurn(), which returns a value that can be compared to TEAM_PLAYER and TEAM_ENEMY.

Example:

local hook = function(mission)
	LOG("Currently it is turn of team: " .. Game:GetTeamTurn())
end

modApi:addNextTurnHook(hook)

 

missionUpdateHook

Argument name Type Description
mission table A table holding information about the current mission

Called once every frame, after the game updates the game entities, ie. things such as status effects (fire/smoke/acid) have been processed and applied to pawns.

Example:

local hook = function(mission)
	LOG("Entities have been updated!")
end

modApi:addMissionUpdateHook(hook)

 

missionStartHook

Argument name Type Description
mission table A table holding information about the current mission

Fired right after the player has selected a mission, loads into the game board, and is about to start deploying their mechs.

Example:

local hook = function(mission)
	LOG("Mission started!")
end

modApi:addMissionStartHook(hook)

 

missionEndHook

Argument name Type Description
mission table A table holding information about the current mission
ret SkillEffect A skill effect that can be used to apply effects to the game board when the mission ends. Vanilla game uses this to make enemies retreat, etc.

Fired when the turn counter reaches 0, ie. a mission ends. Not sure if it fires when the player loses all grid power.

Example:

local hook = function(mission)
	LOG("Mission end!")
end

modApi:addMissionEndHook(hook)

 

missionNextPhaseCreatedHook

Argument name Type Description
prevMission table A table holding information about the previous mission (the one the player just completed)
nextMission table A table holding information about the next mission (the one the player is now entering)

Fired when a mission with NextPhase defined constructs its next phase mission object.

Example:

local hook = function(prevMission, nextMission)
	LOG("Left mission " .. prevMission.ID .. ", going into " .. nextMission.ID)
end

modApi:addMissionNextPhaseCreatedHook(hook)

 

voiceEventHook

Argument name Type Description
eventInfo VoiceEvent A userdata type holding information about a voice event. Fields: id -- string identifier of the event, pawn1 -- id of the pawn that triggered the event, if applicable, pawn2 -- id of the target pawn of the event, if applicable
customOdds number Optional integer value ranging from 0 to 100, used to override odds of the voice dialog being triggered
suppress boolean Whether a voice dialog should be not be played in response to this voice event (this is true if eg. another hook has already played a dialog)

Triggered by the game in response to various events, or by manually invoking the TriggerVoiceEvent function.

Example:

local hook = function(eventInfo, customOdds, suppress)
	if eventInfo.id == "SomeEventWeAreInterestedIn" and not suppress then
		LOG("Voice event!")
		-- We handled this event (and maybe played some dialogs between pilots), so
		-- we return true to tell other hooks that they shouldn't play their dialogs.
		return true
	end

	return false
end

modApi:addVoiceEventHook(hook)

 

preIslandSelectionHook

Argument name Type Description
corporation string A string identifier of the island's corporation. Corp_Grass, etc.
island number A number id of the island. 0 for Archive, 1 for R.S.T., etc.

Fired when the player selects an island, before missions are created for the island.

Example:

local hook = function(corporation, island)
	LOG("Selected island " .. island .. ": " .. corporation)
end

modApi:addPreIslandSelectionHook(hook)

 

postIslandSelectionHook

Argument name Type Description
corporation string A string identifier of the island's corporation. Corp_Grass, etc.
island number A number id of the island. 0 for Archive, 1 for R.S.T., etc.

Fired when the player selects an island, after missions have been created for the island.

Example:

local hook = function(corporation, island)
	LOG("Selected island " .. island .. ": " .. corporation)
end

modApi:addPostIslandSelectionHook(hook)

 

preStartGameHook

Fired right after the player exits the hangar and right after mods are loaded, but before game variables are set up (GAME, Game, GameData, SquadData, RegionData, etc.)

Example:

local hook = function()
	LOG("About to start a new game!")
end

modApi:addPreStartGameHook(hook)

 

postStartGameHook

Fired after the player exits the hangar and game variables are set up (GAME, Game, GameData, SquadData, RegionData, etc.).

Example:

local hook = function()
	LOG("Started a new game!")
end

modApi:addPostStartGameHook(hook)

 

preLoadGameHook

Fired after mods are loaded, but before savegame data is loaded. Triggers when pressing "Continue" and when resetting turn.

Example:

local hook = function()
	LOG("We're about to load a savegame!")
end

modApi:addPreLoadGameHook(hook)

 

postLoadGameHook

Fired after savegame data is loaded. Triggers when pressing "Continue" and when resetting turn.

Example:

local hook = function()
	LOG("We've loaded a savegame!")
end

modApi:addPostLoadGameHook(hook)

 

saveGameHook

Fired before the game is saved.

Example:

local hook = function()
	LOG("Game is being saved!")
end

modApi:addSaveGameHook(hook)

 

vekSpawnAddedHook

Argument name Type Description
mission table A table holding information about the current mission
spawnData table Table holding information about the spawn point

Fired when a Vek spawn is added onto the game board. Doesn't work for spawns added via Board:SpawnPawn(); use Mission:SpawnPawn(location, enemyType) if you wish for the spawn to be detected by this hook.

See GetSpawnPointData() for contents of the spawnData table.

Example:

local hook = function(mission, spawnData)
	LOG(spawnData.type.." is spawning at "..spawnData.location:GetString())
end

modApi:addVekSpawnAddedHook(hook)

 

vekSpawnRemovedHook

Argument name Type Description
mission table A table holding information about the current mission
spawnData table Table holding information about the spawn point

Fired when a Vek spawn is no longer on the game board (either when the Vek successfully spawned, or when the spawn was removed via API).

See GetSpawnPointData() for contents of the spawnData table.

Example:

local hook = function(mission, spawnData)
	LOG(spawnData.type.." spawn removed from "..spawnData.location:GetString())
end

modApi:addVekSpawnRemovedHook(hook)

 

modsInitializedHook

Fired when all mods have been initialized, but before the mod loader starts loading them. Unlike other mod hooks, this will not be reset during load, so it should generally be added in `init.

Example:

modApi:addModsInitializedHook(function()
	LOG("All mods have been initialized!")
end)

 

modsLoadedHook

Fired when all enabled mods have been loaded. May be fired multiple times when mods are loaded again, such as when starting a game.

Example:

modApi:addModsLoadedHook(function()
	LOG("All mods have been loaded!")
end)

 

modsFirstLoadedHook

Fired after the first time that all enabled mods have been loaded. Unlike other mod hooks, this will not be reset during load, so it should generally be added in `init.

Example:

modApi:addFirstModsLoadedHook(function()
	LOG("Mods are first loaded!")
end)

 

testMechEnteredHook

Argument name Type Description
mission table A table holding information about the current mission

Fired when the player enters the test mech scenario.

Example:

modApi:addTestMechEnteredHook(function(mission)
	LOG("Player has entered the test mech scenario!")
end)

 

testMechExitedHook

Argument name Type Description
mission table A table holding information about the current mission

Fired when the player leaves the test mech scenario.

Example:

modApi:addTestMechExitedHook(function(mission)
	LOG("Player has left the test mech scenario!")
end)

 

tipImageHiddenHook

Argument name Type Description
skillType string Skill type of weapon having its tipimage hidden

Fired when a tipimage is hidden. Can fire during missions, test mech scenarior, in the hangar, and in the mech edit window. However, it does not fire when viewing tipimages for upgrades.

Example:

modApi:addTipImageHiddenHook(function(skillType)
	LOGF("Tipimage for skillType %s was now hidden!", skillType)
end)

 

tipImageShownHook

Argument name Type Description
skillType string Skill type of weapon having its tipimage shown

Fired when a tipimage is shown. Can fire during missions, test mech scenarior, in the hangar, and in the mech edit window. However, it does not fire when viewing tipimages for upgrades.

Example:

modApi:addTipImageShownHook(function(skillType)
	LOGF("Tipimage for skillType %s is now being shown!", skillType)
end)

 

preprocessVekRetreatHook

Argument name Type Description
mission table A table holding information about the current mission
missionEndFx SkillEffect The SkillEffect instance used to apply mission-end Board effects

Fired once the mission ends, as the vek retreat SkillEffect is being prepared, before the vek present on the game board are processed.

Example:

modApi:addPreprocessVekRetreatHook(function(mission, endFx)
	LOG("Pre-processing vek retreat!")
	endFx:AddScript("LOG(\"Vek are about to start retreating!\")")
end)

 

processVekRetreatHook

Argument name Type Description
mission table A table holding information about the current mission
missionEndFx SkillEffect The SkillEffect instance used to apply mission-end Board effects
pawn userdata The pawn that is currently being processed for retreat

Fired during the mission end, as the vek retreat SkillEffect is being prepared, while the vek present on the game board are being processed. Triggers once for each enemy pawn on the board.

Example:

modApi:addProcessVekRetreatHook(function(mission, endFx, pawn)
	LOG("Procesing retreating vek: " .. pawn:GetMechName())
	endFx:AddScript(string.format(
		"LOG(%s..\" is retreating!\")",
		pawn:GetMechName()
	))
end)

 

postprocessVekRetreatHook

Argument name Type Description
mission table A table holding information about the current mission
missionEndFx SkillEffect The SkillEffect instance used to apply mission-end Board effects

Fired once the mission ends, as the vek retreat SkillEffect is being prepared, after the vek present on the game board have been processed.

Example:

modApi:addPreprocessVekRetreatHook(function(mission, endFx)
	LOG("Post-processing vek retreat!")
	endFx:AddScript("LOG(\"All vek have retreated!\")")
end)

 

saveDataUpdatedHook

Fired when save game data is reloaded by the mod loader, and the GameData, RegionData, and SquadData globals have been updated with fresh data straight from the save file.

 

sdlext

 

settingsChangedHook

Argument name Type Description
old table Old settings table
new table New settings table

Fired when settings are changed.

IMPORTANT NOTE: sdlext hooks are not cleared during load(), so you must ensure that you only add them once, to prevent duplicates.

Example:

sdlext.addSettingsChangedHook(function(old, new)
	LOG("Settings have changed")
end)

 

continueClickHook

Fired when the Continue button in main menu is clicked.

IMPORTANT NOTE: sdlext hooks are not cleared during load(), so you must ensure that you only add them once, to prevent duplicates.

Example:

sdlext.addContinueClickHook(function()
	LOG("Continue clicked!")
end)

 

newGameClickHook

Fired when the New Game button in main menu is clicked (does not account for the confirmation popup when trying to start a new game while still having a game you can return to -- for that, use mainMenuLeavingHook).

IMPORTANT NOTE: sdlext hooks are not cleared during load(), so you must ensure that you only add them once, to prevent duplicates.

Example:

sdlext.addNewGameClickHook(function()
	LOG("New Game clicked!")
end)

 

uiRootCreatedHook

Argument name Type Description
screen userdata The screen object accepting draw instructions
uiRoot table The root UI element

Fired when the root UI element is created. This hook can be used to create your own custom UI, if you need it created as soon as the game starts.

The root UI element handles stuff like mouse and keyboard interaction with the game. All of your mod's UI should be a child of this root UI element.

IMPORTANT NOTE: sdlext hooks are not cleared during load(), so you must ensure that you only add them once, to prevent duplicates.

Example:

sdlext.addUiRootCreatedHook(function(screen, uiRoot)
	LOG("UI root created!")
end)

 

mainMenuEnteredHook

Argument name Type Description
screen userdata The screen object accepting draw instructions
wasHangar boolean True if the player was previously in the hangar screen
wasGame boolean True if the player was prviously in game

Fired when the player enters the main menu screen.

IMPORTANT NOTE: sdlext hooks are not cleared during load(), so you must ensure that you only add them once, to prevent duplicates.

Example:

sdlext.addMainMenuEnteredHook(function(screen, wasHangar, wasGame)
	LOG("Main menu entered!")
end)

 

mainMenuExitedHook

Argument name Type Description
screen userdata The screen object accepting draw instructions

Fired when the player exits the main menu screen.

IMPORTANT NOTE: sdlext hooks are not cleared during load(), so you must ensure that you only add them once, to prevent duplicates.

Example:

sdlext.addMainMenuExitedHook(function(screen)
	LOG("Main menu exited!")
end)

 

mainMenuLeavingHook

Fired when the player starts leaving the main menu screen.

IMPORTANT NOTE: sdlext hooks are not cleared during load(), so you must ensure that you only add them once, to prevent duplicates.

Example:

sdlext.addMainMenuLeavingHook(function()
	LOG("Leaving main menu!")
end)

 

hangarEnteredHook

Argument name Type Description
screen userdata The screen object accepting draw instructions

Fired when the player enters the hangar screen.

IMPORTANT NOTE: sdlext hooks are not cleared during load(), so you must ensure that you only add them once, to prevent duplicates.

Example:

sdlext.addHangarEnteredHook(function(screen)
	LOG("Hangar entered!")
end)

 

hangarExitedHook

Argument name Type Description
screen userdata The screen object accepting draw instructions

Fired when the player exits the hangar screen.

IMPORTANT NOTE: sdlext hooks are not cleared during load(), so you must ensure that you only add them once, to prevent duplicates.

Example:

sdlext.addHangarExitedHook(function(screen)
	LOG("Hangar exited!")
end)

 

hangarLeavingHook

Argument name Type Description
startGame boolean true if the hangar is being left to start a new game. false otherwise.

Fired when the player starts leaving the hangar screen.

IMPORTANT NOTE: sdlext hooks are not cleared during load(), so you must ensure that you only add them once, to prevent duplicates.

Example:

sdlext.addHangarLeavingHook(function(startGame)
	LOG("Leaving hangar!")
end)

 

gameEnteredHook

Argument name Type Description
screen userdata The screen object accepting draw instructions

Fired when the player enters the game screen.

IMPORTANT NOTE: sdlext hooks are not cleared during load(), so you must ensure that you only add them once, to prevent duplicates.

Example:

sdlext.addGameEnteredHook(function(screen)
	LOG("Game entered!")
end)

 

gameExitedHook

Argument name Type Description
screen userdata The screen object accepting draw instructions

Fired when the player exits the game screen.

IMPORTANT NOTE: sdlext hooks are not cleared during load(), so you must ensure that you only add them once, to prevent duplicates.

Example:

sdlext.addGameExitedHook(function(screen)
	LOG("Game exited!")
end)

 

frameDrawnHook

Argument name Type Description
screen userdata The screen object accepting draw instructions

Fired when a frame is finished being drawn.

IMPORTANT NOTE: sdlext hooks are not cleared during load(), so you must ensure that you only add them once, to prevent duplicates.

Example:

sdlext.addFrameDrawnHook(function(screen)
	LOG("Frame drawn!")
end)

 

windowVisibleHook

Argument name Type Description
screen userdata The screen object accepting draw instructions
wx number X position of the window on screen in pixels
wy number Y position of the window on screen in pixels
ww number Width of the window in pixels
wh number Height of the window in pixels

Fired every frame when a shadow-casting UI element is visible. This includes a variety of stuff like inert UI panes, tooltips, tip images, etc. Can be used to hack together heuristics for whether some kind of UI window is open.

sdlext.CurrentWindowRect is a rect that is set to the wx, wy, ww, and wh values every frame, reducing the need for this hook. sdlext.LastWindowRect does the same, but holds values for the previous window that was visible before the current one has been opened.

IMPORTANT NOTE: sdlext hooks are not cleared during load(), so you must ensure that you only add them once, to prevent duplicates.

Example:

sdlext.addWindowVisibleHook(function(screen, wx, wy, ww, wh)
	LOG("Window visible! Dimensions:", wx, wy, ww, wh)
end)

 

gameWindowResizedHook

Argument name Type Description
screen userdata The screen object accepting draw instructions
oldSize table table containing old sizes of the game window in x and y fields

Fired when size of the game window changes.

IMPORTANT NOTE: sdlext hooks are not cleared during load(), so you must ensure that you only add them once, to prevent duplicates.

Example:

sdlext.addGameWindowResizedHook(function(screen, oldSize)
	LOG("Game window has been resized! Old size:", oldSize.x, oldSize.y)
end)

 

preKeyDownHook

Argument name Type Description
keycode number SDL keycode of the key that has been pressed. See SDL Keycode Lookup table

Fired whenever a key is pressed down. The hooked function can optionally return true to signal that it handled the key event, and that this event should not be processed further. This stops the game and other hooks from even being notified of this keypress.

Key hooks are fired WHEREVER in the game you are, whenever you press a key. So your hooks will need to have a lot of additional restrictions on when they're supposed to fire.

Pre key hooks are fired BEFORE the uiRoot handles the key events. These hooks can be used to completely hijack input and bypass the normal focus-based key event handling.

IMPORTANT NOTE: sdlext hooks are not cleared during load(), so you must ensure that you only add them once, to prevent duplicates.

Example:

sdlext.addPreKeyDownHook(function(keycode)
	LOG("Pressed key: " .. keycode)
end

 

preKeyUpHook

Argument name Type Description
keycode number SDL keycode of the key that has been pressed. See SDL Keycode Lookup table

Fired whenever a key is released. The hooked function can optionally return true to signal that it handled the key event, and that this event should not be processed further. This stops the game and other hooks from even being notified of this keypress.

Key hooks are fired WHEREVER in the game you are, whenever you press a key. So your hooks will need to have a lot of additional restrictions on when they're supposed to fire.

Pre key hooks are fired BEFORE the uiRoot handles the key events. These hooks can be used to completely hijack input and bypass the normal focus-based key event handling.

IMPORTANT NOTE: sdlext hooks are not cleared during load(), so you must ensure that you only add them once, to prevent duplicates.

Example:

sdlext.addPreKeyUpHook(function(keycode)
	LOG("Released key: " .. keycode)
end

 

postKeyDownHook

Argument name Type Description
keycode number SDL keycode of the key that has been pressed. See SDL Keycode Lookup table

Same as preKeyDownHook, except:

Post key hooks are fired AFTER the uiRoot has handled the key events. These hooks can be used to process leftover key events which haven't been handled via the normal focus-based key event handling.

IMPORTANT NOTE: sdlext hooks are not cleared during load(), so you must ensure that you only add them once, to prevent duplicates.

Example:

sdlext.addPostKeyDownHook(function(keycode)
	LOG("Pressed key: " .. keycode)
end

 

postKeyUpHook

Argument name Type Description
keycode number SDL keycode of the key that has been pressed. See SDL Keycode Lookup table

Same as preKeyUpHook, except:

Post key hooks are fired AFTER the uiRoot has handled the key events. These hooks can be used to process leftover key events which haven't been handled via the normal focus-based key event handling.

IMPORTANT NOTE: sdlext hooks are not cleared during load(), so you must ensure that you only add them once, to prevent duplicates.

Example:

sdlext.addPostKeyUpHook(function(keycode)
	LOG("Released key: " .. keycode)
end

 

consoleToggledHook

Argument name Type Description
open boolean true if the console has been opened. false if it has been closed.

Fires when the console is opened or closed.

Example:

sdlext.addConsoleToggledHook(function(open)
	if open then
		LOG("Console has been opened")
	else
		LOG("Console has been closed")
	end
end)

 

shiftToggledHook

Argument name Type Description
pressed boolean true if the modifier button has been pressed, false if released.

Fires when the Shift modifier button is either pressed or released.

Example:

sdlext.addShiftToggledHook(function(pressed)
	if pressed then
		LOG("Shift has been pressed!")
	else
		LOG("Shift has been released!")
	end
end)

 

altToggledHook

Argument name Type Description
pressed boolean true if the modifier button has been pressed, false if released.

Fires when the Alt modifier button is either pressed or released.

Example:

sdlext.addAltToggledHook(function(pressed)
	if pressed then
		LOG("Alt has been pressed!")
	else
		LOG("Alt has been released!")
	end
end)

 

ctrlToggledHook

Argument name Type Description
pressed boolean true if the modifier button has been pressed, false if released.

Fires when the Control modifier button is either pressed or released.

Example:

sdlext.addCtrlToggledHook(function(pressed)
	if pressed then
		LOG("Ctrl has been pressed!")
	else
		LOG("Ctrl has been released!")
	end
end)
Add a custom footer
Add a custom sidebar
Clone this wiki locally