I have noticed many messages reporting bugs and module problems that all stem from the same basic misunderstanding about the way that counter traits work.
The Three most important things to remember when setting up traits in a counter are
LOCATION, LOCATION and LOCATION!
The order of traits is VITALLY important. This needs to be engraved on the forehead of every budding VASSAL module designer.
Each trait is only affected by other traits that are BELOW it in the expanded list of traits after taking prototypes into account.
If you want Text Labels to Rotate, then the Text Label trait must be ABOVE the Rotation trait. If you don’t want your Text Labels to rotate, then they must be BELOW the Rotation trait. You need to think about each trait, how it affects the counter and whether it should affect, or be affected by other traits that affect the counter.
This is a FEATURE, not a BUG. You can’t just blast in the traits you want in any order and expect them to work. You can’t move a trait from one prototype to another and expect it work in exactly the same way (though it may). You need to take into account the order of all traits in all prototypes after they have all been expanded.
Okay, how does this impact my current project? I’m adding movement trails to a set of counters that have a flipped side as a layer. Will it make a difference if I put the movement trails in above or below the layer? (And if I put them in a prototype, that would be like putting it above even if the prototype is below?)
The behaviour I have seen appears that prototypes are expanded ‘in place’
during unit creation, so that traits in a prototype maintain their relative
order as in the prototype, and sit in the piece where the prototype sits.
This is transitive, so that it generalizes to prototypes within prototypes…
Okay, how does this impact my current project? I’m adding movement
trails to a set of counters that have a flipped side as a layer. Will
it make a difference if I put the movement trails in above or below the
layer? (And if I put them in a prototype, that would be like putting it
above even if the prototype is below?)
So if I have Dynamic property (Mass) ; a text Label displaying the dynamic property (mass); an action button that activates the dynamic property’s keystrokes; and a calculated property that calculates a value based on the dynamic property… does the order of these affect their function? should the buttons be on top and the calculated be on the bottom?
I ran into this myself. I would have figured it out had it been documented. I just looked in the Game Pieces Help and it’s not there. You can’t blame someone for not understanding what isn’t documented.
(Only half in jest) Yes, you can: especially if you’re a software engineer. They resent everyone who can’t quote code, or don’t know the Windows Development Guide verse for verse. Ever notice how IT people seem to have that chip on their shoulder, so that when you call them in to solve a problem, they act as if “you should’ve known how to do this yourself”?
I move the order of elements in the design to troubleshoot when something is not working correctly, so also use the order as a troubleshooting tool before declaring a bug as 99% of the time it’s a design flaw by the designer and not vassal itself. Had a map issue that I caused and moving the map to the bottom of the design helped me figure out what was really going on. So do the same for traits on a unit and see what changes!
Is there a reason why there is not a means to define or modify the order of traits? Exposing the traits implicit order explicitly?
For example, I want all my combat units to have a Rotate trait - but I can’t include it in the prototype because all the units that inherit from that prototype also have additional layers that need to be rotatable - so I’ve got to include the Rotate in each of the sub-sub-sub prototypes AFTER all the individual layers have been defined. Not a huge issue, so I bite the bullet and just do it. But if it was hundreds of units instead of ~20 prototypes I’d be grumpy. If the base prototype for combat unit could include the Rotate trait and set it’s order attribute to be, say, 999 that would guarantee it would be last and all the other layers would come before…
I’m guessing this has been thought of and there’s either good reasons why not to do it (way too much code would have to be changed) or there’s just not enough people like me clammering for such a feature…
Here’s a quick explanation of the current architecture:
The traits in VASSAL are implemented using the “Decorator pattern” (en.wikipedia.org/wiki/Decorator_pattern). BasicPiece is the “innermost” part of the piece, and the traits are the “decorators” wrapping it one-by-one going down the list, heading to the very last trait in the list which is the “outermost”. Since the “outer” traits sit between the inner traits and the rest of the world, they are able to control the “messages” going in and out to those traits (for example an “Invisible” trait can simply choose NOT to pass along requests to draw a more inward trait, or a “Rotate” trait can alter the draw to rotate it). So that’s why traits lower down the list (further toward the “outside” of the onion layers) can affect traits higher on the list (further toward the “inside”). There are of course other choices for architecture, but this is the one we’ve inherited. Obviously if we suddenly changed it now then 20+ years of modules which depend on the existing setup might suddenly break which we definitely don’t want – this is always the delicate challenge we face as we improve VASSAL, is making changes that both improve things for future modules but keep supporting old modules! We’ve always committed to keep old modules running indefinitely. Not that it isn’t possible to come up with improvements in this area, just that it’s a lot more technically and architecturally challenging than would be “designing a brand new thing from scratch”.
One thing you could possibly do is have two different “Combat Unit” prototypes (e.g. CombatUnitDraw, CombatUnitOther) or something like that, and include them both at (different) appropriate places in your unit.
By the way, in the newer VASSAL versions (i.e. 3.4.0+), if you go to Help on your editor and go to “Game Piece”, you will find I’ve updated the documentation substantially, an in particular included some material to try to at least demystify the trait order a little bit. Here are a couple of the charts from it, but there is more material in the article. We are working on getting this material in some of the other documentation places e.g. the wiki and designer guide, and may also experiment with some “UI improvements” in the Piece Definer dialog to at least make the relationships clearer.
I can IMAGINE an upgrade where Prototype definitions were given awareness of “load layers” (sort of like Game Piece Layer Control does for drawing – we’d have to think of a better name than “layer” because we already have two confusingly different things both named that! Maybe trait “shell”? Trait “depth”?). The default would be to load all traits “in order” essentially as we normally do, but individual traits could also specify a load layer by name, in which case when the prototype was loaded into the piece those traits could end up further inward (or perhaps further outward) than is indicated by the prototypes position – so the different layers of the prototype would disperse throughout the piece to their called-for locations. That would then allow e.g. a “CombatUnit” to have a RotateTrait that specified an outward-enough load layer for itself to be able to rotate the images included in subsequent prototypes.
Of course implementing this would have two challenges – the technical one of maintaining this load-layer information and then, on load, actually doing surgery on the GamePiece to insert some traits into the middle of the existing “decorator stack”. But then the other challenge would be in the UI – coming up with a good way to communicate all this to the module designer, make it reasonably intuitive to use (rather than bringing down a whole new set of module behavior problems on their heads). Both issues could conceivably be overcome but they would require quite a lot of careful thought!
Yes, I’ve seen your updated docs - many kudos to you for your efforts, sir - they are appreciated, by those of us less informed in the arcane ways!
The warning of 20+ years of modules waiting to be broke is probably the best reason to leave this sleeping dog.
As for your idea of how to upgrade prototypes - yes, something like this was what I had imagined. I had simply thought of numeric layers (1-999) for example, but I do like your idea of symbolic layers - that would allow different ‘bins’ for traits to be added and the order that each trait was added to the bin determined its order within the bin and the bins are pre-ordered.
I found this thread when trying to troubleshoot some features that seemed to break when updating the Malifaux module to 3.4.3: it seems that the position of the ‘can rotate’ trait is no longer affecting the ‘move fixed distance’ trait. Regardless of how I position the traits, the movement always seems to be oriented with respect to the current rotation of the piece. I double checked the module on 3.2.17, and all the ordering effects seem to work appropriately, but I just can’t seem to get the position of the ‘can rotate’ trait to do anything in 3.4.3. Is there a feature update that I’m missing, or is this a new bug that’s been introduced?
Hi Andorman – please post this in the Technical Support forum, with specific steps on how to reproduce (e.g. a way to boot the specific module and look at a specific piece and do a specific thing and then “3.2.17 - right behavior”, “3.4.3 - wrong behavior”)
Hi Andorman, Do you still have an issue? I tried your latest module M3E-Malifaux-v1j.vmod out on Vassal version 3.4.3 and the ‘Move Fixed Distance’ movement direction seems to rotate correctly with the models.