VASSAL 3.7 Release Notes

This article will give you a quick tour of the new features in VASSAL 3.7, as well as listing some significant player-facing bug fixes.

Major New Features

Import/Export Items in Editor

Editor items (as well as entire hierarchies of them) can be exported to an XML files. This is particularly useful when you wish to then import them into other modules. For instance you could export all the prototypes from one module and import them into another (or just a specific folder of prototypes). It's not quite cut-and-paste across modules, but it's the next best thing!

When exporting a folder or component from a module, the selected item and all of its "children" will be exported.

When importing into a module, the items imported will be added as "children" of the currently selected item.

New Trait: Attachment

The new Attachment trait creates a lasting relationship between one or more pieces. Once a piece has an attachment to another, it has faster access to that piece: it can directly read and write that piece's dynamic properties, and it can send a Global Key Command to attached pieces much more quickly than normally possible.

Advanced Attachment Trait

The basic version of the Attachment trait automatically creates an attachment to any other piece(s) with the same attachment name. The advanced version (accessed by turning off "automatic" attachment) allows attachments to be explicitly added and dropped via key commands, and allows the use of expressions to filter which pieces become attached.

When a global key command is sent to "Current Attachments", only attached pieces will receive the command, and they will receive the command very quickly (compared to a normal Global Key Command where VASSAL must search through a long list of potential pieces)

The GetAttachmentProperty function can be used to read the value of an attachment's property. Pass the name of the attachment trait, the name of the property, and either the BasicName or the index of the attachment.

Additional functions have also been added to Sum, Count, and get the Max/Min of attachment property values.

New Trait: Set Attachment Property

The "Set Attachment Property" trait supplements the new Attachment trait by allowing the dynamic properties of an attached piece to be changed. This trait works much like the normal "setters" on a Dynamic Property or Set Global Property, and simply has additional fields to specify the attachment being accessed.

New Trait: Set Piece Property

The "Set Piece Property" trait allows a piece to change the Dynamic Properties of other pieces. This works similarly to the "Set Global Property" trait, but uses filters similar to those for a Global Key Command to determine which piece(s) have their properties set.

New Trait: Multi-Location Command

The "Multi-Location Command" allows a single trait to produce multiple "right click menu" options for different potential map locations, based on a filter you create which is checked when the piece gets right-clicked. The piece can then respond differently based on which of the different items was clicked. 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. See below for an illustrative example.

Here we configure the trait -- we are going to produce a command for each region in Illinois, but using our filter to exclude Chicago using the LocationOfCommand special property.

Here is the menu that appears when the player right-clicks the piece. All of those menu items were generated by this same trait. Notice that Chicago was filtered out.

Here is how we configure a Report Action trait to respond to one of the menu items being clicked: it receives the same key command each time, but is able to use special properties such as LocationOfCommand and ZoneOfCommand to identify the specific location selected. Other traits could respond as well -- we're just using Report Action for illustrative purposes.

Here we see the final result displayed when the player selects one of the menu items (based on the Report Action trait we configured)

New Trait: Border Outline

Piece with Border Outline

The new Border Outline trait will put a solid outline around the shape of a piece. Width and color of the outline is configurable. Can optionally be shown only when a designated property is true or non-zero.

New Properties: StackPos, StackSize, OldDeckName

New properties are available to be referenced in pieces: StackPos exposes piece's current position in its stack, and StackSize exposes the total number of pieces in its stack. OldDeckName contains the name of any deck the piece was just moved from.

SumMat and CountMat

Beanshell expressions can now use SumMat to sum the value of a property across a Mat and all of its Cargo. CountMat can be used to count (again among a Mat and all of its Cargo), the number of pieces that have a non-blank value for a particular property. Both SumMat and CountMat can be accessed either from the Mat or from a Cargo piece.

Startup Global Key Commands can send Global Hotkeys

Startup Global Key Commands can be used to send a Global Hotkey rather than a Global Key Command, so they can directly activate toolbar buttons, deck commands, and other similar things that aren't pieces.

Area of Effect Improvements

The Area of Effect trait has received some attention, with the addition of an active property field, local/global visibility options, and separate on/off key commands.

Symbolic Dice Button Improvements

Symbolic Dice Buttons now feature full "action button" support: they can fire a key command or play a sound, as well as generating a report.

Eliminating Spurious Auto-Reports

Auto-reporting on a Map can be configured to ignore same-location movements (i.e., if a piece's LocationName and Mat stayed the same, to not generate a movement report).The default behavior remains the same.

Mark When Moved improvements

Similarly the Mark-When-Moved trait can be configured to only flag when a piece changes LocationName or Mat. The default behavior remains the same. ALSO, the Mark When Moved trait now includes key commands to directly set the Moved state to true or false, as opposed to only toggling.

Hiding Blank Prompts

When a property is configured to be set using the "Prompt" option, one longstanding issue has been when one of the items in the list of possible prompts is blank. In 3.7, a new Global Option has been added to allow the display of blank prompts to be suppressed.

Suppress Sounds Caused by Global Key Commands

Global Key Commands now offer the option to suppress sounds being generated by the key commands they send.

Non-Rectangular SVG Support

Non-Rectangular traits based on SVG files will use the path (rather than merely a bitmask), allowing more accurate and efficient outlines to be drawn in many cases. In particular, Non-Rectangular traits with a relatively clean/simple "path" around them will scale much more cleanly than a regular bitmap image.

Mouse-over Stack Viewers for Terrain

Mouse-over Stack Viewers can now be configured to show the underlying terrain from the map, in addition to any pieces there. This feature is similar to one long present in VASL through custom code, and is now available to all modules.

Mouse-over Stack Viewers: Configurable Outlines

Mouse-over Stack Viewers now feature additional configuration options relating to the thickness and color of outlines.

Inventory Window Count

The count_ prefix is now allowed for counting (as opposed to summing) properties. It can be used in place of the sum_ prefix and will count the number of pieces with a non-blank value for the property in question, instead of summing the value of the property.

DEL or Backspace Key Mapping

The DEL or Backspace key can now be mapped in key commands. Obviously we recommend it be used with care, but it can be an appropriate key for e.g. deleting markers.

Action Buttons now allowed on Maps, Hands, Private Windows

Action Buttons are now available on all windows where other similar buttons (e.g., GKC, Multi-Action, etc) are available.

3.7.0 Full Change Log (changes since 3.6.19)

New features

• 12566: Add Beanshell function to add Sleep/Delay processing
• 12536: GKC and Place/Replace parameters
• 12492: Add Comment trait
• 12454: BeanShell Editor improvements: larger, multi-line, more properties
• 12445: Add Ranged Sum/Count Functions; updated Function Builder and documentation; updated Property documentation
• 12444: Implement real Unique Piece Id property UniqueID that does not change during refresh
• 12323: Add Beanshell Range functions
• 12284: Add Danish localization
• 12251: New Set Piece Property trait
• 12243: Startup Global Key Commands can also send a Global Hotkey
• 12222: Multi-Location Commands: One trait may create actions corresponding to several map locations
• 12192: New Attachment trait
• 12184: Pivot can have two key commands/angles
• 12153: Layer traits allow a show-only-if-this-property-true filter
• 12149: BorderOutline trait now accepts two fields
• 12129: PlaceMarker and ReplaceWithOther can use expression for X/Y offset
• 12100: Text Labels support <img> tags
• 12067: Import/export of groups of items from Editor as XML files (e.g., to transfer between modules)
• 12060: Editor allows Deck files to be imported into a deck to become permanent part of module
• 12035: Mouse-over Stack Viewers allow configuring thickness of outer border, and more padding/stretching options
• 12032: Mark-When-Moved trait can be configured to only flag when piece changes LocationName or Mat. Similarly Map auto-report can be configured to ignore same-location movements.
• 12003: OldDeckName now supported as a piece property
• 12001: count_ supported for counting properties in Inventory windows
• 11969: New Border Outline trait
• 11964: Mouse-over Stack Viewers can display an image of underlying terrain
• 11937: SumMat and CountMat functions for Beanshell expression
• 11932: Support for setting Scenario Options
• 11918: Startup GKC that fires when player joins or changes sides
• 11917: Create Non-Rectangular mask directly from SVG outline
• 11530: Add new StackPos and StackSize properties to Basic Piece
• 11523: Area of Effect improvements: Active property, local/global visibility, separate on/off Key Commands
• 11178: Global Option added to omit empty lines in property setting prompts
• 11100: Allow begin-logfile and end-logfile to have configurable hotkeys in Global Options
• 10822: Sounds can be suppressed during GKC processing
• 10821: Symbolic Dice buttons how have full Action Button capabilities (sounds, hotkeys, etc.)
• 10820: Make Action Button available on all windows where other similar buttons (e.g., GKC, Multi-Action, etc) are available
• 4454: Save chat text to file
• 4446: Dynamic button labels (can use expressions and $...$ in certain toolbar buttons)

Bug fixes

• 12644: Prevent NPE when Editing Deck count expressions
• 12627: Fix chat non-scrolling caused by setting preferred size for the Chatter contents pane
• 12620: Ensure that HTML attribute values are quoted
• 12595: Fix Search UnsupportedOperationException
• 12578: Process Set Piece Property expressions correctly
• 12568: Center of map view during zoom used incorrect coordinate space
• 12561: Handle Beanshell functions correctly in expressions
• 12547: CountLocation function with 3 parameters does not work
• 12529: Allow Piece UIDs to be compared properly in expressions
• 12528: Close InputStreams opened for reading SVG
• 12482: Map Shader now able to add button to Map Toolbar
• 12470: Place Marker X Offset should default to 0, not null
• 12439: Uniformly handle addition of standard and imported Configurables
• 12434: FastMatch by Location now respects Deck limits
• 12433: Attachment Fastmatch: match each piece at most once, limit checking by name
• 12420: Set Piece Property does not work
• 12403: Extension Editing fixes: Cut & Paste now deletes cut element, Drag & Drop between folders in Extension are saved, stopped UnsupportedOperationException during search
• 12401: Allow Ctrl-V to be entered as a Key Command
• 12396: Add missing Global Option message
• 12393: Fix Auto-attach breaking on Undo
• 12392: Replace With Other incorrectly retains existing Marker values when Match Current State is checked
• 12382: Prevent NPE in Beanshell execution during module initialisation
• 12363: Initialise Global Option preferences that have no Tab name
• 12347: Refresh Dynamic Properties correctly when they have no value
• 12342: Fixed bad link in Reference Manual
• 12340: Fix inaccurate Hex Grid location reports
• 12322: Scale summed board locations instead of summing scaled board locations to reduce rounding error
• 12315: Prevent NPE in MouseOverStackViewer trying to show top piece of empty stack
• 12303: Dynamic button text was resolved too soon
• 12302: Description field now properly appears with Startup GKC set to send Global Hotkey
• 12261: Report error if more than one grid added to a Zone
• 12220: Add BorderOutline's property names to the searchable target list
• 12215: New MarkMoved commands shouldn't default to being displayed if no key commands entered
• 12205: Area of Effect trait was eating other traits' visibility info in some cases
• 12203: Properly extract outlines from SVG for NonRectangular
• 12175: Fix stretchy images in chat
• 12159: Correctly handle install paths containing spaces in VASSAL.sh
• 12158: List Key Commands tool can be re-opened after closing with X button
• 12152: Work around Java bug which prevents displaying Windows file dialog
• 11913: Numeric global properties with increments other than 1 and -1 now wrap around correctly

Other improvements

• 12626: Hide caret in chat pane
• 12573: Updated bundled Java to 20.0.2
• 12556: Map Shaders on different maps can now have same name
• 12549: Simplify Trait edit window title
• 12538: Scenario Options - Allow Observers to Lock option tabs if no Sides taken
• 12509: Allow and empty Deck or At-start Stack to be repositioned
• 12504: Updated documentation for 3.7
• 12501: Merge Set Attachment property into Set Piece Property
• 12495: Mouse-over Stack Viewer 'Show move limited pieces' option no longer dependent on 'Show non-stacking' option
• 12443: Clarified MouseOverViewer documentation
• 12432: Add missing Sum & Count expressions
• 12427: Fixed bad links in Reference Manual
• 12362: Rollover component help button goes to MouseOver.html instead of Map.html
• 12341: Expression documentation improvements
• 12287: Enable text field DnD
• 12279: Default heap raised to 1024MB
• 12270: Scenario Options tweaks
• 12267: Optimize Ranged GKC's and remaining Location based fastmatch option
• 12235: HTML Help file starting page can now be an expression
• 12187: Improved Rectangular Grid range metric names and made them translatable
• 12177: Change-property buttons don't generate completely empty chat lines
• 12176: Add preference to not display Mark Moved status of pieces
• 12172: Metadata now contains the 'extra' fields, and Module Manager displays them if numeric
• 12138: Better editor descriptions of Global Hotkey traits
• 12137: Editor shows better descriptions for Dynamic Property and Set Global Property traits
• 12136: Change Property Buttons now have a description field, which is displayed in the editor if filled in
• 12133: Rollovers automatically shrink scale if the pieces are too wide to fit the screen width
• 12084: Help menu shows module-specific help items before generic Vassal ones
• 12080: Zooming in and out no longer loses track of player's preferred center point for map
• 11919: Allow DEL/BACKSPACE to be mapped as a hotkey
• 11506: Predefined Setup "menus" with blank names will not be shown
• 11104: Refresh Can Rotate trait by Rotator Name match option for Game Refreshers

Changes in 3.7.1

Bug fixes

• 12727: Ensure that tiles are cobbled for fixed-size board scaling
• 12708: Prevent ArrayIndexOutOfBoundsException if side translation count does not match module
• 12688: Replace with Other should not update text of unchangeable labels
• 12683: Prevent NPE on starting game in Main Room
• 12679: Set Piece Property respects target property numeric constraints unless overridden
• 12676: IncrementProperty: Corrected bad wrap-around calculation when increment is negative
• 12659: Translate current side before checking for "next side"
• 12645: Respect localization when filtering sides
• 12582: Corrected divide-by-zero problem for Zones defined by zero-point polygons
• 12542: Mitigate race condition when selecting player sides
• 12474: Fixed NPE when moving EditablePiece which isn't on a map
• 12411: Fixed NPE when updating ConfigureTree
• 12324: Fixed ClassCastException caused by reordering columns in Delayed Notes table
• 12307: Prevent NPE when Return to Deck of a deleted Deck

Other improvements

• 12716: Support regular expressions in Editor search
• 12715: Enable help button for editor Search dialog
• 12706: Keep the "retire" button disabled unless a game is running
• 12696: Removed "Indexing pieces" message
• 12670: Prevent essential components being accidentally deleted
• 12661: Translate side names in change sides message

Changes in 3.7.2

Bug fixes

• 12784: Fix rendering of external Text Label images
• 12781: Fix bad translation keys for Attachment, Deselect, Send To Location traits
• 12780: Correctly adjust Player window title to reflect actions taken in Welcome Wizard
• 12769: Fix support for expressions in Sound Clip Configurer
• 12729: Set Global Property to again record old GP value in oldValues for reporting
• 12773: Disabled Toolbar Button icons should not appear in unused images list
• 12770: Prevent NPE when escaping from GKC trait after adding 'Set Dynamic Properties' entries

Other improvements

• 12896: Build universal Mac bundle

Changes in 3.7.3

Bug fixes

• 12817: Fix alphanumeric key behavior in hotkey (key command) configurer in Editor (e.g., Shift+B should show up as "Shift+B", not "B")
• 12810: VASSAL.sh exits before printing relevant exit message
• 12705: Prevent creation of duplicate Translations by Add Translation button

Other improvements

• 12814: Updated bundled Java to 21
• 12808: Horizontal scrolling now supports 2-finger-trackpad and mice with additional horizontal wheels
• 12724: Improved legibility of translation panels

Changes in 3.7.4

Bug fixes

• 12830: Prevent Load Continuation from auto-forwarding to end of log
• 12826: Fix bug where pieces sometimes teleport from deck back to different map in multiplayer (Ensure map recorded in pieces matches map in parent Stack/Deck)
• 12824: Ensure ColorManager and FontManager are created exactly once, before use
• 12802: Prevent NPE in Named KeyStroke Configurer

Other improvements

• 12829: Set Piece Property Documentation clarification
• 12825: Allow Unique components to be copied; change Game Piece Layers to be non-mandatory

Changes in 3.7.5

Bug fixes

• 12866: Fix double application of board magnification to board bounds
• 12852: Prevent SumZone from generating Bad Data Errors
• 12846: Fix missing custom colors and font styles in Game Piece Layouts
• 12841: Ensure labels are correctly updated in Replace With Other trait

Other improvements

• 12865: Documentation: Editor Search section - add a cross-link to main search details
• 12861: Number in-use traits in Piece Definer