VASSAL Reference Manual

Home > Module > Game Piece Palette > Game Piece > Multi-Location Command


Multi-Location Command

Sometimes it is useful for a piece to have context menu items representing actions at multiple map locations (e.g., "Send me to London", "Send me to Paris"), but creating an individual trait for, e.g., every location on the map can be prohibitive.

Multi-Location Commands solve this problem by allowing a single trait to generate multiple menu items, filtering locations through a property expression. Each location that matches the property expression will be given its own menu item, with the text of the menu item being generated on the fly using the specified report format.

Whenever the player selects any of the menu items associated with a Multi-Location Command trait, the trait’s single key command will be generated, and can be intercepted by other traits (e.g., Trigger Action, Send to Location). To identify which map location was associated with the menu item picked by the player, these other traits can use the properties LocationOfCommand, ZoneOfCommand, BoardOfCommand, and MapOfCommand.

NOTE: It is recommended that Named Key Commands (rather than actual keystrokes) be used for Multi-Location Commands. If an actual keystroke is used and the user manually types the key command, the trait properties (e.g., LocationOfCommand) will be set to the first location found.

Description:

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

Type of Location:

The type of location that will be scanned (Regions or Zones)

Search current map only:

If selected, then only locations on the same map as the piece will be searched; otherwise all maps will be searched.

Matching Properties:

An expression to determine which of the scanned locations will be included as commands. If left blank, all of them will.

Menu item format:

The format for constructing menu items from the locations. The trait’s properties (e.g., LocationOfCommand, etc) can be used with $..$ to make string substitutions.

Sort menu items by this keystring:

This field lets you provide a keystring to control the order that the generated commands will appear in the context menu. For example $LocationOfCommand$ would sort based on the location name, or $YOfCommand would order the list based on the Y position (i.e. from north to south).

Ascending sort:

Controls whether an ascending or descending sort is used.

Numeric sort:

If this box is checked, the sort key is considered to be a numeric field (so that e.g. "90" is treated as lower than "100" which wouldn’t be true in an alphabetic sort). If unchecked an alphabetic sort is performed.

Key command generated by menu item:

Whenever any menu item generated by this trait is picked by the player, this key command will be generated.

MultiLocationCommand

MultiLocationCommand2

MultiLocationCommand3

MultiLocationCommand4


Properties

A Multi-Location trait exposes the following Properties. They can be used both for filtering which locations are included as commands, for substitution into menu text for commands, and for identifying which location’s command was picked after the key command has been picked up by another trait.

  • LocationOfCommand The location (region or zone) of the command

  • ZoneOfCommand The zone (if any) of the command

  • BoardOfCommand The board of the command

  • MapOfCommand The map of the command

  • XOfCommand The X position on the map of the command

  • YOfCommand The Y position on the map of the command