How can I identify the top piece in a stack?

I would like to apply a global key command to only the top unit of each stack on a map. I believe there iis a “topPiece” method but I don’t know how to use it in an expression (due to lacking Java skills). I am not even sure using this method is the right / best way to solve my problem.

Does anyone know a way to apply a global command to only the top unit in a stack?

To only one item in a stack, yes. To specifically the top item, I await replies with interest but as far as I know, it is not possible.

I have been racking my brains and checked the code, but I’ve got nothing.

Sounds like we could do with a couple of new properties exposed by pieces:

  • StackPos - position in the current Stack, 1 = top, 2 = 2nd from top etc.
  • StackSize - number of pieces in the current Stack.

Non-Stacking pieces (including Mats) would report 1 for both.
Cargo on Mats would report the details of any Stack they are in on the Mat.


I had something related - I needed to know which units were stacked under a marker as the common method in the physical game was to use a single marker and any units under that marker were regarded as having that status, e.g. Disorganized, Out of Supply, etc.

I’d noticed that when processing units in a stack Vassal always went from bottom to top. Shuffling game pieces in a hex changed the order of processing so it was always bottom to top.

However, a large caveat: Code that depends on the stability of the internal application processing is always dangerous, and should be implemented only as a last resort.

That said, the Vassal solution was a GKC to call all the game pieces in the stack, incrementing a Global Property with each game pice, with units recording the stack position into a Dynamic Property and each marker into a related Global Property. Then it was a simple case when calculating combat strengths to check whether the Dynamic Property was less than the relevant Global Property (i.e. the unit was impacted by that status), which allowed exactly the results required.

Brent’s proposal to expose the stack position would be far better.

1 Like

Thanks, I agree that this approach might be a bit fragile depending on future engine updates but I will give it a go. This problem has been plagueing me for quite a while and I am grateful for your solution! :slightly_smiling_face:

Yes indeed, Brent. Would love to see those properties added to a piece. It seems odd to me that a global command can be applied to one or more cards (pieces) in a deck but that option is not available for pieces in a stack.

If you want to have a play, there is an interim build VASSAL-3.6.8-SNAPSHOT-675de0b-11530_new_stack_pos_size_props at Builds of vassalengine/vassal .

Note this will be a 3.7.0 feature, not a 3.6.8 feature.

1 Like

I use about 8 layers. So there is always a probability of there being 8 ‘top of stack hits’ for any particular hex. The conditional statements would also need to consider which layer for the top unit to affect.
At days end, I do not see how the introduction of a few new properties can generate side issues, but after the leading zeros thing, I am wary about making changes for one ‘thing’ that may lead to breaking other ‘things’. Just my thoughts here. I do not want to stifle the creative juices that really do flow in this forum.

Adding a new property that has not existed before cannot in anyway affect existing modules, they will not be attempting to reference it. Anyone who wants to use this functionality in 3.7 will need to specifically modify their module to use it, and will need to handle Game Piece Layers and multiple Stacks in a position in their own way.

1 Like

Wow, that is service! Thanks Brent, you are a legend! :sunglasses:

Nowadays, by its preferred pronoun.


1 Like

Hello Glocko,

I have dealt with a similar problem in the past and solved it as follows using Vassal version 3.2.17. Currently, given the many improvements to the system, there is certainly a better, faster and more efficient way to achieve the same result.

First, a global numeric property must be defined:


Subsequently, for each unit present in the stack, the following traits must be defined (or, preferably, a prototype must be created that contains these traits):

A GKC must then be sent to the hex (or zone) containing the stack. The position of the stack must have been defined in advance. In the example, the X and Y coordinates have been saved on the global properties Tx and TY.

Units Count GKC

At this point it is possible to send a GKC to the topmost unit:

Target Unit GKC

Hope this can help.