UX improvement - stack management feature idea

(I hope this is the right area to post the following …)

Hi all, I’m new to Vassal and really loving it. I’ve been playing both live and PBEM and the experience is absolutely wonderful.

I’m playing Salerno '43 and one thing I’ve struggled with a bit is stack management. In particular: I can expand the stack and drop a piece into the middle of the stack … but it is pretty difficult to drop it into the right spot because there is no visual feedback as to where the piece is to be placed. I can also move a piece up and down the stack by using the arrow keys, but this is a bit fiddly and occasionally seems to be buggy (where a piece will disappear from the stack and become unelectable (but you can still see it in the hover-over-view).

Since I’m a new user, it’s quite possible that I could be using the app slightly differently and not run into these issues. Let me know if that’s the case!

Is stack management a common pain point for others?

Would it be nice to be able to easily manipulate the stack?

Without mocking it up or going into too much detail, I’m thinking something along these lines:

Perhaps some or all of the following, (A) consolidate the hover-over-view and the double-click stack expand view, (B) allow drag and drop rearrangement of pieces within the stack, (C) easy dropping in of new pieces into precise positions within the stack.


If this all seems reasonable, I might be also interested in taking a stab at developing this feature for v4. Or helping to develop the feature.

1 Like

I agree, precise placement of a new piece into a specific position in a an existing Stack is difficult and fiddly. Given that Stacks are displayed in ‘real size and position’, there is just no room to allow this.

I think I understand what you are saying. If you double-click on a Stack, then instead of expanding the stack, it opens up a small window (a bit like the stack viewer window) where you can actually manipulate the counters in the window, even drag them out to the board. Similarly, if you drag a piece over a stack and hold it, the same window will pop open and allow you to precisely place the piece.

I can see this would work well, but it isn’t something everyone would want happening all the time (for the DnD case), Perhaps the DnD case you need to hold a modifier key down to pop open the window, otherwise, it could become extremely annoying.

God idea, this is definitely worth investigating.

1 Like

Thanks Brent!

Hi All –

(I’ve rethought combining the expanded stack and stack preview. On further thought, I believe they serve slightly different, albeit overlapping use cases.)

I spent some time noodling on different approaches and this is what I’ve come up with:

A. Drag piece into expanded stack
Room is made in the stack by shifting the pieces above the drop location (up/right).

B. Drag piece into an unexpanded stack

Drag is in progress


When the cursor hovers over the stack for a few seconds, stack auto-expands, allowing an insert / drop per (A).

Note: Stack would collapse again when cursor leaves stack area.

Also note: Stack does not auto-expand on hover unless drag is in progress.

(C) Rearrange pieces in Stack Preview

Pieces can be dragged within the stack preview to be rearranged.

(Below you can see that the 142nd regiment is being moved from the 2nd position to the 3rd position.)

Note: Currently the stack preview disappears as soon as the mouse is moved. This change would require that the stack preview only disappear after the mouse had left both the stack area and the stack preview area.

(D) Drag piece into / out of the Stack Preview.

A piece is dragged into the stack preview area.

Note: In order for this to work, the stack preview area needs to be present when the mouse pointer is no longer in the area. One way to achieve this would be to have the user hold the ( on the Mac). This key could also summon the Stack Preview immediately when the mouse is over the stack. Furthermore, a tip could be shown at the edge of the preview regarding the alt key so that users could discover the feature.

(E) From-piece is ghosted, dragged piece is solid

You might have noticed throughout the examples above, I’ve ghosted the from-piece and not the dragged piece. Of course, this is not required to implement any of the above, but I think it makes the above interactions more usable and I also think it makes sense generally.

It would be great (at least imho) if (A) or something like it could be implemented prior to v4.

I’d enjoy taking a stab at the implementation myself if I thought there was a high chance that it would be accepted.

1 Like

Some thoughts:

  • I can’t read this and tell if it would be better than what we have. That’s not due to your description, but rather because UI proposals typically have to be tried to be evaluated.
  • A consequence of this is that if you’re going to undertake such a thing, you have to go into it with the expectation that you might do the work only to find out that you’ve made something which isn’t an improvement.
  • Whenever you make a UI change, even if it is objectively an improvement, there will be some people who are wrong and prefer it the way it had been. If there are enough such people and they complain loudly enough, you may end up having to add a preference to maintain the previous behavior for those benighted souls.
  • If you want to attempt implementing this for V3, there may be some UI-level design things you learn doing it which would carry over to V4, but there may also be some details you’re forced to dig into that have no applicability beyond V3. I can’t speak to your willingness to spend time on those details for V3, but at this point the well’s nearly dry for me. I’m not implementing anything new in V3 at this point myself, though I would still review PRs. My focus is on V4 now.

So, if you’re willing to put in the work to write a PR that we don’t accept and where you might have to dig into a lot of gnarly stuff where you won’t learn anything of use for the future, then I wouldn’t dissuade you from attempting this for V3. Otherwise, I’d wait to try it during V4 development.

1 Like


Thanks for the thoughtful response.

I guess I wanted to know if my effort was doomed for failure from the start or not :wink: Sonds like it is not.

I’ll take a stab at implementing something quick and dirty for usability testing and feedback.

Re v3 vs v4. Happy to implement twice if the feature makes sense

Make a PR on GitHub when you have something you want us to try.

1 Like

Let’s say for now I will target my investigation to solely making a gap in an already-expanded stack (Scenario A above).

I took a look at the code.

My understanding so far (Yes I realize this will change in v4)

There seem to be 3 classes involved:


  • Each Stack manages its own state. I’ll store whether to show an additional gap (and the index of the gap) in the Stack. Let’s call this state gapIndex.


  • StackMetrics Is in charge of how the stack is displayed including gaps.
  • StackMetrics has access to its stack, so StackMetrics can adjust the gap based on stack.gapIndex.


  • PieceMover is responsible for moving (i.e. dragging) pieces and also in detecting which piece/stack to merge the dragged stack/piece into. It uses map.pickAnyPiece(..) to figure this out.

What I’ve done so far

I implemented something very hacky (as described above) and call the code in PieceMover.mouseDragged. I can get gaps to appear/disappear, but not reliably (see Q’s below).


  1. I’m currently detecting the stack overlap inside PieceMover.mouseDragged. This method seems to be called unreliably / sporadically (I am on a Mac). Is this the right place to check for stack overlap?

  2. I’m currently using map.pickAnyPiece to decide if a piece overlaps with a stack. This has the benefit of not having to write something new. And it could work for a usability test. But, it doesn’t give exactly what I want (I want piece collision). I’d be happy to implement something else, but just wanted to check that my thinking is correct and that I didn’t miss something elsewhere in the codebase that does this (or something similar). I didn’t see any collision detection code.

Minimal input would still be helpful. Thanks for any feedback / assistance.

Okay, I think I answered Question 1. There is a 4th class that I had not seen / understood:


  • Handles the drag operation involving 1 or more PieceMovers.
  • Has dragMouseMoved method which is called reliably (and often!).

Perhaps I’ll figure out Q2 on my own as well :wink:

1 Like

I am away for a long weekend, but will help with detailed code assistance when I get back. I am very interested too see your proposals in action. As Joel says, it’s really difficult to imagine these things without actually trying therm.

Hi Brent,

That would be awesome. If you want, I’ll create a PR of what I have so far. It’ll be a few days though, since I have some other work to do first. Thanks!!!

I created a PR here for you to look at:

The PR is just a demonstration of where my understanding is currently. It is not meant to do any more than that.

I have never done any game development nor GUI work. I last looked at Java more than a decade ago. I don’t know the Vassal code base nor any of the typical patterns for GUI work. (I do have general software development experience).

Some questions re communication:

  1. I noticed that there are very few open PR’s… should I have just opened the PR on my forked REPO? I can close and move it if so.

  2. Should I ask questions here? Or directly in the PR? Or in discord dev channel? Or somewhere else?


I made a short video sharing my thinking and demonstrating the feature … at least as much as I’ve built so far:


FWIW - it might be helpful if for a stack above a certain size, it opened a small separate window with the pieces, laid out linearly, which could then be dragged to order as needed.
(top) 1 2 3 4 5 6 7 (bottom)

1 Like

Very nice video presentation. You have some great ideas that look very useful.

I’m fairly new to Vassal as well. I do want to comment on the semi-transparent “ghost” image of the unit being moved while it is between its starting location and committed to its ending location. I believe that is a feature of that module and not a standard Vassal feature. I am working on a module for an 18xx game, and I built in a similar “ghosting” while moving feature using the Layer trait with Levels follow expression value. To do this I made the opaque image for each tile, then pulled that image into Gimp to make a copy that was 60% transparent. In the Layer trait I assigned the opaque image to Level 1 and the 60% transparent image to Level 2. I created a Dynamic Property that the Layer Level would follow. This property would have either the value of 1 or 2, and I defined Trigger Actions to set the property to the desired value when a particular action happened. I would guess that there is a prototype for all the movable units that has a Layer trait using Levels follow expression value.

Personally, I like the “ghosting” of units in movement shown in the module. It allows the player to be aware of where the unit was before starting the move during its movement, and see what the unit is moving “over”. The degree of transparency is adjustable, and the method of adjustment depends on how the unit was made semi-transparent.

No, that’s a standard Vassal feature, but it doesn’t work properly on some OS versions. In the Compatibility Preference tab, try turning on the this option:


1 Like

I REALLY like that, I think that is a significant improvement on what we have now. As you suggest, with the addition of the Stack auto-expand when you drag a unit over it, after a delay, so you don’t have to manually expand the Stack before you start the move, it will be even better.

I also like the proposal that you be able to open Stack-viewer-like window where you can manipulate the units, or drop a unit in to to insert it. This would take the place of the existing read-only Stack Viewer when drag and drop is in progress.

To maintain continuity with the current UI gestures, I would make all of this opt-in and optionally controllable via modifier keys. So for example, the mini-stack-window might only appear if you hold down the Ctrl or Alt Key while dragging, or when double clicking on a stack. Need a simple way (Escape perhaps?) to close it down.

The transparency of the drag image is currently hard-coded to 50% (PieceMover.AbstractDragHandler.CURSOR_ALPHA), this could easily be changed to be a player preference.

That’s just because there aren’t many of us, we have a lot on, and things are fairly stable at the moment. Creating the PR in the main vassal repo is definitely easiest for us to see and try out.

Any of the first 3 #general in Development on Discord if any of us are on. Forum is good also, it is easier to see and find later. PR is good for specific questions about the PR. I’m answering the questions you posed there.

1 Like

Having stacks expand and make space smoothly when a piece is dragged near them is an excellent idea. Thank you for the clear and compelling presentation in your video.

I know roughly how one would do this in in a browser-based renderer driven by JavaScript. I fear it’s going to be rather difficult to do in Swing, partly because Swing is gnarly and partly because the parts of our own code which do rendering are gnarly.


I’m up for gnarly. Unless you tell me no, I’m going to give it a shot. :slight_smile:.

My thinking is to get something very hacky working as a proof of concept. If it seems like a good idea after folks are able to play with it, then the next step would be to fit it into the codebase nicely and also to make sure it performs well. I’m definitely up for those tasks as well – in fact, I’m excited.


FWIW, my thought is that this should be a player preference with a checkmark and selectable threshold:
[checkbox] open stack in separate window when stack >=: [value] (default value = 5; value grayed out if checkbox not selected)