VASSAL Reference Manual

Home > * Message Format*

Message Format

ReportFormat MessageFormatHTML MessageFormatExpression

A Message Format allows you to format the text messages that are generated by VASSAL during play. It is essentially a text message, except that the values of Properties can be substituted into the message. Any word surrounded by $ characters (e.g. $CurrentMap$) substitutes the value of the named Property in place of the $..$ name. The value is taken during play at the time the message is generated.

Click on the Insert drop-down menu for a list of available Properties. Selecting one of the Properties from the menu will insert it at the current cursor position.


By using the calculator button at the far right of the field, you can also turn a Message Format into a Beanshell Expression. If you choose to use this manner of defining a Message Format, the entire format will need to be generated from a single Beanshell expression surrounded by the { } markers and using quotation marks " " to surround literal string values, etc. In these new-style expressions property names are not surrounded by $..$ the markers used in old-style expressions.

Quick Colors

VASSAL provides several "quick color" shortcuts to allow colored text to be put into the chat log by Report Action traits and other Message Formats. This is done by placing a special character as the first character of a message. The special first character, if any, will be removed automatically from the message when it is displayed. Each of these characters activates one of the five chat log colors from the Chat Preferences tab; default colors are provided but players are allowed to reconfigure the colors as they wish.

EXAMPLE: If a Report Action trait’s message said Hello World. and you wanted to change the text to green, you could simply change the message text to !Hello World. The exclamation point would be automatically removed, and the message would appear as Hello World.

First Character



none or "|"

vertical separator

defaults to black text


exclamation point

defaults to green text


question mark

defaults to pink text



defaults to red text


back apostrophe

defaults to purple text

ChatLog Reports displayed in Chat Log

HTML in Chat Log

VASSAL’s chat log now supports HTML as well as regular text, as long you turn on the proper Global Options setting (this is to maintain compatibility with modules created with earlier versions of VASSAL that did not account for such support). To turn on HTML support for your module, in the Editor window navigate to the [Global Options] component and open its properties dialog. Find the Enable HTML support in Chat Log option (see illustration at right) and set it to Always. Any message with a "Quick Colors" first character, including "|" will also parse HTML regardless of the Global Options setting.

With HTML support enabled, you can include many types of HTML tags in your Report Action traits and other Message Formats. This opens up even more possibilities than the Quick Colors shortcuts and allows you to create an unlimited number of new styles.

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).



<b>bold text</b>

bold text

<i>italic text</i>

italic text

<u>underscore text</u>

underscore text

<span style="color:blue;">blue text</span>

blue text

<span style="color:#ff6666;">hex color text</span>

hex color text

<img src="d6-6-grey.png" width=14 height=14> dice image

imagedice image

Properties available in Message Format

Available Properties will vary depending on the component being configured. Some commonly-used Properties are:

$playerName$ is the player’s name as specified in the Preferences. Note that this is the name of the player running the current session "on this computer", not e.g. the name of the player who owns a particular piece.

$playerSide$ is the side chosen by the player from the Definition of Available Sides

$playerId$ is a combination of playerName and playerSide specified in the Global Options

$Global Property$ names can also be referenced.

$result1$, etc., from the roll of a Symbolic Dice Button can also be checked.

$Properties$ of a Game Piece can be referenced when a Message Format is used in conjunction with a particular Game Piece. See the Properties article for a handy list of properties associated with pieces.


Enabling Chat Log HTML Support in Global Options