Mod API Reference:Custom Cards
A Warzone 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
A mod defines the custom cards in the Client_SaveConfigureUI mod hook. The second parameter to this function is a callback that adds a card.
This function takes the following arguments:
- string: Name of the card
- string: Description of the card
- string: Image filename (see Image below)
- 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: 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
If you'd like for your card to be configurable by the player like a normal card, you should let the player select values for the number of pieces, minimum pieces, initial pieces, and weight.
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 GameOrderEvent yourself to award your card to players.
Playing the Card
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:
- Game: Provides read-only information about the game.
- 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 two arguments: 1. The text to appear in the orders list next to the play-card order, and 2. a string that will be stored with the order in a field called ModData.
If you don't require any additional information from the user, you can simply call playCard immediately, for example:
function Client_PresentPlayCardUI(game, cardInstance, playCard)
playCard('Play a magic card', '')
end
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.
Image
Mods can upload their own image to define what the card looks like in the cards dialog. These should be a png file that's exactly 130 pixels wide and 180 pixels tall. Place this image into a sub-folder in your mod folder named CardImages. Then pass the name of your image to the third parameter of the add card function defined above.