VASSAL Reference Manual

Mat

Mats are generally larger pieces that are designed to have smaller pieces (Mat Cargo) placed on top of them, and for the cargo pieces to move along with the Mat and maintain their relative position.

When a Game Piece with this trait is selected by left-clicking on it, any game pieces with the Mat Cargo trait that have been placed on top of the Mat piece will also become selected automatically. Therefore, if the Mat game piece is then moved with a drag-and-drop, the cargo pieces conveniently move along with it and maintain their relative positions.

Similarly, when a Mat piece is moved with a Send to Location trait or a Move Fixed Distance trait, cargo pieces on top of it will follow.

WARNING: Mats cannot be made to stack (they are always inherently Does Not Stack), and cannot be placed in Decks if they contain any cargo.

If a Mat piece is rotated or pivoted, any cargo pieces on top can also match their facing to the Mat, if that option is selected in the Mat Cargo trait.

Mats & Cargo - Layers and Draw Order

A Mat and its Mat Cargo, if set to the same Game Piece Layer, when moved will automatically be processed in an order such that the Mat Cargo pieces will remain "on top" of the Mat, visually. Mat Cargo pieces in higher Game Piece Layers will likewise of course always be drawn in front.

A Mat Cargo placed in a lower layer will appear to be beneath the Mat when it is drawn. This can be useful for e.g. "tucking cards underneath a Mat" — the Mat Cargo will still stay attached to the Mat and will still move with it when the Mat is dragged or moved. Warning: This scheme can produce a situation wherein a Mat Cargo piece is inadvertently placed entirely behind the Mat, and in this case simply "moving the Mat out of the way" isn’t easy because the Mat Cargo will automatically maintain its same relative position! The only way to recover from such a situation is to select the Mat (which automatically selects all of its Mat Cargo), then Ctrl+Click (Command+Click on Mac) to unselect the Mat while leaving at least one visible Mat Cargo selected. Then, dragging the still-selected Mat Cargo away will also produce the hidden piece, as it is still part of the selection. A module which wants to detect this situation and remedy it by automatically moving the Mat Cargo elsewhere can attempt to detect it through the use of the CurrentMatOffsetX and CurrentMatOffsetY properties of a Mat Cargo piece, combined with the apply-on-move key command of a Map.

Mat name:

An identifier for the Mat. This is exposed to the module via the MatName property, and is also used when filling the CurrentMat property of Mat Cargo pieces.

Description:

Description of the trait - displayed only in the Editor, in the piece definer dialog.

Mat

Mat2

A Mat and its Mat Cargo pieces rotated 45 degrees in Almoravid

Properties

A Mat trait exposes the following Properties:

  • MatName contains the name of the Mat, taken from the Mat Name field.

  • MatID contains a unique identifying string for the Mat piece: even two pieces sharing the same Mat Name will have different Mat ID’s.

  • MatNumCargo contains the number of Mat Cargo pieces currently sitting on this mat.