Mod Hooks

Revision as of 01:33, 8 April 2017

WarLight will call into a mod's lua code using what are called hooks.

For example, it will call a hook named Server_StartGame when a game is beginning and give your mod an opportunity to change things about how the map is set up.

If you provide a function with the name listed here, and in a file with the name listed here, it will be called as explained. Note that both the function name and the file name are case-sensitive.

Hook Reference

• Server_Created (Server_Created.lua)
  • Called in every game when the game is first created. In multi-player, this means it's called before players even accept or join the request for the game. This is the only place that game settings can be changed.
  • Return value: None.
  • Arguments:

1. Game: Provides read-only information about the game.
2. GameSettings: (writable) Allows your mod to change the game's settings.

• Server_StartDistribution (Server_StartDistribution.lua)
  • Called in any game set to manual territory distribution before players select their picks. This hook is not called in any game configured to automatic territory distribution. This is called after the standing has been built (wastelands and pickable territories have already been placed and initial cards have already been given out.)
  • Return value: None.
  • Arguments:

1. Game: Provides read-only information about the game.
2. Standing: (writable) Allows your mod to change the standing before players see it. For example, a mod could change the number of armies on any territory, control which territories are pickable, or define what cards each player starts with.

• Server_StartGame (Server_StartGame.lua)
  • Called when the game starts the first turn. In a manual territory distribution game, this is called after all players have entered their picks. In an automatic territory distribution game, this is called when the game starts. This is called after the standing has been built (picks have been given out)
  • Return value: None.
  • Arguments:

1. Game: Provides read-only information about the game.
2. Standing: (writable) Allows your mod to change the the standing before players see it. For example, a mod could change the number of armies on any territory, control which players control which territories, or define what cards each player starts with.

• Client_PresentConfigureUI (Client_PresentConfigureUI.lua)
  • Called when a player checks your mod on the Create Game page. If your mod has any configurable settings, you should create UI controls on the screen to allow players to configure them using the UI API. Mods should also check the Mod.Settings global to see if any settings are already defined, and if they are, default their UI state to match that.
  • Return value: None.
  • Arguments:

1. rootParent: Pass this as an argument to the top-level UI element your mod creates. See the UI API for details.

• Client_SaveConfigureUI (Client_SaveConfigureUI.lua)
  • Called when a player submits the Create Game Mod page with your mod checked. If your mod presented any UI in Client_PresentConfigureUI, your mod should persist any settings into the Mod.Settings global during this hook.
  • Return value: None.
  • Arguments:

1. alert: A function callback that takes a string. If the user has configured anything wrong with your UI, you can call this to notify them of their mistake. Calling this function will also abort the save.

• Client_PresentSettingsUI (Client_PresentSettingsUI.lua)
  • Called when a player opens the Game Settings panel of a game that has your mod included. If your mod has any configurable settings, you should read them out of the global Mod.Settings and show them to the player here using the UI API.
  • Return value: None.
  • Arguments:

1. rootParent: Pass this as an argument to the top-level UI element your mod creates. See the UI API for details.

Notes

Any hooks that start with Server_ are run on the server in multi-player games, and on the client in single-player games.