VASSAL Reference Manual

Home > Module> Game Piece Palette > Game Piece > Send to Location

Send to Location

Adds a command that moves a piece directly to another location.

EXAMPLE:
A game may require that damaged units are returned to a Damaged pool for repairs. Different boxes in the pool represent the amount of time before the unit is fully repaired. A game piece may be given a Send to Location trait with menu text "Send to Damaged Pool" and key command Ctrl+P, with the target position corresponding to the first box of the pool, with an additional offset, determined by the level of a Layer representing the damage, to place it in the appropriate box in the pool.

Note
 The Menu Command of a Send to Location trait will be greyed out and unavailable if the destination is illegal, or cannot be determined for any reason.
Description:

A brief description of the command which will appear in the Trait list of the piece. Helpful when distinguishing between different Send to Location traits.

Menu command:

Text for a right-click context menu that will cause the piece to be moved. If left blank, no context menu item will appear, but the trait can still be activated with the key command.

Key command:

The Keystroke or Named Command which will activate this trait, causing the piece to be moved.

Send back menu command:

The menu text for an "undo" command to return the piece to its original location.

Send back Key Command:

The Keystroke or Named Command for the "undo" command

Destination:

The destination drop-down provides different methods to determine where the piece will be sent to.

Depending on the Destination type, additional options will be available to specify the destination exactly.

All destinations can be further offset by the additional offset options provided below.

Location on Selected Map

An (x,y) position on a specific map.

Zone on Selected Map

The center of a Zone on a map.

Region on Selected Map

The named Region on a map. In the case of Multi-Zone Grids, this format makes use of the Location Format field in any Zone:

  • for Zones whose Location Format is configured to $name$, the name of the Zone will be the name of the Region.

  • for Zones whose Location Format is configured to $gridLocation$, then the grid location inside the zone will be used.

Any counter, selected by properties

The location of the first piece selected by the Property Match Expression specified. Compared to the two subsequent property match options (Cycle and Nearest), this option usually executes the most quickly and efficiently. If you expect there to be only one piece matching the expression, or if you don’t care which matching piece is picked as long as it matches the expression, then this is the option you want.

Cycle through counters, selected by properties

The location of the next piece selected by the Property Match Expression specified. If there are multiple matching counters then sending this command multiple times will cycle through the counters.

Nearest counter, selected by properties

The location of the nearest piece selected by the Property Match Expression specified.

Grid Location on Selected Map

A named location on a map using the appropriate grid numbering (or the named location on an Irregular Grid.

Note
 When using Grids with fully numeric Column and Row numbers with leading zeros (e.g. 0203), then Vassal will internally remove leading zeros of any Grid Reference you enter, making it impossible to Send to numeric locations that commence with a leading '0'. This can be overcome by setting the Preserve leading zeros in Integers Global Option.
Map:

An Expression specifying the Map Window name that the piece will be sent to. If unspecified, then the piece’s current map is used. You can use the Select button to select a Map Window currently defined in the module.

Board:

An Expression specifying name of the board that the piece will be sent to. Positions below are relative to the board’s position within the Map. If no board is specified, positions are relative to the Map Window. You can use the Select button to select a Board currently defined in the module.

Zone:

An Expression specifying the Zone name that the piece will be sent to.

Region:

An Expression specifying the Region name that the piece will be sent to. In the case of Multi-Zone Grids, this format makes use of the Location Format field in any Zone:

  • for Zones whose Location Format is configured to $name$, the name of the Zone will be the name of the Region.

  • for Zones whose Location Format is configured to $gridLocation$, then the grid location inside the zone will be used.

Grid location:

The Grid Location that the piece will be sent to. In the case of an Irregular Grid, this is name of an individual Region defined in the grid.

Property match:

A Property Match Expression that selects a counter that the piece will be sent to.

X position:

An Expression specifying the horizontal position of the destination point in pixels.

Y position:

An Expression specifying the vertical position of the destination point in pixels.

Additional Offsets:

After the destination of the piece has been determined based on the Destination type, the final position is further adjusted by the multiplied values of the two pairs of offsets Expressions.

Each pair of expressions (X and Y) will be evaluated, multiplied together, and then applied as offsets to the X,Y position calculated from the destination above to give the final destination for the piece.

SendToLocation Sample Send to Location trait

SendToLocationL Map destination options

SendToLocationZ Zone destination options

SendToLocationR Region destination options

SendToLocationA Counter destination options

SendToLocationG Grid Location destination options

SendToLocationAdv Offset example