## VASSAL Reference Manual

Home > Tools > Refresh Counters

### Refresh Counters

When you update the Game Pieces in a module, or Prototypes that are applied to them, those changes will affect any future games started using that module, but the changes will not—​by default at least—​affect pieces in any ongoing games that you load with the new version of the module. The same is true of decks and stacks. VASSAL saved games include the complete definition of these components in order to maintain saved game compatibility with older versions of a module: so that replays and saves sent to you by someone with an earlier version of the module will continue to work in the same way they always did with the old version.

Since the predefined setups for module scenarios are stored internally as saved games, it is often important to module designers to be able to update an existing game to use the latest prototypes. That way a module designer can often avoid re-doing complex setups simply because prototypes have been updated and improved.

To use the refresher on the currently loaded game, go to the Tools menu in your main VASSAL window and select Refresh Counters. You will be shown a dialog with several choices affecting the manner in which the operation is to be carried out. The screenshot below shows all main options selected in order to reveal the sub-options. Normally, the Refresher’s standard mode is to refresh pieces only, without trying to identify unknown counters.

Click the Run button when you are ready to perform the refresh. The chat log will show output and statistics from the operation. Once the operation is finished, pieces in the game (as well as new pieces created from Game Piece Palettes) will make use of the most recent prototypes.

Whenever a piece is created in a VASSAL game, the Id of the definition used to create it is saved in the Piece. This Id identifies a piece in a Game Piece Palette, or a Piece Definition in a Place Marker or Replace With Other trait.

The Game Refresher works by matching the Id in each piece in the current game to the Id’s of all piece definitions in the current module to find the new definition. If a match is found, then the piece is replaced with one created from the new definition. Then each trait in the new Piece is checked to see if there is an EXACTLY matching trait in the old definition. If an EXACT match is found, then the 'state' of the old trait is copied over (e.g. what is the current layer showing, or current rotation facing).

Problems occur when the definition used to create the piece no longer exists in the module, or if traits are modified slightly so that they no longer EXACTLY match the old piece. There are various options in the Game Refresher dialog that can be used to help match and update these pieces and traits. In addition, there is an option to trigger a special hotkey to perform custom maintenance routines which you have designed.

Refresh piece definitions with latest settings from module: This feature is mandatory and will refresh Pieces in the game with the following sub-options: - Use counter names to identify unknown counters: Use this option when the piece definition used to create a Game Piece no longer exists in the module. This option tells the Refresher to find a Piece Definition with the same Basic Name as the old definition to use for the Refresh. The first such definition found will be used. - Refreshed counter will adopt matching counter’s Piece Id: This sub-option is available when "Use counter names…​" is selected. The counter will be repaired using the matching counter’s Piece Id ("GPID"). ⚠️ Exercise prudence when considering this option, to be sure that the matching counter is correct. Use Label descriptions to match modified Text Label traits: If you change any of the options in a Text Label trait, then the new definition will not exactly match the old counter and the current setting of the Text Label will revert to the default recorded in the new definition. This option tells the Refresher to find a Text Label trait in the new definition that has the same Description as in the old definition. This allows the current value of the Text Label to be carried across to the piece, even if the Text Label trait has been modified as long as the Description field has not been changed. - Use Layer names to match modified Layer traits: If you change any of the options in a Layer trait, then the new definition will not exactly match the old counter and the current Activation and Layer level will revert to the default recorded in the new definition. This option tells the Refresher to find a Layer trait in the new definition that has the same Name as in the old definition. This allows the current activation status and Layer level to be carried across to the piece, even if the Layer trait has been modified as long as the Name field has not been changed. - Use Rotator names to match modified Can Rotate traits: If you change any of the options in a Can Rotate trait, then the new definition will not exactly match the old counter and the current rotation angle will revert to the default recorded in the new definition. This option tells the Refresher to find a Can Rotate trait in the new definition that has the same Rotator Name as in the old definition. This allows the current rotation angle to be carried across to the piece, even if the Can Rotate trait has been modified as long as the Rotator Name field has not been changed. Refresh decks' properties with latest settings from module: Allow Decks in the game to be refreshed, with the following two sub-options. See the Deck Refresher section below for full details. - Delete decks which no longer exist in the module (any contents will be left on map in a stack): Remove Decks from the game that no longer exist in the module. See the Deck Refresher section below for full details. - Add decks to game which have been added to the module since this game was created (empty deck will be added): Add Decks to the game that have been added to the module. See the Deck Refresher section below for full details. After refresh trigger Global Hotkey VassalPostRefreshGHK: Use this option to invoke a special Global Hotkey, VassalPostRefreshGHK, which will execute as a final refresh step. See the Post-Refresh Hotkey section below for more details.

You can then save the game, or simply continue playing it from that point.

#### Deck Refresher

As of VASSAL 3.6 you can also refresh the Decks in a module. Like Game Pieces, Decks are not normally updated from the module definitions during a game, and so if you have an updated version of the module and load a saved game the deck will still behave according to the original settings. This maintains backward-compatibility with saves and logs made with earlier versions of a module, but it can become awkward when managing modules that use predefined setups as starting positions. The Deck Refresher lets you update, add, and delete decks in a game, for this reason.

If you select the Refresh decks option when running the Game Refresher, existing decks will be refreshed from the latest settings and positions in the module definition. This will update almost all the properties of the deck, including key commands, menu text, and the various check-box options that configure a deck. A deck can even be moved from one position to another this way. However, decks are matched by name, so changing the name of a deck will make the deck refresher think that a deck of the old name has been deleted and a new deck has been created.

##### Adding and Deleting Decks

When Refresh decks is selected, two additional options also become available, to add and delete decks.

If you select the Delete decks option, then any deck found in the current game that does not match (by name and board) a deck in the module definition will be deleted. Any current contents (e.g., cards) in that deck will be left in a stack at the deck’s former location.

If you select the Add decks option, then any new deck found in the module definition that does not exist in the game being refreshed will be added. Note this will not add any contents (e.g., cards) to the deck, it will only add the deck. If you need to add contents you will need to arrange to add them separately, e.g., from a piece palette, or dragged in from some other location.

#### Post-Refresh Hotkey

When the hotkey option is checked, the Refresher will trigger the special hotkey VassalPostRefreshGHK after refreshing. The module developer can use this feature to perform additional maintenance on predefined setup files or to facilitate upgrading of an externally loaded game. Potential uses include converting counters or populating a new deck.

This options can be used to extend the automated functionality of the game refresher, especially when running via the Refresh Pre-Defined Setups tool outlined in this section.

Design and test your maintenance actions carefully. You can use Refresh Counters to do one-off tests. Also, remember that Startup GKCs are not executed during Refresh Predefined Setups.

After using Refresh Predefined Setups, save your module as a different file name so you can do re-runs on the original if need be.

Once you are done, consider disabling or removing the maintenance components so that further refreshes don’t trigger them accidentally.