VASSAL Reference Manual

Home >  Expressions


Expressions


Any field within the Vassal Editor that is followed by a Calculator icon allows the entry of an Expression. Expressions are essentially an in-line Calculated Property that are re-evaluated whenever its value is required.

Property Match Expressions are a special kind of expression that are used in Global Key Commands to select what counters to operate on, and in Trigger Action traits to check if the action is Triggered. These are described on a separate page.

There are two varieties of Expressions. BeanShell Expressions are identified by being surrounded by curly braces {}. They are very powerful and can be arbitrarily complex. Simple Expressions are identified by not being surrounded by the curly braces {}. Simple Expressions are far less powerful than BeanShell expressions and are supported to provide compatibility with earlier versions of Vassal.

Expressions should not be confused with Message Formats that are used by various traits and component to generate messages. Message Formats are far more limited than Expressions. They only allow the inclusion of Property values, they do not allow any sort of calculations.

BeanShell Expressions

BeanShell Expressions (named after the software package the implements them in Vassal) allow you to use arbitrarily complex formulae to define the value returned. BeanShell Expressions are marked by being surrounded by braces {}.

The BeanShell processor is an accurate implementation of the Java programming language and BeanShell Expressions are made up of Java language components. You can use any introductory Java tutorial to learn more about the syntax of BeanShell Expressions. The basic components are as follows:

Type Options Examples Notes
Numbers   {35} Vassal works with whole numbers. Decimal numbers are treated as Strings
Strings   {"German"} A String must be enclosed in """ marks
Properties   {Nation} Any string not enclosed in "" is interpreted as a Property name
Arithmetic + Add
- Subtract
* Multiply
/ Divide
% Modulo
{CurrentHP + 2 * Damage - Resistance}
{FirstName + "-" + Surname}
{Height * 10}
{width / 5}
{Level % 10}
Using the + operator on two String will concatenate (join) them. If the values on either side of the + look like whole numbers, Vassal will attempt to add them.
Comparison > Greater than
< Less than
>= Not less than
<= Not greater than
== Equals
!= Not Equals
=~ Match regular Expression
{height > 10 && width >= Level}
{length < maxlength || breadth <= maxbreadth}
{Nation=="Germany"}
{Army!="Allied"}
{Type="^A$"}
Comparison operators are used primarily in Property Match Expressions and also in the If function.
Logical && Logical AND
|| Logical OR
! Logical NOT
() Grouping
{Nation=="Germany" && Type="Unit"}
{Nation=="Germany" || Type="Unit"}
{Nation=="Germany" && Type="Unit"}
{! isInUse}
{A==B && (C==1 || D==2)}
Comparison operators are used primarily in Property Match Expressions and also in the If function.
Functions Alert(message)
If(comparison,value1,value2)
GetProperty(propertyName)
SumStack(propertyName)
{Alert("Adding 1 to HP")}
{If(Nation=="Germany",1,3)}
{GetProperty("Nation"+myNation)
{SumStack("Attack")}
Alert displays a message in a popup dialog box.
If returns value1 if the comparison is true, or value2 if it is not.
GetProperty returns the value of the Property, which may be an expression.
SumStack returns the total of the specified Property in all counters in the same stack as this one.

Simple Expressions

Simple expressions are not surrounded by braces and provide compatibility with earlier versions of Vassal that only implemented a much simpler version of Expressions. Simple Expressions are far more limited than BeanShell Expressions, only allowing the substitution of property values into a pre-determined string.
A Simple Integer Expression: A whole number. In general, Vassal does not support decimal numbers, except when stored and used as Strings.
A basic Simple String Expression: A String in a Simple Expression is defined without quotation marks.
A more complex example: The string $Nation$ will be replaced by the value of the Nation property. You can use multiple $...$ strings in an expression ($Nation$-$Division$), but can NOT nest them ($Nation$Count$$).

SEE ALSO: Properties