How to calculate total of numeric Property of all pieces in particular location/state.

From Vassal


Suppose you have army units, each of them have numeric Marker named "Strength" and you need to calculate total Strength of units located in particular zone. Or you need to count cards in the zone (or map or whatever). Generally when you want calculate total of some numeric property of pieces in particular state (e.g. face-up) use this method. In this HowTo we consider calculating total Strength of pieces in the zone.

The idea

First of all you need to know command(s) that issues when pieces change state, i.e. when they moved, flipped, deleted etc. For the purpose of this module (calculating total Strength of pieces in the zone) we need only "Key Command to apply to all units ending movement on this map" (and remember about Delete command if you use Delete trait). When a piece lands on the zone it uses SetGlobalProperty command to increase the total value by value of its Strength. When a piece leaves the zone it uses SetGlobalProperty command to decrease the total by its Strength. To exclude the case of constantly increasing the total when moving a pieces within the zone, pieces have a Dynamic Property named "Counted" (you may name it as you want) and possed two values: "yes" indicated that the piece already taken into account, and "no" when it is not.

IMPORTANT WARNING: In other tutorials or forums you might suggested to use values named OldMap, OldZone or any other variable started with "Old"! I insist you do NOT do that!

Here's why: 1) these variables are valid only when you drag pieces by mouse, they do not work when you move piece via command such as SendToLocation and ReturnToDeck; 2) using the Dynamic Property "Counted" is the more error-proof method.

Detailed instructions

Assume that you already have Main Map, the Zone, Global Property "TotalStrength" and text label $TotalStrength$ somewhere on the Map (to view a result). You also have defined all Pieces (we called them Units), each of them has Marker trait called "Strength" with numerical value.


1. Set "Key Command to apply to all units ending movement on this map" in your Windows in the module. You cannot guess where users may send their pieces, so apply this command on ALL your windows: Map Windows, Private Windows, Player Hands etc.


2. Create Game Piece Prototype (if you have not done this already) that contains traits that are the same for all Units. We've named it "Unit". It will contain our engine. Add this Prototype to all your units.


3. In the prototype create two Trigger Actions: one for increasing TotalStrength and other for decreasing it. Conditions are: 1) if Unit is in the our Zone and still not Counted, then increase TotalStrength (incTS) and set Counted variable to "yes" (setC); 2) if Unit is landed off the Zone and was Counted, then decrease TotalStrength (decTS) and set Counted variable to "no" (unsetC).


4. Add Set Global Property "TotalStrength" to the prototype. Here you define two commands incTS and decTS that you have used in the Trigger Actions.


5. Add Dynamic Property "Counted" to the Unit prototype. Here you define two commands setC and unsetC that you have used in the Trigger Actions.


Additional programming for Delete trait

If you want to have Delete trait make sure that you decreace TotalStrength BEFORE actual delete. You cannot simply insert "del" command to Watched Keystrokes of "decrease TotalStrength" Trigger Action trait (if you do, then the TotalStrength would not be decreased since the "Strength" Marker would be unset at the moment of calculating).

To do this properly break delete task by two consecutive commands: be4del and ultdel (abbreviated forms of "before delete" and "ultimate delete" respectively). So create Trigger Action, in which you write text "Delete" for menu and add be4del and ultdel commands.


You should also create separate "decrease TotalStrength" Trigger Action for be4del command because of slightly different condition of trigger. In contrast to previous "decrease" Trigger Action you only check Counted value (without checking location, because when the piece will be deleted it would go nowhere) and you issue only decTS command (without unsetC, because the Counted property would be meaningless).


Remove text "Delete" from Delete trait, the command for it is ultdel.


Test module

Here is test module with example of our engine.

Filename Filetype Size Date Compatibility
HowToSum.vmod module 4 KB 2016-02-13 3.2.15