Editing Mod Hooks
Warning: You are not logged in.
Your IP address will be recorded in this page's edit history.The edit can be undone.
Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.
Latest revision | Your text | ||
Line 1: | Line 1: | ||
− | + | WarLight will call into a [[Mods|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. | 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. | ||
Line 5: | Line 5: | ||
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. | 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) | + | * 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. | ** 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. | ** Return value: None. | ||
Line 31: | Line 31: | ||
+ | * 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 [[Mod API Reference:UI|UI API]]. Mods should also check the <code>Mod.Settings</code> global to see if any settings are already defined, and if they are, default their UI state to match that. | ||
+ | ** Arguments: | ||
+ | # rootParent: Pass this as an argument to the top-level UI element your mod creates. See the [[Mod API Reference:UI|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 <code>Mod.Settings</code> global during this hook. | ||
+ | ** Arguments: | ||
+ | # 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 <code>Mod.Settings</code> and show them to the player here using the [[Mod API Reference:UI|UI API]]. | ||
+ | ** Arguments: | ||
+ | # rootParent: Pass this as an argument to the top-level UI element your mod creates. See the [[Mod API Reference:UI|UI API]] for details. | ||
− | * Server_AdvanceTurn_Order ( | + | * Server_AdvanceTurn_Start (Client_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_* turns share global state within a single turn, so global variables can be read and written reliably by mods. | ||
+ | ** Arguments: | ||
+ | # [[Mod API Reference:Game|Game]]: Provides read-only information about the game. | ||
+ | # addNewOrder: A function that you can call to add a [[Mod API Reference:GameOrder|GameOrder]] to the start of the turn. Pass a single GameOrder as the only argument to this function. You may call this function multiple times if you wish. | ||
+ | |||
+ | |||
+ | * Server_AdvanceTurn_Order (Client_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. <br/>This hook is called after the results of the order have been computed, but before it has been applied to the [[Mod API Reference:GameStanding|standing]]. For example, when looking at an [[Mod API Reference:GameOrderAttackTransfer|Attack/Transfer order]] that represents a territory being captured, the standing will still show the territory as uncaptured. <br/>All of the Server_AdvanceTurn_* turns share global state within a single turn, so global variables can be read and written reliably by mods. | ** 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. <br/>This hook is called after the results of the order have been computed, but before it has been applied to the [[Mod API Reference:GameStanding|standing]]. For example, when looking at an [[Mod API Reference:GameOrderAttackTransfer|Attack/Transfer order]] that represents a territory being captured, the standing will still show the territory as uncaptured. <br/>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: | ** Arguments: | ||
Line 48: | Line 62: | ||
# [[Mod API Reference:GameOrder|GameOrder]]: The order being processed. (read-only) | # [[Mod API Reference:GameOrder|GameOrder]]: The order being processed. (read-only) | ||
# [[Mod API Reference:GameOrderResult|GameOrderResult]]: The result of the order being processed. This is writable, so mods can change the result. Currently, only [[Mod API Reference:GameOrderAttackTransferResult|GameOrderAttackTransferResult]] has writable fields. | # [[Mod API Reference:GameOrderResult|GameOrderResult]]: The result of the order being processed. This is writable, so mods can change the result. Currently, only [[Mod API Reference:GameOrderAttackTransferResult|GameOrderAttackTransferResult]] has writable fields. | ||
− | # 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. | + | # 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. Only the last call to this function defines the result, if you call it once you can call it again with a new value to change your mind. |
## 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. | ## 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. | ||
## 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 [[Mod API Reference:GameOrderEvent|GameOrderEvent]] will be written into the orders list to tell the player who entered this order that their order was skipped. | ## 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 [[Mod API Reference:GameOrderEvent|GameOrderEvent]] will be written into the orders list to tell the player who entered this order that their order was skipped. | ||
## 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. | ## 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. | ||
− | # addNewOrder: A function that you can call to add a [[Mod API Reference:GameOrder|GameOrder]] to the | + | # addNewOrder: A function that you can call to add a [[Mod API Reference:GameOrder|GameOrder]] to the end of the turn. Pass a single GameOrder as the only argument to this function. You may call this function multiple times if you wish. |
− | * Server_AdvanceTurn_End ( | + | * Server_AdvanceTurn_End (Client_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. | ** 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: | ** Arguments: | ||
# [[Mod API Reference:Game|Game]]: Provides read-only information about the game. | # [[Mod API Reference:Game|Game]]: Provides read-only information about the game. | ||
− | # addNewOrder: A function that you can call to add a [[Mod API Reference:GameOrder|GameOrder]] to the | + | # addNewOrder: A function that you can call to add a [[Mod API Reference:GameOrder|GameOrder]] to the end of the turn. Pass a single GameOrder as the only argument to this function. You may call this function multiple times if you wish. |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
== Notes == | == Notes == | ||
Any hooks that start with <code>Server_</code> are run on the server in multi-player games, and on the client in single-player games. | Any hooks that start with <code>Server_</code> are run on the server in multi-player games, and on the client in single-player games. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− |