Mod Hooks - Revision history

Fizzer at 02:36, 18 April 2026

2026-04-18T02:36:09Z

← Older revision		Revision as of 02:36, 18 April 2026
Line 1:		Line 1:
	~~Warzone~~ will call into a [[Mods\|mod's]] lua code using what are called '''hooks'''.		War.app 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 143:		Line 143:
	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.

	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.		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 War.app 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 War.app must decide which to obey.

	== See also ==		== See also ==

JustADutchman: /* Client Hooks */ Added some additional newlines

2025-04-09T19:03:24Z

Client Hooks: Added some additional newlines

← Older revision		Revision as of 19:03, 9 April 2025
Line 83:		Line 83:
	# 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.		# 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.
	# addCard: A function callback used by [[Mod API Reference:Custom Cards\|Custom Cards]]		# addCard: A function callback used by [[Mod API Reference:Custom Cards\|Custom Cards]]


	* Client_CreateGame (Client_CreateGame.lua)		* Client_CreateGame (Client_CreateGame.lua)
Line 89:		Line 90:
	# settings: [[Mod API Reference:GameSettings\|GameSettings]]		# settings: [[Mod API Reference:GameSettings\|GameSettings]]
	# 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 game creation.		# 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 game creation.


	* Client_PresentSettingsUI (Client_PresentSettingsUI.lua)		* Client_PresentSettingsUI (Client_PresentSettingsUI.lua)

Fizzer at 03:10, 30 March 2025

2025-03-30T03:10:37Z

← Older revision		Revision as of 03:10, 30 March 2025
Line 84:		Line 84:
	# addCard: A function callback used by [[Mod API Reference:Custom Cards\|Custom Cards]]		# addCard: A function callback used by [[Mod API Reference:Custom Cards\|Custom Cards]]

			* Client_CreateGame (Client_CreateGame.lua)
			** Called when a player attempts to create a game with your mod included. If your mod wishes to check that the game settings are valid before the game is created, you can do so here. Note that you should do as much validation as possible in Client_SaveConfigureUI, however Client_CreateGame can be used to do additional validation that isn't possible in Client_SaveConfigureUI, such as if the player changed settings after leaving the mod configuration page.
			** Arguments:
			# settings: [[Mod API Reference:GameSettings\|GameSettings]]
			# 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 game creation.

	* Client_PresentSettingsUI (Client_PresentSettingsUI.lua)		* Client_PresentSettingsUI (Client_PresentSettingsUI.lua)

Fizzer at 05:36, 22 February 2025

2025-02-22T05:36:40Z

← Older revision		Revision as of 05:36, 22 February 2025
Line 128:		Line 128:
	# [[Mod API Reference:ClientGame\|ClientGame]]: Information about the game.		# [[Mod API Reference:ClientGame\|ClientGame]]: Information about the game.
	# close: Function that, when called, will close the current dialog. Takes no arguments and returns nothing.		# close: Function that, when called, will close the current dialog. Takes no arguments and returns nothing.


			* Client_PresentPlayCardUI (Client_PresentPlayCardUI.lua)
			** See [[Mod_API_Reference:Custom_Cards\|Custom Cards]]

	== Notes ==		== Notes ==

Fizzer at 23:15, 18 January 2025

2025-01-18T23:15:20Z

← Older revision		Revision as of 23:15, 18 January 2025
Line 82:		Line 82:
	** Arguments:		** 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.		# 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.
			# addCard: A function callback used by [[Mod API Reference:Custom Cards\|Custom Cards]]

Fizzer at 22:49, 18 January 2025

2025-01-18T22:49:04Z

← Older revision		Revision as of 22:49, 18 January 2025
Line 98:		Line 98:
	# [[Mod API Reference:ClientGame\|ClientGame]]: Information about the game.		# [[Mod API Reference:ClientGame\|ClientGame]]: Information about the game.
	# close: Function that, when called, will close the current dialog. Takes no arguments and returns nothing.		# close: Function that, when called, will close the current dialog. Takes no arguments and returns nothing.


	* Client_GameOrderCreated (Client_GameOrderCreated.lua)		* Client_GameOrderCreated (Client_GameOrderCreated.lua)
Line 105:		Line 106:
	# [[Mod API Reference:GameOrder\|GameOrder]]: Read-only information about the order that was just created.		# [[Mod API Reference:GameOrder\|GameOrder]]: Read-only information about the order that was just created.
	# skipOrder: Function that, when called, will cause the order to not be inserted into the player's order list. If you call this, you should also ensure the player understands why the order was skipped, such as by popping up an alert, otherwise players could become confused about why their orders aren't being recorded. Note that if you use this for skipping invalid orders, you must still take care to ensure invalid orders are skipped on the server as well, as a clever player could hack their client to prevent Client_GameOrderCreated from being called at all.		# skipOrder: Function that, when called, will cause the order to not be inserted into the player's order list. If you call this, you should also ensure the player understands why the order was skipped, such as by popping up an alert, otherwise players could become confused about why their orders aren't being recorded. Note that if you use this for skipping invalid orders, you must still take care to ensure invalid orders are skipped on the server as well, as a clever player could hack their client to prevent Client_GameOrderCreated from being called at all.


	* Client_GameCommit (Client_GameCommit.lua)		* Client_GameCommit (Client_GameCommit.lua)

Fizzer at 22:48, 18 January 2025

2025-01-18T22:48:45Z

← Older revision		Revision as of 22:48, 18 January 2025
Line 98:		Line 98:
	# [[Mod API Reference:ClientGame\|ClientGame]]: Information about the game.		# [[Mod API Reference:ClientGame\|ClientGame]]: Information about the game.
	# close: Function that, when called, will close the current dialog. Takes no arguments and returns nothing.		# close: Function that, when called, will close the current dialog. Takes no arguments and returns nothing.

			* Client_GameOrderCreated (Client_GameOrderCreated.lua)
			** If present, whenever a player creates an order in the client, this function will be called. For example, whenever they deploy armies, issue an attack, play a card, etc.
			** Arguments:
			# [[Mod API Reference:ClientGame\|ClientGame]]: Information about the game.
			# [[Mod API Reference:GameOrder\|GameOrder]]: Read-only information about the order that was just created.
			# skipOrder: Function that, when called, will cause the order to not be inserted into the player's order list. If you call this, you should also ensure the player understands why the order was skipped, such as by popping up an alert, otherwise players could become confused about why their orders aren't being recorded. Note that if you use this for skipping invalid orders, you must still take care to ensure invalid orders are skipped on the server as well, as a clever player could hack their client to prevent Client_GameOrderCreated from being called at all.

			* Client_GameCommit (Client_GameCommit.lua)
			** If present, whenever a player clicks the Commit button in the client, this function will be called.
			** Arguments:
			# [[Mod API Reference:ClientGame\|ClientGame]]: Information about the game.
			# skipCommit: Function that, when called, will cause the commit request to be cancelled. If you call this, you should also ensure the player understands why they aren't being allowed to commit, such as by popping up an alert, otherwise players could become confused about why it isn't working. Note that if you use this for validating orders are correct, you must still take care to ensure invalid orders are checked on the server as well, as a clever player could hack their client to prevent Client_GameCommit from being called at all.

DanWL60 at 17:46, 5 October 2024

2024-10-05T17:46:19Z

Show changes

Kaninchen: /* Server Hooks */ changed the location for the Mod Security hint so there isn't a random dot floating around

2024-04-18T16:55:03Z

Server Hooks: changed the location for the Mod Security hint so there isn't a random dot floating around

← Older revision		Revision as of 16:55, 18 April 2024
Line 64:		Line 64:
	* Server_GameCustomMessage (Server_GameCustomMessage.lua)		* Server_GameCustomMessage (Server_GameCustomMessage.lua)
	** Called whenever your mod calls [[Mod API Reference:ClientGame\|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.		** Called whenever your mod calls [[Mod API Reference:ClientGame\|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\|Mod security]] should be applied when working with this Hook
	** 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.
Line 69:		Line 70:
	# payload: The data passed as the ''payload'' parameter to SendGameCustomMessage. Must be a lua table.		# payload: The data passed as the ''payload'' parameter to SendGameCustomMessage. Must be a lua table.
	# 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.		# 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.
	**[[Mod_Security\|Mod security]] should be applied when working with this Hook

	== Client Hooks ==		== Client Hooks ==

Fizzer: Reverted edits by Fizzer (talk) to last revision by Kaninchen

2024-04-17T21:48:17Z

Reverted edits by Fizzer (talk) to last revision by Kaninchen

← Older revision		Revision as of 21:48, 17 April 2024
Line 7:		Line 7:
	== Server Hooks ==		== Server Hooks ==

	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 69:		Line 69:
	# payload: The data passed as the ''payload'' parameter to SendGameCustomMessage. Must be a lua table.		# payload: The data passed as the ''payload'' parameter to SendGameCustomMessage. Must be a lua table.
	# 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.		# 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.
			**[[Mod_Security\|Mod security]] should be applied when working with this Hook

	== Client Hooks ==		== Client Hooks ==