VASSAL Reference Manual

Home > Module > Game Piece Palette > Game Piece > Mat Cargo

Mat Cargo

A Mat Cargo piece has special capabilities when placed on top of a larger Mat piece: they will select automatically when their parent Mat is left-clicked, and will attempt to move with it and even optionally maintain the same facing.

When a Game Piece with the Mat 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 Mat 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.

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.

Description:: Description of the trait - displayed only in the Editor, in the piece definer dialog.
Maintain facing relative to mat:: If checked, then the cargo piece will attempt to maintain its relative facing to any Mat it has been placed on, changing facing if/when the Mat rotates.

Note

This means that like a Can Rotate trait, the Mat Cargo trait should be placed below the graphical elements (e.g., Layer and Non-Rectangular Traits) to potentially be rotated. A Mat Cargo piece does not need a separate Can Rotate trait in order to be able to maintain relative facing, although it is permitted to have its own Can Rotate trait as well.

X Extra detection distance from center:: If non-zero, then VASSAL will look this distance to the left and right of the piece’s center when trying to attach it to a mat. Useful, e.g., for cards that are tucked halfway under a mat surface, as it does not require the precise center of the card to be on the mat.
Y Extra detection distance from center:: If non-zero, then VASSAL will look this distance above and below the piece’s center when trying to attach it to a mat. Useful, e.g., for cards that are tucked halfway under a mat surface, as it does not require the precise center of the card to be on the mat.
Key Command to force attach to any mat found at current location:: If the piece receives this key command, it will immediately search for (and attempt to attach itself to) any available mat at its current location; if it was already attached to a mat but is no longer overlapping it, it will be detached. Note that attachment and detachment are normally handled automatically whenever a cargo piece is moved, but this allows a check to be forced explicitly in special situations. An example of such a situation would be if you’ve just "shrunk" the mat (changed its visual shape to be smaller) and want to drop of all the pieces no longer overlapping the mat.
Key Command to force detach from any current mat:: If the piece receives this key command, it will immediately detach itself from any mat it is currently sitting on. This does not in-and-of-itself move the piece from being in its current map position, but does mean that if the mat is subsequently moved, clicked, or dragged it will not take this piece with it.

MatCargo

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

Properties

A Mat Cargo trait exposes the following Properties:

CurrentMat contains the name of any Mat that the Mat Cargo piece is currently sitting atop, taken from the Mat’s Mat Name field. If the piece is not sitting on any Mat, this property will contain the empty string "".
CurrentMatID contains a unique string identifier for the Mat that the Mat Cargo piece is currently sitting atop. The string will be unique among even Mat pieces sharing the same Mat Name property. If the piece is not sitting on any Mat, this property will contain the empty string "".
CurrentMatX contains the X position of the Mat that the Mat Cargo piece is currently sitting on. If the piece is not sitting on any Mat, this property will contain the empty string "".
CurrentMatY contains the Y position of the Mat that the Mat Cargo piece is currently sitting on. If the piece is not sitting on any Mat, this property will contain the empty string "".
CurrentMatOffsetX contains an offset from this piece’s X position to the X position of the Mat that the Mat Cargo piece is currently sitting on. For example if the Mat is at 10 and the Cargo is at 20 then this property will contain -10. If the piece is not sitting on any Mat, this property will contain the empty string "".
CurrentMatOffsetY contains an offset from this piece’s Y position to the Y position of the Mat that the Mat Cargo piece is currently sitting on. For example if the Mat is at 10 and the Cargo is at 20 then this property will contain -10. If the piece is not sitting on any Mat, this property will contain the empty string "".
CurrentMatPieceName contains the PieceName of the Mat, if any
CurrentMatBasicName contains the BasicName of the Mat, if any
CurrentMatLocationName contains the LocationName of the Mat, if any
CurrentMatZone contains the CurrentZone of the Mat, if any
CurrentMatBoard contains the CurrentBoard of the Mat, if any
CurrentMatMap contains the CurrentMap of the Mat, if any
CurrentMatProp0 - CurrentMatProp9 will contain the value of the identically named property of the Mat. For example if the Mat contains a CalculatedProperty trait called "CurrentMatProp0" and that trait presently evaluates to 7, then CurrentMatProp0 on any Mat Cargo sitting on that mat will also return 7. The Mat can use a Marker, Dynamic Property, or Calculated Property to expose these values to its cargo.
IsCargo will always contain the string "true" for a Mat Cargo piece (it will contain an empty string, "" for a piece which does not have this trait).
OldMat contains the previous Mat name, if any (former contents of CurrentMat).
OldMatID contains the previous Mat unique ID, if any (former contents of CurrentMatID)
OldMatPieceName contains the previous Mat’s piece name, if any
OldMatBasicName contains the previous Mat’s basic name, if any
OldMatOffsetX contains the cargo’s previous CurrentMatOffsetX value (offset from X position to X of Mat), if any
OldMatOffsetY contains the cargo’s previous CurrentMatOffsetY value (offset from Y position to Y of Mat), if any