VASSAL 3.5 Release Notes

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

= New Features =

Flare Command
A "Flare" command has been added, allowing you to draw an opponent's attention to a particular location on the map. By default this is by Alt + Left Click but it can be reconfigured by the module designer. A pulsing circle will appear at the target location on the maps of all other players.

This feature works both in online play and PBEM games being replayed from the log.



Performance Improvements for Global Key Commands


Global Key Commands now include "Fast Match" options which can be used to improve the performance of "slow" Global Key Commands by pre-matching the location and/or a single property value of the target piece. Essentially these run limited but much faster comparisons, to screen out some of the potentially hundreds of pieces needing to be checked for each Global Key Command. Fast Match expressions are optional in that the same comparisons can always be run in the standard "Additional matching expression" field. Judicious use of them, however, can improve the performance of a Global Key Command by 25-33%.

There is some necessary complexity involved with Fast Match, in order to achieve performance optimization. Any expressions supplied in Fast Match fields are immediately evaluated against the source (issuing) piece, but the results of those expressions are then matched to the target piece. For example if a Fast Match "by Property" is selected with the property name field filled with {"Status"} and the property value field is filled with {Rank + 1}, then the Rank property of the source piece will be read immediately, and a number one higher than it will be the value which is then compared to the value of the "Status" property in all potential target pieces. If instead of {"Status"} the property name field were filled with {"Status" + Type}, then the value of Type from the source piece would be used, and if it contained for example "Infantry" then the value of the property StatusInfantry would be checked on the target piece.





MouseoverStackViewer HTML Support and Additional Options
Many new features have been added to the configuration for Mouseover Stack Viewers:
 * A description field so that multiple Mouseover components are more easy to distinguish
 * HTML support and Quick Colors can now be turned on for text portions
 * More control provided over relative positioning, padding and centering of elements.
 * The Viewer can be set up to show more than one card from a deck (e.g. to show the entire discard pile)
 * The Viewer can be set up to show all pieces overlapping the mouse location (rather than only pieces precisely matching the location of the first piece found)



Chess Clocks
VASSAL now includes "Chess Clocks" which can be added to a module and used to facilitate timed online play. To add chess clocks to a module, right click on the main (top) module component in the editor and select "Add Chess Clock Control". Depending on the type of game, different modes of clock display can be selected.

Chess Clocks are not designed to facilitate timed PBEM games, as time usage in these situations cannot be verified in-game.



Editor can Search in Traits and Components
The Editor's "Search" function can now search into Traits and Components. Results from traits and components will appear in the chat log.



Ability to Deselect a Piece with a Key Command
Pieces can now be given a "Deselect" Trait. Activating the key command for this trait will cause the piece to be removed from the current selection (if it was present). Optionally the piece can also be removed from its current stack if desired. This can be useful in games where stacks frequently "drop pieces off".



Simpler Way to Display PDF Files from Help menu
Although it was possible to add a PDF file to earlier versions of VASSAL, it involved a considerable number of steps and "hoops to jump through". The process has now been vastly simplified.



Removing Unused Images From Modules
The Editor's Tools menu now has a "Remove Unused Images" feature, which will search for image files that are not referenced anywhere in the module and give you an option to remove them. Note that it is safe to launch this feature to take a look for unused files, because no images will actually be removed from the module file unless you then explicitly move them to the "Files to remove" column and then click the "Remove Files" button.

Note: The remove images tool will not be able to detect if an image is used by a "Custom Class" that does not register its image names with VASSAL. Custom classes can register their images by calling this method (available from either AbstractBuildable or Decorator):

public void addLocalImageNames(final Collection s)



Console Commands
Vassal 3.5 includes a new console command feature for the chat log, upon which we may expand in the future. Presently it includes commands related to the errorlog and for examining and setting the values of global properties. Console commands do not function in multiplayer games.

For a list of console commands, type "/help" in the chat log. 

Customized images and help files based on VASSAL language
Starting in Vassal 3.5.4, you can select different images and help files based on the locale (language) selected in VASSAL. By default, all images are taken from the "images" folder, and the help files, by the filename indicated when building the module, but you can add "images_es", "images_fr", "images_de", etc. folders, and if VASSAL is set to Spanish, French, German, etc. alternative images will be looked for there. The images should have the same name and format that the ones in the "images" folder. You can overwrite only a few images - if the image is found in the alternative, language-specific folder, it will be loaded from image, as usual.

For help files, the same will happen, but the folder is "help_es", "help_fr", "help_de", etc. 

= Interface Improvements =

Key Command fields split
Key Command configurers have been split into two fields. The "Command" field is now where you place Named Key Commands; the "Keystroke" field is for real keystrokes. In addition to improving clarity, this eliminates certain quirky behaviors of keystroke fields when typing in new values, and allows cut/pasting into the named command fields. 

Title Bar Shows Most Recent Save/Load
The VASSAL 3.5 window title bar now includes information on the most recent save, load, or logfile accessed. For those who keep multiple VASSAL sessions open at once, this should make it far easier to tell the windows apart. 

Don't Forget To Start Logfile!
A longtime complaint has been "forgetting to start a log file" when beginning a new session. A preference "sort of" existed for this, but it wasn't working very well. VASSAL 3.5 now includes improved functionality to begin any new session (e.g. after starting a game, loading a save file, etc) by starting a logfile. There is a "Don't Prompt Again" button for those who do not care about logfiles (and this function can be toggled on the preferences screen). 

Feedback When Logging
A chat log message will confirm when logging has begun. 

Logfile Comments... They Actually Work Now!
Players previously mystified by the "enter logfile comments" prompt may want to give them another try -- logfile comments are now displayed prominently in the chat log when the file is loaded. The entry dialog has also been improved. <br style="clear:both" />

Side-Switching is Reported
Previously there was no report given at the moment a player "switched sides". It is now reported in the chat log, in bold red text.

<br style="clear:both" />

Native file chooser on Linux
Choosing files on Linux will now use the native file chooser instead of the Java Swing file chooser. This should provide a smoother, more attractive experience. <br style="clear:both" />

Default Filename Extensions
VASSAL will now attempt to complete filenames with default filename extensions (e.g. ".vmod") based on the context.

<br style="clear:both" />

= Additional Preferences Added =
 * Drag-at-edge-of-map width
 * Help button added to Preferences dialog
 * Threshold for centering on opponents move is now configurable
 * Preference to turn off sounds
 * Moved Compatibility-related preferences on the General tab to a new Compatibility tab

<br style="clear:both" /> = Technical Improvements =
 * 13494: Expose version numbers and module strings to module as properties, $VassalVersionCreated$, $VassalVersionRunning$
 * 13314: Expose Module Version number as a Global Property $ModuleName$, $ModuleVersion$, $ModuleDescription$, $ModuleOther1$, $ModuleOther2$
 * 13363: buildFile renamed to buildFile.xml
 * 13219: Added KeyNamer for overriding key names

<br style="clear:both" />

= Miscellaneous Bug Fixes in 3.5 =
 * 13593: Global preferences weren't being written except when prefs dialog was closed
 * 13509: Save As in Editor, if it fails, complained about old filename instead of new filename
 * 13495: Wizard should now set the initial value for next save/load dialog
 * 13336: Fixed incorrect date format in SecretNotesController
 * 12946: Prevent top level required components from being deleted in Editor
 * 4779: Comparison operator >= incorrectly documented as =>

= Additional Improvements in 3.5.0-beta2 =
 * 13813: Simplified communication between Module Manager, Player, Editor
 * 13792: Combined save and log loading; Load Continuation moved from File to Tools menu
 * 13777: Improved workflow of zone editor
 * 13761: Refer to MacOS instead of MacOS X now that MacOS 11 is out

= Additional Fixes in 3.5.0-beta2 =
 * 13825: "Module from older version" check is too strict
 * 13823: Map/Module Global Key Command Description not being saved
 * 13821: SendToLocation does not create Movement Trail points
 * 13783: Non-rectangular trait should remember name of image that created it
 * 13782: Suffix/Prefix fields in Layer trait are not displayed correctly
 * 13781: Bad parameter in Editor.UniqueIdManager.more_than_one message
 * 13771: NPE after cutting/pasting piece palettes in Editor
 * 13755: Chess clock help file is misnamed
 * 4324: Antialiasing RenderingHints not set properly for drawing game components

= Additional Fixes in 3.5.0-beta3 =
 * 13900: MassPieceLoader trait editor was showing standard Embellishment trait editor instead of MPL-specific one
 * 13886: Reinstate removed TilingHandler ctor for VASL 6.6.1
 * 13879: NPE in DieManager ctor
 * 13876: NPE in AbstractMetaData.getVassalVersion
 * 13868: Added description field to (nearly) all traits
 * 13853: Toolbars were missing from non-dockable windows
 * 13811: NPE in DiceButton.setAttribute
 * 13810: Find all parentless Dialogs and JOptionPanes and give them a parent

= Additional Bug Fixes in 3.5.1 =


 * 14035: Multi Action Button and Toolbar Menu lose last item in Menu Entry list
 * 14034: Prevent concurrent updates to preferences
 * 14033: Fast Match forgets fields when added to Maps and Module
 * 14032: Fast Match was picking wrong number of cards from decks
 * 14026: GameRefresher incorrectly deletes off map pieces
 * 14024: NumberFormatException when private server port is empty
 * 14023: Advanced Search displays "hit lists" properly for names/types of prototypes & configurables
 * 14018: Refresh Predefined Setup incorrectly clones at start stacks
 * 14012: Die Roll 'Prompt for values when button pushed' dialog is broken
 * 14008: Unused Images Tool was suggesting some in-use GIFs for deletion
 * 14007: NPE when adding dockable PieceWindow from module extension
 * 14000: OverlappingFileLockException when attempting to write preferences
 * 13999: Fast-Match wasn't working for "Moved" property
 * 13997: Chat log should start display on bottom line even with larger monitors
 * 13996: Sanitize temp file basenames to escape illegal characters
 * 13995: Don't try to write a logfile without having started one
 * 13993: IllegalBuildException on gpIdChecker when using GameRefresher
 * 13992: NPE in Embellishment.addLocalImageNames
 * 13991: NPE when using Game Refresher on predefined setups
 * 13988: ExecutionException when opening a moved or renamed module file
 * 13987: ChessClock buttons with icons had inappropriate height/width
 * 13984: NPE in BugUtils when involved from the Module Manager
 * 13981: NoSuchElementException using Edit All Contained Pieces
 * 13975: ArrayIndexOutOfBoundsException using Edit All Contained Pieces
 * 13973: Missing message for failure to write file
 * 13971: Cannot create new module extensions
 * 13970: DiceButton icons and Mask images incorrectly suggested for removal by unneeded-file-remover
 * 13968: NPE in HelpFile.addLocalImageNames
 * 13967: Search wasn't searching into PieceSlots ("Single Piece" items in Setup Stacks, etc.)
 * 13965: MouseoverStackViewer should not show face-down cards in decks, should not unnecessarily clip underneath text, and should not run off left edge of screen in an overzealous attempt to center-on-cursor
 * 13964: Module extension file extension incorrectly listed as .vext instead of .vmdx
 * 13960: MouseoverStackViewer mis-centering if "draw pieces" wasn't selected
 * 13959: Loads from wizard should add filename to window title
 * 13958: ExecutionException when cancelling a screenshot
 * 13954: Alt-click, Shift+Ctrl-click should not change selection
 * 13944: NPE when loading second game in modules using deprecated Map.mainWindowDock

= 3.5.1 Improvements =


 * 14040: Reference Manual cleanup
 * 14039: Improved/Repaired some tables in online docs
 * 14022: Upgrade bundled Java to 15.0.2+7
 * 14019: Remove confusing Vassal Version column from MM, show based on preference
 * 14015: Added infinite loop protection to PlaceMarker
 * 14011: Search now pre-selects contents of search field when restoring/remembering the previous contents
 * 14009: Standardize remaining dialogs
 * 13977: Alt+Shift now an option for band selection of Does Not Stack pieces
 * 13974: Better window title bars (filename-first like most apps)
 * 13930: Added infinite loop protection to TurnTracker
 * 13742: Action Button trait should arm when pressed, fire on release

= 3.5.2 Bug fixes =


 * 14104: Removing Image from BasicPiece stores image name as '(No Image)'
 * 14086: Fix Alt key for selecting on maps
 * 14078: Undo causes standard counter to become unstacked
 * 14076: SetGlobalProperty editor has incorrect label for maximum value field
 * 14075: BoardPicker and LOS_Thread could sometimes intercept commands for wrong objects
 * 14074: Flares sometimes not appearing on opponent's map (in log replay, or online)
 * 14065: Show OS Specific cut/paste key descriptions in Piece Definer
 * 14061: ArrayIndexOutOfBoundsException in StringArrayConfigurer.entryChanged
 * 14047: Prevent versions <= 3.2 from clobbering the 3.5 module list
 * 14046: Nested ExecutionException when cancelling a screenshot
 * 14043: Help button on Flare, Chess Clock, Deselect had broken link
 * 14041: Prevent race when creating GlobalPrefs
 * 14116: Incorrect module sort order in Module Manager
 * 14111: Incorrect description for Dynamic Property initial value

= 3.5.2 Other improvements =


 * 14098: Player includes module version number in window title
 * 14077: Include '(pixels)' in Turn Counter Label Display Length Label
 * 14070: Array Configurers: Add button moves focus to newly created entry
 * 14068: Key Command editor: Change return arrow icon to Tango undo icon
 * 14064: Add Refresh Predefined Setups in ExtensionEditor + (remove warning on pieces without parent)
 * 14059: Show better descriptions for Marker traits in Piece Definer
 * 14057: Piece Definer should give piece image a little breathing space on left and right by default
 * 14056: Search now covers initial/min/max values in property traits
 * 14053: Canceling Welcome Wizard closes the Player (unless "show wizard at startup" has been unchecked)
 * 14055: Set Global Property: include name/expression of property in trait list

= 3.5.3 Bug fixes =


 * 14122: IllegalArgumentException when Action Button is armed on one map but released on another
 * 14078: Undo causing standard counter to become unstacked

= 3.5.3 Other improvements =
 * 14121: Editor shows Global Property descriptions next to the names in the main list

= 3.5.4 New features =
 * 14228: Chess Clocks can now be manually reset (if manual reset is enabled for them by module designer)
 * 14217: MouseoverStackViewer - $countPieces$ will give the total number of pieces found in the stack (w/o having to create a property)
 * 14191: CurrentLanguage and CurrentLanguageName exposed as module properties

= 3.5.4 Bug fixes =
 * 14270: "maximum heap too large" message shown when maximum heap is too small
 * 14269: Poor Editor performance when using Fast Match
 * 14267: Game Refresher: Refresh Predefined Setups should clear any open game in the Player
 * 14256: LOS gets stuck on screen when replayed through logfile
 * 14255: Default autoreport text made -< instead of ->
 * 14246: Fast Match Global Key Commands were "dealing off the bottom of the deck" in certain cases
 * 14245: HTML in Tabbed Panes (charts, widgets): Work around apparent Swing bug in JTabbedPane
 * 14243: Game Piece Layer manipulation commands do not match described effect
 * 14227: Mark When Moved had Vertical offset mislabeled as Horizontal offset
 * 14226: Undo and Server buttons steal focus after being clicked
 * 14222: Editor Search output loses less-than symbols
 * 14219: Do not expand every prototype in a piece before searching it, just match the name of the prototype.
 * 14203: Global Key Commands should exit after displaying report if there is no key command to issue
 * 14200: Scenario names (Predefined Setup) should be displayed in translated language
 * 14199: Inventory text not translated
 * 14198: Translated private windows do not work when changing sides if module is translated
 * 14196: Right-click menu localization is not shown for some elements
 * 14192: Decks from previous saves and logs are retained in memory
 * 14187: Drag Thresholds shouldn't be violated by "deep legacy" mouse listeners (e.g. accepting double click AND drag from same mouse sequence)
 * 14178: Some weird systems lack awt.font.desktophints but aren't headless
 * 14168: Fix broken HTML in the 'not-allowed-in-multiplayer-games' message
 * 14164: Fast Match change persists despite Cancel
 * 14163: NPE due to File.listFiles returning null for symlnks on Macs
 * 14159: Fast Search GKC ignores "Within a deck, apply to no pieces"
 * 14156: Loading a log file to continue a game shouldn't reset the map window
 * 14155: Search was showing duplicate entries for certain items
 * 14154: Search wasn't finding "Fast Match" fields
 * 14152: .vsav, .vlog should be appended to saves, logs when not present, instead of checking for '.'
 * 14149: Windows installer fails to run uninstallers for old versions
 * 14143: First character is 'eaten' when typing chat while over map
 * 14138: Turn Tracker mispopulates button tooltip field while running in editor
 * 14136: Module-level GKCs were not honoring fast match
 * 14131: String method calls in Beanshell don't return proper result unless GetProperty is used
 * 14124: Remove "(Optional)" from Send to Location Board Name hint text
 * 14112: In Dynamic Property List of values, cursor jumps after first character entered
 * 14088: Ensure image is updated on selection of new image with duplicate filename in the Editor
 * 14069: ArrayIndexOutOfBoundsException in StringArrayConfigurer due to race
 * 13796: Stacks after the first are unstacked when multiple stacks dragged to a snap-to map
 * 13793: ArrayIndexOutOfBoundsException in CompoundPieceCollection.indexOf
 * 13472: "Send to Deck" creates phantom cards in proportion to the number of game starts
 * 13145: Send Hot Key ignored by Deck
 * 12538: Decks report multiple shuffles after loading saved game

= 3.5.4 Other improvements =
 * 14258: "Logging" and "Replaying" should have priority over "Saved" in the title bar
 * 14240: Welcome Wizard: Put "enter your name" screen after the main welcome (so that option to turn off wizard is always on first screen viewed)
 * 14209: Write logs and saves to .part file to forestall copying of partially written files
 * 14205: Allow different images to be loaded based on currrent VASSAL language
 * 14201: Share immutable objects
 * 14193: Expressions should be cached
 * 14185: Distinguish tile loading errors from other image loading errors
 * 14182: Prevent duplication of FormattedString data and Expressions
 * 14167: Inefficient implementation of FilterOutputStream in ZipWriter
 * 14148: Module Editor Labels get truncated with '...'
 * 14139: Delete trait to set 'old...' properties prior to deleting piece
 * 14133: Better support for Mac Alt and Function keys
 * 14066: Remove Unused Images: Dialog sizing and file size display improvements

= 3.5.5 Bug fixes =
 * 14348: Invisible Trait UI conflated opacity with transparency
 * 14336: MouseoverStackViewer improperly excludes does-not-move pieces when "include move-when-selected" is unchecked
 * 14332: NullPointerException in Expression.resetCachedExpressions
 * 14331: Additional Selection Highlighter fails to offset images
 * 14327: IllegalComponentStateException in ToolbarMenu.launch
 * 14322: IllegalComponentStateException in TableInfo.myKeyEvent
 * 14321: IllegalComponentStateException in PropertySheet.myKeyEvent
 * 14317: NPE in ReturnToDeck.getDeckName
 * 14310: Property Sheet options not saved
 * 14309: Missing Deck.deck translation key
 * 14301: GKC/GHK trigger actions out of order at remote end in online play
 * 14296: IndexOutOfBoundsException in BasicLogger.step when holding down step key
 * 14291: IllegalArgumentException in PlayerRoster.resetListeners
 * 14290: Online multi-player game is subject to a race condition that ends with corrupt decks
 * 14288: Deck Hotkey ignored from keyboard and Global Hotkey Trait in preset scenarios
 * 14285: IllegalArgumentException in PlayerRoster when moving items in Editor
 * 14284: Chess Clocks: fixed problem where "allow reset" option selection wouldn't "stick"
 * 14262: Missing Editor.GridEditor.command_arrow_keys translation key
 * 14225: Send Hotkey action corrupts target deck
 * 13837: Creating a Global Property with Null name causes NPE on Load Game
 * 13203: Refresh Counters causes Pieces within Decks to expand

= 3.5.5 Other improvements =
 * 14282: Upgrade to Java 16 for Windows, Mac packages

= 3.5.6 Bug fixes =
 * 14518: Zoomer hotkeys should take effect only if their map is focused
 * 14506: NPE in PieceWindow.launchButtonPressed
 * 14505: Edit Extension menu item should be disabled when the extension is already being edited
 * 14504: Improved results for users who started with no password and then set one later
 * 14503: Set errorLog encoding explicitly to UTF-8
 * 14502: Tailer misdecodes errorLog
 * 14484: Module editing permanently disabled after editing associated Extension
 * 14469: Java's ProcessBuilder misencodes Unicode outside Latin1 on Windows
 * 14468: MouseoverStackViewer: corrected text centering problem with "extra space between" setting
 * 14461: NPE in TableInfo.getExpressionList
 * 14460: StackOverflowError when referencing _Level property in layer-following expression
 * 14456: ConcurrentModificationException in GameState.setup when component setup adds components
 * 14452: Catch PatternSyntaxException on user-provided regexes
 * 14440: Counter refresh function sometimes changes stacking order of pieces
 * 14422: ArrayIndexOutOfBoundsException in Embellishment.getProperty
 * 14418: MassPieceLoader: Copy/Paste of Modified Layer trait generates Standard Layer on Paste
 * 14401: Cancelling a predefined-setup load during setup wizard shouldn't show "Loaded..." message
 * 14393: Don't show that sending bug reports failed when they've succeeded
 * 14386: Editor was reporting module saved when the "confirm overwrite" dialog cancelled
 * 14370: NPE in BasicLogger.write when there is no game state to write
 * 14368: Using String functions on property names containing double quotes in value causes Bad Module Data errors
 * 14351: NPE when Player Roster deleted from module
 * 14337: Show/Hide Palette Hotkey shows but does not hide
 * 14325: TileNotFoundException after second copy of a module in use is removed
 * 14311: Cancelling edit where a Hotkey name was changed does not cancel changes
 * 14308: Bad encoding in errorLog, bug reports
 * 14286: Prevent bad expressions from returning null
 * 14271: Chat & Notes input panel(s) treat Hotkeys differently
 * 14261: StackOverflowError: Infinite loop caused by Text Label wasn't being caught properly
 * 10755: Infinite loop in RecursionLimiter.infiniteLoop
 * 10114: ArrayIndexOutOfBoundsException in SecretNotesController.setup
 * 2623: FreeRotator does not update masked image if sides change

= 3.5.6 Other improvements =
 * 14477: MouseoverStackViewer: Show a single card when used in a PlayerHand window
 * 14453: Improved error message on failure to load a deck
 * 14408: Lock logs and saves during writes to preempt locking by programs like Dropbox

= 3.5.7 Bug fixes =
 * 14540: PgDn stopped scrolling maps downward
 * 14527: NoSuchMethodError when calling ArchiveWriter.save
 * 14526: IllegalArgumentException when rendering empty labels
 * 14521: NPE in CounterDetailViewer when Stack shapes array is longer than the piece count

= 3.5.8 Bug fixes =
 * 14599: Error logs should be read from disk as UTF-8
 * 14596: Removed initial heap setting for Importer, unused since 3.5.4
 * 14579: Mass Piece Loader cannot add 'standard' layer traits
 * 14570: Longer cancel wizard text shifts wizard divider position
 * 14568: Counter Global Key Command expression does not see properties in lower traits
 * 14479: GamePieceImages recognized by unused image removal tool

= 3.5.8 Other improvements =


 * 14600: Switch bug tracker to GitHub