Mod Hooks

Warzone 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.

Server Hooks

• 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.

• Server_AdvanceTurn_Start (Server_AdvanceTurn.lua)
  • Called whenever the server begins processing a normal turn (not territory picking). This gives mods an opportunity to insert orders at the start of a turn, before any player's orders are added. All of the Server_AdvanceTurn_* hooks share global state within a single turn, so global variables can be read and written reliably by mods.
  • Arguments:

1. Game: Provides read-only information about the game.
2. addNewOrder: A function that you can call to add a GameOrder to the start of the turn. You may call this function multiple times if you wish to add multiple orders. Pass a single GameOrder as the first argument to this function.

• Server_AdvanceTurn_Order (Server_AdvanceTurn.lua)
  • Called whenever the server processes a player's order during a normal turn (not territory picking). This gives mods an opportunity to skip the order, modify it, or let it process normally.

This hook is called after the results of the order have been computed, but before it has been applied to the standing. For example, when looking at an Attack/Transfer order that represents a territory being captured, the standing will still show the territory as uncaptured.

All of the Server_AdvanceTurn_* turns share global state within a single turn, so global variables can be read and written reliably by mods.

• • Arguments:

1. Game: Provides read-only information about the game.
2. GameOrder: The order being processed. (read-only)
3. GameOrderResult: The result of the order being processed. This is writable, so mods can change the result. Currently, only GameOrderAttackTransferResult has writable fields.
4. skipThisOrder: A function that you can call to indicate that this order should be skipped. This should be called with one of three values, listed below. If it is called multiple times, the last call overrides the previous calls.
   1. WL.ModOrderControl.Keep: Indicates this order should be processed normally. This is the default value, and all orders will default to Keep if skipThisOrder is not called.
   2. WL.ModOrderControl.Skip: Indicates this order should be skipped. It won't appear in the orders list at all and it will be as if the order never existed. A GameOrderEvent will be written into the orders list to tell the player who entered this order that their order was skipped.
   3. WL.ModOrderControl.SkipAndSupressSkippedMessage: Same as Skip, except that the GameOrderEvent is not written. This should be used with care, as players will want to know why their order didn't appear in the orders list. This should only be used if you use some other mechanism to explain to the player why their order was not present, or if this is an order that your mod inserted and therefore no players were expecting it.
5. addNewOrder: A function that you can call to add a GameOrder to the start of the turn. You may call this function multiple times if you wish to add multiple orders. Pass a single GameOrder as the first argument to this function. Optionally, you can also pass "true" as a second argument to this function to make your new order get skipped if the order this hook was called on gets skipped, either by your mod or another mod. This second argument was added in 5.17.0.

• Server_AdvanceTurn_End (Server_AdvanceTurn.lua)
  • Called whenever the server finishes processing a normal turn (not territory picking). This gives mods an opportunity to insert orders at the end of a turn, after all player's orders are added. All of the Server_AdvanceTurn_* turns share global state within a single turn, so global variables can be read and written reliably by mods.
  • Arguments:

1. Game: Provides read-only information about the game.
2. addNewOrder: A function that you can call to add a GameOrder to the start of the turn. You may call this function multiple times if you wish to add multiple orders. Pass a single GameOrder as the first argument to this function.

• Server_GameCustomMessage (Server_GameCustomMessage.lua)
  • Called whenever your mod calls ClientGame.SendGameCustomMessage. This gives mods a way to communicate between the client and server outside of a turn advancing. Note that if a mod changes Mod.PublicGameData or Mod.PlayerGameData, the clients that can see those changes and have the game open will automatically receive a refresh event with the updated data, so this message can also be used to push data from the server to clients.
  • Mod security should be applied when working with this Hook
  • Arguments:

1. Game: Provides read-only information about the game.
2. PlayerID: The ID of the player who invoked this call.
3. payload: The data passed as the payload parameter to SendGameCustomMessage. Must be a lua table.
4. setReturn: Optionally, a function that sets what data will be returned back to the client. If you wish to return data, pass a table as the sole argument to this function. Not calling this function will result in an empty table being returned.

Client Hooks

• 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.
  • 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. This is the only place that Mod.Settings should ever be written to.
  • 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.
  • Arguments:

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

• Client_PresentMenuUI (Client_PresentMenuUI.lua)
  • If present, games with this mod enabled will have a new button on the menu. When the player clicks that button, this mod hook is invoked and the resulting UI will be shown to the player in a dialog. See UI API.
  • Arguments:

1. rootParent: Pass this as an argument to the top-level UI element your mod creates. See the UI API for details.
2. setMaxSize: Function mods can call to set the maximum size of the dialog. Pass two numbers: the width and the height. Note that screen sizes can vary a lot, so you can never be sure you'll get the size you request, so plan on making your UI work in all sizes.
3. setScrollable: Function mods can call to set whether the dialog is scrollable horizontally or vertically. Pass two booleans: the first determines if it's horizontally scrollable, and the second determines if it's vertically scrollable. The default is false, true.
4. ClientGame: Information about the game.
5. close: Function that, when called, will close the current dialog. Takes no arguments and returns nothing.

• Client_GameRefresh (Client_GameRefresh.lua)
  • Invoked whenever the client gets data about this game from the server. This can be used to check for updated Mod.PublicGameData or Mod.PlayerGameData, documented at Mod Game Data Storage. The client refresh timing is different between single-player and multi-player, and in multi-player can also vary depending on the user's internet connection (such as whether they're connected by websocket, long polling socket, or normal polling). Therefore, a mod should never write code that breaks if Client_GameRefresh is called at unexpected times.
  • Arguments:

1. ClientGame: Information about the game.

• Client_PresentCommercePurchaseUI (Client_PresentCommercePurchaseUI.lua)
  • Invoked whenever the player clicks the "Build" button in a commerce game. This can be used to present UI to allow the player to spend their gold on things.
  • Arguments:

1. rootParent: Pass this as an argument to the top-level UI element your mod creates. See the UI API for details.
2. ClientGame: Information about the game.
3. close: Function that, when called, will close the current dialog. Takes no arguments and returns nothing.

Notes

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

No hooks have return values. Meaning, it doesn't matter if you return any values from your hook functions. Instead, the mod framework gives you callbacks to call to affect things. This is preferred over return values for a few reasons. First, it allows mods to call the callbacks early on or late on in their function, which can be easier than a return statement which must come at the end. Second, it allows mods to simply not call the callback, which can signal to Warzone that the mod doesn't care about the result of this. This can be important in some cases where multiple mods that define the same hook. Sometimes the mods instructions can conflict and Warzone must decide which to obey.

See also

• Mod Developers Guide
• Mod Game Data Storage