VASSAL Reference Manual

Home > Module > Game Piece Palette > Game Piece > Report Action

Report Action

A Game Piece with this trait will report a configurable message to the Chat Log in the main window when any of a given set of Keystrokes or Named Commands are either typed or activated by other traits.

Note that the Chat Log now supports bold text, italicized text, and even colored text and ChatLogDice. See the Chat Log article for full details.

IMPORTANT: When HTML is enabled in the chat log, it is important to remember that the < character will be interpreted as the beginning of an HTML tag, rather than simply displaying a "less than" or "left angle bracket" symbol. Thus, modules which use the < symbol to indicate "less than" or to "draw an arrow" or enclose a username, etc., will need to have those instances changed to &lt; (the HTML escape code which causes a literal < character to be printed). Otherwise, you may experience odd behaviors such as chat log messages failing to appear (or seeming to be delayed until the next chat message is printed).

Troubleshooting: (If a Report Action trait doesn’t seem to be showing a message)

  1. Check to make sure that the Map where the piece is located has its Auto-report format for units modified on this map field set to include the string $message$ since otherwise Report Action traits will not generate messages for pieces on that map.

  2. If the Report Action trait is activated by a Global Key Command, then it will only generate a message if the Global Key Command’s Suppress individual reports field is not checked.

EXAMPLE: A unit named "Infantry" has a single Layer trait that is activated with a Ctrl+F "Flip" command. By adding a Report Action trait with report key Ctrl+F and message $newPieceName$ flips in $location$ the chat text will echo "Infantry flips in A9" whenever a player flips the unit.

EXAMPLE: If the unit above has the Invisible trait activated by Ctrl+I , then an additional Report Action trait with report key Ctrl+I and two cycling messages $oldPieceName$ goes invisible in $location$ and $newPieceName$ revealed in $location$ will report when the unit becomes invisible/revealed.

EXAMPLE: If the counter above has the Can Rotate trait with 4 facings controlled by Ctrl+] and Ctrl+[, then an addition Report Action trait with report key Ctrl+] and report-previous key Ctrl+[ and cycling messages $newPieceName$ rotates to face North, etc., will automatically report the appropriate facing.


A short description of this trait for your reference.

Report on these Key Commands:

Specifies the Keystroke or Named Commands that this trait will respond to. Use the List controls to add more than one key command.

Cycle through different messages:

If left unchecked, the same message will be reported whenever any of the above key commands are received. If checked, the message to be reported will cycle through the list specified below. Each time one of the key commands is received, the next message in the list will be reported, returning to the beginning after the end is reached.

Report format:

The Message Format for the message that will appear in the Chat Log. Note that a simple string message with properties substituted by $..$ can be used, or a fully functional Beanshell Expression can be created. See Message Format for more details.

Additional Properties: $menuCommand$ inserts the name of the piece’s right-click context menu command that corresponds to the key command received, $oldPieceName$ is the name of the piece before the action is applied, $newPieceName$ is the name of the piece after the action is applied, $mapName$is the name of the map where the piece is located, $oldMapName$ is the name of the map before the action, $location$ is the map location where the piece is located, $oldLocation$ is the location before the action is applied.

Override suppression by Global Key Commands:

If this box is checked, the message will be displayed when triggered even if it is triggered by a Global Key Command with the "Suppress Individual Reports" option checked. This can be used to ensure that certain key messages are displayed no matter what.

if a piece is deleted or replaced as the result of an action, then the value of oldLocation and oldMapName will depend on the order of the traits, while mapName and location will be blank.
Message Formats:

A list of Message Formats for cycling messages. Available properties are the same as above. Any Properties defined on the piece will be substituted. To access the value of a Property before the change, add old to the name. For example, if a piece has a property hitPoints, then $hitPoints$ gives the value after the key command and $oldhitPoints$ gives the value before.

Report previous message on these keystrokes:

When any of these key commands are received, the message reported will be the one the precedes the last reported message, instead of the following one.

ReportChanges Simple Report, Single Message

ReportChanges2 Adding Multiple Cycling Messages

ReportChanges3 *Bold*, Italicized, and Colored text are supported.

ReportChanges4 Using a Beanshell expression to generate a report

SEE ALSO: Chat Log