First off, there is a confusing part we need to get out of the way. Pieces have a Layer trait. Maps also have a Layer trait, which is a completely different concept, and if you don’t know any better, you can confuse the two. We are going to talk about Map Layers here and not Piece Layers. We create map layers and assign pieces to those layers to have them rendered properly above and below each other.
Edit a module, click on your Main Map entry, and choose “add game piece layers.” (Again this has nothing to do with the Layer piece trait.) The default property name for a layer is “Layer.” You could change this to anything, for example “mainMapLayer”, but let’s leave it as “Layer.” Now add some layer names. Suppose we create 3 layers, top, middle, bottom. They should appear in reverse order in the display. From top to bottom, we want them to read “bottom”, “middle”, and “top”.
Now we need to assign ALL pieces that could appear on the main map to one of these layers, even the stacking ones. To do this, edit a piece (preferably a piece prototype) and add a Marker trait. (No, not the Layer trait!) Suppose it is something we want on the bottom, so in the marker we set property name to “Layer” and the value to “bottom”. The property name is important. If we had used “mainMapLayer” to define the map layers, the property name must then be “mainMapLayer”. You must do this for all your pieces, assigning them to top, middle, or bottom, even the stackers. Miss one and you will get unpredictable results. In general, I’d assign almost everything to middle, the stuff that must be on the bottom to bottom, and the markers that should be on top of everything to top.
Now when rendered on the screen, the top pieces will always appear above the middle pieces, which will appear above the bottom pieces. This is a bread and butter feature in Vassal. I believe I have used it in all the dozens of modules I have made.
One last thing. If you right-click the Game Piece Layers item you created in your main map, you should notice that you can also create a layers control. This gives you some options on managing your layers. One thing I often do here is to create a button that temporarily hides all the pieces on the map except for terrain pieces in the bottom layer. It’s really helpful to see what is underneath the pieces.