VASSAL Reference Manual
Home > Module > Map > DeckDeck
A Deck functions like a deck of playing
cards. Each game begins with the contents of the Deck as
specified
in the Configuration window. During a game, players may remove
cards from the deck by clicking on the deck and dragging the
mouse. This removes the card from the Deck and assigns ownership
to the dragging player. Dragging a card onto the deck adds it
back
to the Deck.
The number of cards in the deck is exposed as a Map-level Property with the name <name>_numPieces.
The number of card types in the deck can be exposed as a Map-level Property with the name <name>_<type> (see Perform Counting of Piece Types below).
In previous versions, a Deck was used for fixed pools of standard counters as well. The At-Start Stack component is now recommended for this use.
Name: The name of a Deck is not used during game play. It is just used for identification in the module editor.
Belongs to board: If a name is selected, the Deck will appear on that particular Board. If a game does not use that Board, then the Deck will not appear. If "<any>" is selected, then the Deck will always appear at the given position, regardless of the boards in use.
X,Y position: The position in the Map Window of the center of the deck. If this Deck belongs to a Board, the position is relative to the Board's position in the Map Window.
Width, Height: The size of the "tray" holding the cards. If the Deck is empty, this determines the area into which players may drag cards to add them back to the Deck. It should be set to the same size as the cards the Deck will hold
Allow Multiple Cards to be Drawn: Adds a right-click menu entry that prompts the user to specify the number of cards to be drawn from the deck with the next drag.
Allow Specific Cards to be Drawn: Adds a right-click menu entry that prompts the user to examine the deck and select exactly which cards will be drawn from the deck with the next drag.
When selecting, list cards using: When the user is prompted to select specific cards from the deck, individual cards will be listed using the specified Message Format.
When selecting, sort cards by: When the user is prompted to select specific cards from the deck, the cards can optionally be sorted (alphabetically) using the listed property. Leave blank to list cards by their curring position in the deck. Example: cards in a deck can use a Marker trait to specify a card number (001,002, etc.) and always list cards in order of their assigned number.
Contents are Face-down: Determines whether cards in the deck are always face-down, always face-up, or can be switched from face-up to face-down with a right-click menu entry.
Face Down Report Format: A Message Format that is echoed to the chat text window whenever a player selects the "Face Down" menu item (if enabled above): deckName is the name of this deck, commandName is the name of the menu item.
Draw new cards face up: If checked, then cards drawn from this deck will be placed face-up on the playing area. If un-checked, then cards in a face-down deck are drawn face down and owned by the drawing player.
Re-shuffle: If set to "Never" then cards remain in their original order; cards are drawn from and added to the top. If set to "Always" then cards are always drawn randomly from the deck. If set to "Via right-click menu" then a "Shuffle" entry is added to the Deck's right-click menu.
Re-shuffle Report Format: A Message Format that is echoed to the chat text window whenever a player selects the "Shuffle" menu item (if enabled above): deckName is the name of this deck, commandName is the name of the menu item.
Reversible: Adds an entry to the right-click menu that reverses the order of cards in the deck.
Reverse Report Format: A Message Format that is echoed to the chat text window whenever a player selects the "Reverse" menu item (if enabled above): deckName is the name of this deck, commandName is the name of the menu item.
Draw Outline When Empty? Whether to draw the "tray" for the cards. The "tray" is a rectangle of size width,height centered at x,y. Only drawn when there are no cards in the deck, to indicate where to drag cards to place them back in the Deck. May not be necessary if the Map Window contains a board onto which the tray is already drawn.
Color: The color of the rectangle representing the "tray" above.
Send Hotkey when empty? Select this option to send a Global Hotkey whenever the Deck is emptied.
Hot Key to send when Deck empties: Select the Hot Key combination to send whenever enough cards are removed from the Deck to empty it.
Include command to send entire deck to another deck: If checked, the popup menu for this deck will include a command that sends every piece in this deck to a designated deck. For example, this can be used to reshuffle a discard pile into its original deck. The following three attributes all refer to this option.
Menu Text: The text that appears in the popup menu.
Report Format: A Message Format that is echoed to the chat text window whenever a player selects the "send to another deck" menu item (if enabled above): deckName is the name of this deck, commandName is the name of the menu item.
Name of deck to send to: The name of the deck that the contents will be sent to.
Can be saved-to/loaded-from a file: If selected, the right-click menu will include "Save" and "Load" actions. The "Save" action saves the contents of a deck to a file. The "Load" action replaces the contents of the deck with the cards specified in the file. Saved decks can be loaded into an entirely different game than the one used to save the deck. This option is useful for collectible card games, in which a player may prepare a deck offline in preparation for a game
Maximum Cards to be Displayed in Stack: This defines the maximum number of cards to graphically display in the deck. The default is 10. For example, if set to 10, a deck of 52 will appear to have 10 cards, until the actual number of contents drops below 10. Then the deck will visually start to shrink as cards are removed. If set to 1, the deck will appear flat like a single card.
Perform Counting of property expressions: Enable processing of property expression counting. Expressions must be defined.
Expressions to count: Specify expressions to be counted within the deck. These can be whatever you like and must be in the format of:
EXAMPLE: An ordinary deck of playing cards for, say, Crazy Eights would be set to: Allow Multiple = false, Allow Specific = false, Face Down = Always, Re-shuffle = Always, Reversible = false. The discard pile would be: Allow Multiple = false, Allow Specific = false, Face Down = Never, Re-shuffle = Never, Reversible = false.
A Deck may contain any kind of Game Piece, so it can also be used for draw piles of chits or counters that are drawn randomly and whose total number are limited by the game. If the counters do not need to be selected randomly, use an At-Start Stack.
EXAMPLE: A strategic game in which a nationality has a fixed force pool of variable-strength Infantry, Armor, etc. counters can be modeled by making a Map Window representing the force pool, with a Deck of Infantry counters, a Deck of Armor counters, etc. The decks would be set to Allow Multiple = false, Allow Specific = false, Face Down = Never, Re-shuffle = Never, Reversible = false. In order to guarantee that the number of each type of counter is fixed, the Clone and Delete functions of the Infantry and Armor counters should be disabled.
EXAMPLE: You want to create a deck of playing cards, and display the number of red cards, the number of black cards, the number of face cards, and the total number of cards in the deck. Create the deck, check "Perform counting of expressions". Add the expressions of "red: color = red" and "black: color = black". Also add the expression "facecards: value > 10". When creating your cards, give them a Marker named "color" with the values of "red" or "black". Also give your cards a Marker named "value" with the numeric value of the card. Then, you can refer to the counts with the map-level properties of "<deckname>_red", "<deckname>_black", and "<deckname>_facecards". The total can be referenced by the map-level property of "<deckname>_numPieces".
The number of cards in the deck is exposed as a Map-level Property with the name <name>_numPieces.
The number of card types in the deck can be exposed as a Map-level Property with the name <name>_<type> (see Perform Counting of Piece Types below).
In previous versions, a Deck was used for fixed pools of standard counters as well. The At-Start Stack component is now recommended for this use.
Name: The name of a Deck is not used during game play. It is just used for identification in the module editor.
Belongs to board: If a name is selected, the Deck will appear on that particular Board. If a game does not use that Board, then the Deck will not appear. If "<any>" is selected, then the Deck will always appear at the given position, regardless of the boards in use.
X,Y position: The position in the Map Window of the center of the deck. If this Deck belongs to a Board, the position is relative to the Board's position in the Map Window.
Width, Height: The size of the "tray" holding the cards. If the Deck is empty, this determines the area into which players may drag cards to add them back to the Deck. It should be set to the same size as the cards the Deck will hold
Allow Multiple Cards to be Drawn: Adds a right-click menu entry that prompts the user to specify the number of cards to be drawn from the deck with the next drag.
Allow Specific Cards to be Drawn: Adds a right-click menu entry that prompts the user to examine the deck and select exactly which cards will be drawn from the deck with the next drag.
When selecting, list cards using: When the user is prompted to select specific cards from the deck, individual cards will be listed using the specified Message Format.
When selecting, sort cards by: When the user is prompted to select specific cards from the deck, the cards can optionally be sorted (alphabetically) using the listed property. Leave blank to list cards by their curring position in the deck. Example: cards in a deck can use a Marker trait to specify a card number (001,002, etc.) and always list cards in order of their assigned number.
Contents are Face-down: Determines whether cards in the deck are always face-down, always face-up, or can be switched from face-up to face-down with a right-click menu entry.
Face Down Report Format: A Message Format that is echoed to the chat text window whenever a player selects the "Face Down" menu item (if enabled above): deckName is the name of this deck, commandName is the name of the menu item.
Draw new cards face up: If checked, then cards drawn from this deck will be placed face-up on the playing area. If un-checked, then cards in a face-down deck are drawn face down and owned by the drawing player.
Re-shuffle: If set to "Never" then cards remain in their original order; cards are drawn from and added to the top. If set to "Always" then cards are always drawn randomly from the deck. If set to "Via right-click menu" then a "Shuffle" entry is added to the Deck's right-click menu.
Re-shuffle Report Format: A Message Format that is echoed to the chat text window whenever a player selects the "Shuffle" menu item (if enabled above): deckName is the name of this deck, commandName is the name of the menu item.
Reversible: Adds an entry to the right-click menu that reverses the order of cards in the deck.
Reverse Report Format: A Message Format that is echoed to the chat text window whenever a player selects the "Reverse" menu item (if enabled above): deckName is the name of this deck, commandName is the name of the menu item.
Draw Outline When Empty? Whether to draw the "tray" for the cards. The "tray" is a rectangle of size width,height centered at x,y. Only drawn when there are no cards in the deck, to indicate where to drag cards to place them back in the Deck. May not be necessary if the Map Window contains a board onto which the tray is already drawn.
Color: The color of the rectangle representing the "tray" above.
Send Hotkey when empty? Select this option to send a Global Hotkey whenever the Deck is emptied.
Hot Key to send when Deck empties: Select the Hot Key combination to send whenever enough cards are removed from the Deck to empty it.
Include command to send entire deck to another deck: If checked, the popup menu for this deck will include a command that sends every piece in this deck to a designated deck. For example, this can be used to reshuffle a discard pile into its original deck. The following three attributes all refer to this option.
Menu Text: The text that appears in the popup menu.
Report Format: A Message Format that is echoed to the chat text window whenever a player selects the "send to another deck" menu item (if enabled above): deckName is the name of this deck, commandName is the name of the menu item.
Name of deck to send to: The name of the deck that the contents will be sent to.
Can be saved-to/loaded-from a file: If selected, the right-click menu will include "Save" and "Load" actions. The "Save" action saves the contents of a deck to a file. The "Load" action replaces the contents of the deck with the cards specified in the file. Saved decks can be loaded into an entirely different game than the one used to save the deck. This option is useful for collectible card games, in which a player may prepare a deck offline in preparation for a game
Maximum Cards to be Displayed in Stack: This defines the maximum number of cards to graphically display in the deck. The default is 10. For example, if set to 10, a deck of 52 will appear to have 10 cards, until the actual number of contents drops below 10. Then the deck will visually start to shrink as cards are removed. If set to 1, the deck will appear flat like a single card.
Perform Counting of property expressions: Enable processing of property expression counting. Expressions must be defined.
Expressions to count: Specify expressions to be counted within the deck. These can be whatever you like and must be in the format of:
<expression name> : <expression>For each expression, a map-level property called <deckName>_<expression name> is exposed. The exposed value is number of pieces for which that expression evaluates to true. An example of how to do this is provided below. NOTE: Currently the only "dynamic" property which can be used in counting expressions is playerSide. Other dynamic properties will most likely not update if they change after pieces move into a deck.
EXAMPLE: An ordinary deck of playing cards for, say, Crazy Eights would be set to: Allow Multiple = false, Allow Specific = false, Face Down = Always, Re-shuffle = Always, Reversible = false. The discard pile would be: Allow Multiple = false, Allow Specific = false, Face Down = Never, Re-shuffle = Never, Reversible = false.
A Deck may contain any kind of Game Piece, so it can also be used for draw piles of chits or counters that are drawn randomly and whose total number are limited by the game. If the counters do not need to be selected randomly, use an At-Start Stack.
EXAMPLE: A strategic game in which a nationality has a fixed force pool of variable-strength Infantry, Armor, etc. counters can be modeled by making a Map Window representing the force pool, with a Deck of Infantry counters, a Deck of Armor counters, etc. The decks would be set to Allow Multiple = false, Allow Specific = false, Face Down = Never, Re-shuffle = Never, Reversible = false. In order to guarantee that the number of each type of counter is fixed, the Clone and Delete functions of the Infantry and Armor counters should be disabled.
EXAMPLE: You want to create a deck of playing cards, and display the number of red cards, the number of black cards, the number of face cards, and the total number of cards in the deck. Create the deck, check "Perform counting of expressions". Add the expressions of "red: color = red" and "black: color = black". Also add the expression "facecards: value > 10". When creating your cards, give them a Marker named "color" with the values of "red" or "black". Also give your cards a Marker named "value" with the numeric value of the card. Then, you can refer to the counts with the map-level properties of "<deckname>_red", "<deckname>_black", and "<deckname>_facecards". The total can be referenced by the map-level property of "<deckname>_numPieces".