VASSAL Reference Manual

Deck

A Deck functions like a deck of playing cards, but can also be used to hold a supply of other types of Game Piece, such as a fixed supply of counters or a "bag of chits" to be randomly drawn from. 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 dragging them from the top of the deck with the mouse. This removes a 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 or pieces in the deck is exposed as a Map-level Property with the name <name>_numPieces.
The number of card or piece types in the deck can be exposed as a Map-level Property with the name <name><type>_ (see Perform Counting of Piece Types below).

Decks can be added to Maps, and also to Player Hands and Private Windows, each of which is simply a specialized type of Map. To add a Deck, navigate to the [Map], [Player Hand], or [Private Window] component entry in the Editor configuration window for the Map (or specialized map) you wish to add the Deck to. Right-click on that component and select Add Deck from the menu. After you have configured your Deck and clicked the OK button, your new [Deck] component will appear at the bottom of the map’s list of Sub-Components. You can then right-click on the [Deck] entry and begin adding Cards and other Deck Sub-Components.

Note

Because Decks are quite often used to hold "cards", the Game Pieces contained within a Deck will be frequently referred to in Vassal and in documentation as "cards". However, keep in mind that a "card" is simply a type of Game Piece, and a Deck can be used to contain any type of Game Piece. The difference between a "card" and a "piece" is only notional, and perhaps represented in the artwork and function of the piece/card.

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 pieces/cards do not need to be selected randomly, and you simply wish to provide a pile of them on the board at game start, consider 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, any Clone and Delete traits of the Infantry and Armor counters should be removed.

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 trait named color with the values of red or black depending on the card. Also give your cards a Marker trait 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 number of cards currently in the deck can be referenced by the map-level property of <deckname>_numPieces.

Name:

The name of a Deck is not used during game play. It is only used for identification in the Editor. The name should be unique. If multiple decks with the same name are created the return to deck trait will send cards to the first deck with that name.

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, as well as the box drawn if the Draw Outline When Empty option is selected below. It should be set to approximately the same size as the cards the Deck will hold.

Allow multiple cards to be drawn:

Adds a right-click context menu entry to the Deck’s context menu that prompts the user to specify the number of cards to be drawn from the Deck with the next drag.

Menu command to draw multiple:

The text of the menu option to draw multiple cards from the deck when the draw multiple option is selected.

Allow specific cards to be drawn:

Adds a right-click context menu entry to the Deck’s context menu that allows the player to examine the Deck and select exactly which cards will be drawn from the deck with the next drag.

Menu command to draw specific:

The text of the menu option to draw specific cards from the deck when the draw specific option is selected.

When selecting, list cards using:

When the player 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 player 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 current position in the deck.

Note	Unlike the previous field this field simply names a single property, and should not use $..$ markers. To sort by multiple fields a Calculated Property trait e.g. SortName can be created and serve to concatenate the various fields in an appropriate order.

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: in this case simply fill CardNum into the field, no $..$.

Contents are face-down:

Determines whether cards in the Deck are always drawn face-down, always drawn face-up, or can be switched from face-up to face-down with a right-click context menu entry.

Menu command to turn deck face up:

Text of the menu command to change the facing of subsequent cards drawn from the deck to face up.

Menu command to turn deck face down:

Text of the menu command to change the facing of subsequent cards drawn from the deck to face down.

Draw new cards face up:

If checked, then cards drawn from this Deck (e.g. by dragging them) will be placed face-up on the playing area. If unchecked, then cards from a face-down deck are drawn face down and owned by the drawing player.

Face down report format:

A Message Format that is echoed to the chat log 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.

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 context menu.

Re-shuffle menu command:

The right-click context menu entry for reshuffling the Deck.

Re-shuffle report format:

A Message Format that is echoed to the chat log whenever a player selects the Shuffle menu item (if enabled above): deckName is the name of this Deck, commandName is the name of the context menu item.

Re-shuffle hotkey:

A Keystroke or Named Command that will cause a reshuffle. If left blank, a reshuffle can be caused only with the right-click context menu.

Reversible:

Adds an entry to the right-click context menu that reverses the order of cards in the Deck.

Reverse menu command:

The right-click context menu entry for reversing the Deck.

Reverse report format:

A Message Format that is echoed to the chat log window whenever a player selects the "Reverse" menu item: deckName is the name of this deck, commandName is the name of the menu item.

Reverse hotkey:

A Keystroke or Named Command that will cause a reverse.

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 or desirable if the Map Window contains a board on which the tray is already shown.

Color:

The color used to draw the rectangle representing the "tray" above.

Hotkey to send when Deck empties:

Select the Keystroke Command or Named Command 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 right-click context menu for this Deck will include a command that sends every Game Piece in this Deck to a different designated Deck. For example, this can be used to reshuffle a discard pile into its original deck. The following four attributes are used to configure this option.

Send menu command:

The text for the right-click context menu item.

Send report format:

A Send Message Format that is echoed to the chat log window whenever a player selects the "send to another deck" menu item: deckName is the name of this deck, commandName is the name of the menu item.

Send Hotkey:

Select a Keystroke Command or Named Command that will cause the Deck contents to be moved to the target Deck.

Name of deck to send to:

The name of the Deck that the contents of this Deck will be sent to.

Can be saved-to/loaded-from a file:

If selected, the right-click context 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 cards 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 always appear flat as if it held only 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>

Examples (using old-style and new-style expressions, respectively):

battleships:BB=1
cruisers:{CA==1}

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. In the above example, if the deck’s Name field contained Ships, then the properties Ships_battleships and Ships_cruisers would be exposed.

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.

Restrict adding counters by Drag 'n Drop:: When selected, you can add an expressions that Cards must satisfy to be allowed to be added to a Deck manually by Drag 'n Drop movement. If a Player drops a card onto the Deck that does not satisfy the expression, then the card will 'snap' back to where it was dragged from.

Note	This option does NOT affect cards being added to the Deck by any other mechanism, other than manual Drag 'n Drop.

Dropped counters must match expression:: Enter a Property Match Expression that when evaluated against each Card must evaluate to true to allow the Card to be added to the Deck.

Deck

Sub-Components

Sub-Components can be added to a Deck by right-clicking on the [Deck] entry in the Module Editor and selecting the appropriate Add option.