Mod API Reference:Custom Cards - Revision history

Fizzer at 02:35, 18 April 2026

2026-04-18T02:35:54Z

← Older revision		Revision as of 02:35, 18 April 2026
Line 1:		Line 1:
	A ~~Warzone~~ [[Mods\|mod]] can create '''custom cards''' for use in a game. Custom cards show up the cards dialog right alongside all the other cards for the game.		A War.app [[Mods\|mod]] can create '''custom cards''' for use in a game. Custom cards show up the cards dialog right alongside all the other cards for the game.

	== Card Definition ==		== Card Definition ==
Line 10:		Line 10:
	# ''string'': Image filename (see Image below)		# ''string'': Image filename (see Image below)
	# ''integer'': Number of pieces to divide the card into		# ''integer'': Number of pieces to divide the card into
	# ''integer'': Minimum number of pieces that ~~Warzone~~ will award to each player who takes a territory each turn		# ''integer'': Minimum number of pieces that War.app will award to each player who takes a territory each turn
	# ''.integer'': Number of pieces of the card given to each player at the start of the game (initial pieces)		# ''.integer'': Number of pieces of the card given to each player at the start of the game (initial pieces)
	# ''double'': The card's weight, which determines how likely it is to be selected when using random card distribution		# ''double'': The card's weight, which determines how likely it is to be selected when using random card distribution
Line 22:		Line 22:
	If you'd like your card to only be distributed at the beginning of the game and never again, you can pass 1 for the number of pieces, 0 for weight and minimum pieces, and initial pieces to the number of cards you want distributed at the game start.		If you'd like your card to only be distributed at the beginning of the game and never again, you can pass 1 for the number of pieces, 0 for weight and minimum pieces, and initial pieces to the number of cards you want distributed at the game start.

	If you desire full control over when players receive your card and want to override ~~Warzone~~'s normal card distribution, you can pass 0 for weight, minimum pieces and initial pieces, and then you can use [[Mod API Reference:GameOrderEvent\|GameOrderEvent]] yourself to award your card to players.		If you desire full control over when players receive your card and want to override War.app's normal card distribution, you can pass 0 for weight, minimum pieces and initial pieces, and then you can use [[Mod API Reference:GameOrderEvent\|GameOrderEvent]] yourself to award your card to players.

	== Playing the Card ==		== Playing the Card ==

JustADutchman: /* Playing the Card */

2025-11-23T14:08:45Z

Playing the Card

← Older revision		Revision as of 14:08, 23 November 2025
Line 47:		Line 47:
	</pre>		</pre>

	If you do require additional ~~infirmation~~ from the user, you can call game.CreateDialog to create a dialog and later call playCard from a button callback, for example.		If you do require additional information from the user, you can call game.CreateDialog to create a dialog and later call playCard from a button callback, for example.

	Note: in versions under 5.34.0, [[Mod Game Data Storage\|Mod]] and [[Mod API Reference:UI\|UI]] are not directly accessible in Client_PresentPlayCardUI. They can be accessed in the callback function in [[Mod API Reference:ClientGame\|Game]].CreateDialog. [[Mod API Reference:WL\|WL]] was always accessible when the hook was introduced.		Note: in versions under 5.34.0, [[Mod Game Data Storage\|Mod]] and [[Mod API Reference:UI\|UI]] are not directly accessible in Client_PresentPlayCardUI. They can be accessed in the callback function in [[Mod API Reference:ClientGame\|Game]].CreateDialog. [[Mod API Reference:WL\|WL]] was always accessible when the hook was introduced.

JustADutchman at 14:08, 23 November 2025

2025-11-23T14:08:22Z

← Older revision		Revision as of 14:08, 23 November 2025
Line 37:		Line 37:
	## (optional) ''Table<[[Mod API Reference:TerritoryID\|TerritoryID]],[[Mod API Reference:TerritoryAnnotation\|TerritoryAnnotation]]>'': When the order is selected in the orders list by the player, these messages will be presented on top of the territories specified. (Added in version 5.34.1)		## (optional) ''Table<[[Mod API Reference:TerritoryID\|TerritoryID]],[[Mod API Reference:TerritoryAnnotation\|TerritoryAnnotation]]>'': When the order is selected in the orders list by the player, these messages will be presented on top of the territories specified. (Added in version 5.34.1)
	## (optional) ''[[Mod API Reference:RectangleVM\|RectangleVM]]'': If specified, this will be the spot on the map that the map focuses on when the player clicks on this event in the orders list. Specify coordinates on the map, which you can get by looking at a [[Mod API Reference:TerritoryDetails\|TerritoryDetails]] object. (added in version 5.34.1)		## (optional) ''[[Mod API Reference:RectangleVM\|RectangleVM]]'': If specified, this will be the spot on the map that the map focuses on when the player clicks on this event in the orders list. Specify coordinates on the map, which you can get by looking at a [[Mod API Reference:TerritoryDetails\|TerritoryDetails]] object. (added in version 5.34.1)

	# closeCardsDialog: A function that, when called, closes the main cards dialog. This is commonly used when your mod creates a new dialog that wants to interact with the map, since the cards dialog could overlap the map making it cumbersome for the player. Added in version 5.34.0		# closeCardsDialog: A function that, when called, closes the main cards dialog. This is commonly used when your mod creates a new dialog that wants to interact with the map, since the cards dialog could overlap the map making it cumbersome for the player. Added in version 5.34.0

Fizzer at 22:16, 29 March 2025

2025-03-29T22:16:50Z

← Older revision		Revision as of 22:16, 29 March 2025
Line 31:		Line 31:
	# [[Mod API Reference:Game\|Game]]: Provides read-only information about the game.		# [[Mod API Reference:Game\|Game]]: Provides read-only information about the game.
	# [[Mod API Reference:CardInstance\|CardInstance]]: Provides read-only information about the card the player is attempting to play.		# [[Mod API Reference:CardInstance\|CardInstance]]: Provides read-only information about the card the player is attempting to play.
	# playCard: A function that, when called, will cause the card to be played. It takes ~~three~~ arguments: 1. The text to appear in the orders list next to the play-card order~~, 2.~~ a string that will be stored with the order in a field called ModData~~, and 3.~~ (optional) the [[Mod API Reference:TurnPhase\|turn phase]] in which the card should be played. Custom turn phases cannot be used.		# playCard: A function that, when called, will cause the card to be played. It takes the following arguments:
			## The text to appear in the orders list next to the play-card order
			## a string that will be stored with the order in a field called ModData
			## (optional) the [[Mod API Reference:TurnPhase\|turn phase]] in which the card should be played. Custom turn phases cannot be used.
			## (optional) ''Table<[[Mod API Reference:TerritoryID\|TerritoryID]],[[Mod API Reference:TerritoryAnnotation\|TerritoryAnnotation]]>'': When the order is selected in the orders list by the player, these messages will be presented on top of the territories specified. (Added in version 5.34.1)
			## (optional) ''[[Mod API Reference:RectangleVM\|RectangleVM]]'': If specified, this will be the spot on the map that the map focuses on when the player clicks on this event in the orders list. Specify coordinates on the map, which you can get by looking at a [[Mod API Reference:TerritoryDetails\|TerritoryDetails]] object. (added in version 5.34.1)

	# closeCardsDialog: A function that, when called, closes the main cards dialog. This is commonly used when your mod creates a new dialog that wants to interact with the map, since the cards dialog could overlap the map making it cumbersome for the player. Added in version 5.34.0		# closeCardsDialog: A function that, when called, closes the main cards dialog. This is commonly used when your mod creates a new dialog that wants to interact with the map, since the cards dialog could overlap the map making it cumbersome for the player. Added in version 5.34.0

Fizzer at 22:01, 29 March 2025

2025-03-29T22:01:41Z

← Older revision		Revision as of 22:01, 29 March 2025
Line 14:		Line 14:
	# ''double'': The card's weight, which determines how likely it is to be selected when using random card distribution		# ''double'': The card's weight, which determines how likely it is to be selected when using random card distribution
	# ''integer'': The duration, in turns, that the card should remain in effect. Pass -1, nil, or omit this argument to indicate that the card should not have a duration.		# ''integer'': The duration, in turns, that the card should remain in effect. Pass -1, nil, or omit this argument to indicate that the card should not have a duration.
			# ''[[Mod API Reference:ActiveCardExpireBehaviorOptions\|ActiveCardExpireBehaviorOptions]]'': If a duration is specified, this controls whether the card expires at the beginning or end of the turn. Pass nil or omit this argument for cards where a duration is not passed. If omitted or nil is passed for a card with duration, it will default to EndOfTurn. (Added in version 5.34.1)

	This function returns the [[Mod API Reference:CardID\|CardID]] in [[Mod API Reference:IsVersionOrHigher\|versions 5.32.0.1 and later]].		This function returns the [[Mod API Reference:CardID\|CardID]] in [[Mod API Reference:IsVersionOrHigher\|versions 5.32.0.1 and later]].

Fizzer at 21:19, 16 March 2025

2025-03-16T21:19:08Z

← Older revision		Revision as of 21:19, 16 March 2025
Line 14:		Line 14:
	# ''double'': The card's weight, which determines how likely it is to be selected when using random card distribution		# ''double'': The card's weight, which determines how likely it is to be selected when using random card distribution
	# ''integer'': The duration, in turns, that the card should remain in effect. Pass -1, nil, or omit this argument to indicate that the card should not have a duration.		# ''integer'': The duration, in turns, that the card should remain in effect. Pass -1, nil, or omit this argument to indicate that the card should not have a duration.
	# ''[[Mod API Reference:ActiveCardExpireBehaviorOptions\|ActiveCardExpireBehaviorOptions]]'': If a duration is specified, this controls whether the card expires at the beginning or end of the turn. Pass nil or omit this argument for cards where a duration is not passed. If omitted or nil is passed for a card with duration, it will default to BeginningOfNextTurn.

	This function returns the [[Mod API Reference:CardID\|CardID]] in [[Mod API Reference:IsVersionOrHigher\|versions 5.32.0.1 and later]].		This function returns the [[Mod API Reference:CardID\|CardID]] in [[Mod API Reference:IsVersionOrHigher\|versions 5.32.0.1 and later]].

Fizzer at 18:33, 16 March 2025

2025-03-16T18:33:32Z

← Older revision		Revision as of 18:33, 16 March 2025
Line 14:		Line 14:
	# ''double'': The card's weight, which determines how likely it is to be selected when using random card distribution		# ''double'': The card's weight, which determines how likely it is to be selected when using random card distribution
	# ''integer'': The duration, in turns, that the card should remain in effect. Pass -1, nil, or omit this argument to indicate that the card should not have a duration.		# ''integer'': The duration, in turns, that the card should remain in effect. Pass -1, nil, or omit this argument to indicate that the card should not have a duration.
	# ''[[Mod API Reference:ActiveCardExpireBehaviorOptions\|ActiveCardExpireBehaviorOptions]]'': If a duration is specified, this controls whether the card expires at the beginning or end of the turn. Pass nil or omit this argument for cards where a duration is not passed.		# ''[[Mod API Reference:ActiveCardExpireBehaviorOptions\|ActiveCardExpireBehaviorOptions]]'': If a duration is specified, this controls whether the card expires at the beginning or end of the turn. Pass nil or omit this argument for cards where a duration is not passed. If omitted or nil is passed for a card with duration, it will default to BeginningOfNextTurn.

	This function returns the [[Mod API Reference:CardID\|CardID]] in [[Mod API Reference:IsVersionOrHigher\|versions 5.32.0.1 and later]].		This function returns the [[Mod API Reference:CardID\|CardID]] in [[Mod API Reference:IsVersionOrHigher\|versions 5.32.0.1 and later]].

Fizzer at 18:25, 16 March 2025

2025-03-16T18:25:10Z

← Older revision		Revision as of 18:25, 16 March 2025
Line 13:		Line 13:
	# ''.integer'': Number of pieces of the card given to each player at the start of the game (initial pieces)		# ''.integer'': Number of pieces of the card given to each player at the start of the game (initial pieces)
	# ''double'': The card's weight, which determines how likely it is to be selected when using random card distribution		# ''double'': The card's weight, which determines how likely it is to be selected when using random card distribution
			# ''integer'': The duration, in turns, that the card should remain in effect. Pass -1, nil, or omit this argument to indicate that the card should not have a duration.
			# ''[[Mod API Reference:ActiveCardExpireBehaviorOptions\|ActiveCardExpireBehaviorOptions]]'': If a duration is specified, this controls whether the card expires at the beginning or end of the turn. Pass nil or omit this argument for cards where a duration is not passed.

	This function returns the [[Mod API Reference:CardID\|CardID]] in [[Mod API Reference:IsVersionOrHigher\|versions 5.32.0.1 and later]].		This function returns the [[Mod API Reference:CardID\|CardID]] in [[Mod API Reference:IsVersionOrHigher\|versions 5.32.0.1 and later]].

DanWL60: /* Playing the Card */ note about Mod and UI not directly accessible in Client_PresentPlayCardUI in older versions

2025-03-10T22:29:53Z

Playing the Card: note about Mod and UI not directly accessible in Client_PresentPlayCardUI in older versions

← Older revision		Revision as of 22:29, 10 March 2025
Line 41:		Line 41:

	If you do require additional infirmation from the user, you can call game.CreateDialog to create a dialog and later call playCard from a button callback, for example.		If you do require additional infirmation from the user, you can call game.CreateDialog to create a dialog and later call playCard from a button callback, for example.

			Note: in versions under 5.34.0, [[Mod Game Data Storage\|Mod]] and [[Mod API Reference:UI\|UI]] are not directly accessible in Client_PresentPlayCardUI. They can be accessed in the callback function in [[Mod API Reference:ClientGame\|Game]].CreateDialog. [[Mod API Reference:WL\|WL]] was always accessible when the hook was introduced.

	== Image ==		== Image ==

JustADutchman at 22:07, 10 March 2025

2025-03-10T22:07:50Z

← Older revision		Revision as of 22:07, 10 March 2025
Line 26:		Line 26:
	Mods get complete control exactly what happens when the card is played. When the player attempts to play your card, it will call the function Client_PresentPlayCardUI in Client_PresentPlayCardUI.lua for your mod only.		Mods get complete control exactly what happens when the card is played. When the player attempts to play your card, it will call the function Client_PresentPlayCardUI in Client_PresentPlayCardUI.lua for your mod only.

	Client_PresentPlayCardUI is passed ~~three~~ arguments:		Client_PresentPlayCardUI is passed four 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.
	# [[Mod API Reference:CardInstance\|CardInstance]]: Provides read-only information about the card the player is attempting to play.		# [[Mod API Reference:CardInstance\|CardInstance]]: Provides read-only information about the card the player is attempting to play.