VASSAL Reference Manual

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.

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.

MatCargo

Mat2 Above: 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