Script Hooks

Hooks are script functions that are called at specific moments. This way, you can insert code into the game.

They are specified in script files and tagged with the Hook specifier. They also must be placed within a namespace to avoid ambiguity between multiple mods.

The following is an example of such a file:

namespace MyTestMod
{
  [Hook]
  void GameModeStart(Campaign@ campaign, SValue@ save)
  {
    print("Hello, world!");
  }
}

GameModeConstructor

void GameModeConstructor(Campaign@ campaign)

Called when the Campaign gamemode is being constructed. Useful for initial setting up, for example to add new definitions for items, sets, shops, fountain effects, etc.

GameModeStart

void GameModeStart(Campaign@ campaign, SValue@ save)

Called in the Campaign gamemode's Start() function. This allows to initialize things and additionally loading any saved data saved in the GameModeSave hook using the save parameter. This paramater is null if there is no save.

GameModePostStart

void GameModePostStart(Campaign@ campaign)

Called in the Campaign gamemode's PostStart() function. This function is usually used to load things after all the unit behaviors have loaded in, and just before the player is ready to spawn.

GameModeUpdate

void GameModeUpdate(Campaign@ campaign, int dt, GameInput& gameInput, MenuInput& menuInput)

Called every tick from the Campaign gamemode's update function. Use dt to determine how many milliseconds have passed since the last tick. Note that ticks are different from rendered frames. Ticks typically run at a fixed rate of 30 FPS. You can use gameInput and menuInput here to get information about current controls.

GameModeRenderFrame

void GameModeRenderFrame(Campaign@ campaign, int idt, SpriteBatch &sb)

Called for each rendered frame before any UI is drawn. If you're looking for a hook called after the UI is drawn, use the GameModeRenderWidgets hook instead. You can use sb to render things to the screen. The idt parameter is the current time in milliseconds since the last update tick, which means the value will be between 0 and 33. Divide this value by 33.0f to get a normalized interpolation factor for animations.

GameModeUpdateWidgets

void GameModeUpdateWidgets(Campaign@ campaign, int dt, GameInput& gameInput, MenuInput& menuInput)

Called every tick from the Campaign gamemode's widget updating function. Use this for widgets rather than GameModeUpdate, because this still gets called when the game is paused. Use dt to determine how many milliseconds have passed since the last tick. Note that ticks are different from rendered frames. Ticks typically run at a fixed rate of 30 FPS. You can use gameInput and menuInput here to get information about current controls.

(Added in b100 and onwards)

GameModeRenderWidgets

void GameModeRenderWidgets(Campaign@ campaign, PlayerRecord@ player, int idt, SpriteBatch &sb)

Called for each rendered frame after the UI is drawn. If you're looking for a hook called before the UI is drawn, use the GameModeRenderFrame hook instead. You can use sb to render things to the screen. The idt parameter is described in the GameModeRenderFrame hook description. The player parameter specifies the player that the UI is currently being rendered for. This is typically the local player, but it can also be a different player for spectators.

GameModeSave

void GameModeSave(Campaign@ campaign, SValueBuilder &builder)

Save any gamemode info. Note that this is separate from town and player record saves. Gamemode saves contain only information necessary to switch from one level to another, or for drop-in multiplayer joining. Use builder to serialize data.

GameModeOnRunEnd

void GameModeOnRunEnd(Campaign@ campaign, PlayerRecord@ record, bool died)

Called when a player's run has ended. This can happen if the player dies, or if the player beats the game through the EndOfGame worldscript. The player whose run has ended is specified by the record parameter. The died parameter is true if the run has ended because of the player dying, or false if the game was beaten.

GameModeInitializePlayer

void GameModeInitializePlayer(Campaign@ campaign, PlayerRecord@ record)

Called when the player record is initialized.

GameModeSpawnPlayer

void GameModeSpawnPlayer(Campaign@ campaign, PlayerRecord@ record)

Called when a player has spawned. (B90+)

GameModePlayerDied

void GameModePlayerDied(Campaign@ campaign, PlayerRecord@ player, PlayerRecord@ killer, DamageInfo &di)

Called when a player dies. (B90+)

TownRecordSave

void TownRecordSave(TownRecord@ record, SValueBuilder &builder)

Called when the town record is being saved. Use builder to serialize data.

TownRecordLoad

void TownRecordLoad(TownRecord@ record, SValue@ sval)

Called when the town record is being loaded. Use sval to deserialize data.

PlayerKilledActor

void PlayerKilledActor(PlayerBase@ player, Actor@ killed, DamageInfo &di)

Called when the player kills an actor.

PlayerRecordSave

void PlayerRecordSave(PlayerRecord@ record, SValueBuilder &builder)

Called when a player record is being saved. Use builder to serialize data.

PlayerRecordLoad

void PlayerRecordLoad(PlayerRecord@ record, SValue@ sval)

Called when a player record is being loaded. Use sval to deserialize data.

PlayerRecordRefreshItemSets

void PlayerRecordRefreshItemSets(PlayerRecord@ record)

Called when item sets are refreshed in a player record.

(Added since b102)

PlayerRecordRefreshModifiers

void PlayerRecordRefreshModifiers(PlayerRecord@ record)

Called when modifiers are refreshed in a player record.

(Added since b102)

PlayerRefreshScene

void PlayerRefreshScene(PlayerBase@ player)

Called each tick to make sure the player's unit scene is up to date. Useful if you want to add or attach any graphical element on top of the player unit.

WidgetHosterLoad

void WidgetHosterLoad(IWidgetHoster@ host, GUIBuilder@ b, GUIDef@ def)

Called when a widget hoster loaded its gui file. host specifies the host object that loaded the gui file. b is the builder object that was used to build the widget tree. def is the definition of the gui file, which can be used to get any defined sprites.

WidgetHosterResourceAdded

void WidgetHosterResourceAdded(Widget@ parent, Widget@ w, GUIBuilder@ b, GUIDef@ def)

Called when a widget adds a resource gui file via AddResource. parent is the widget that the resource was added to as a child. w is the root widget of the added gui file. b is the builder object that was used to build the widget tree. def is the definition of the gui file, which can be used to get any defined sprites.

LoadWidgetProducers

void LoadWidgetProducers(GUIBuilder@ builder)

Called when widget producers should be loaded. This allows you to initialize custom widget producers that can produce custom widgets. builder is where you would call AddWidgetProducer on to initialize the widget producer.

(Added since b100 and)