Trait order in counters

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.

Cheers,
Brent.


Brent Easton
Analyst/Programmer
University of Western Sydney
Email: b.easton@uws.edu.au


Messages mailing list
Messages@forums.vassalengine.org
forums.vassalengine.org/mailman/ ā€¦ engine.org

Post generated using Mail2Forum (mail2forum.com)

5 Likes

Good post Brent, I made it a sticky.

thanks brent

I understand that it does not apply to shortcuts, does it?

Also, if this is vitally important, then I suggest that this is underlined both in the documentation (in bold characters) and in the piece definition dialog box.

I believe that this would only take you 5 minutes to do that, and would save lots of headaches to beginners (and not so beginners alike probably).

Regards.

Nicolas.

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ā€¦

Pieter

-----Original Message-----
From: messages-bounces@vassalengine.org
[mailto:messages-bounces@vassalengine.org] On Behalf Of kpilkington
Sent: Wednesday, February 16, 2011 1:44 PM
To: messages@vassalengine.org
Subject: [messages] [Module Design] Re: Trait order in counters

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?)


Read this topic online here:
https://forum.vassalengine.org/t/trait-order-in-counters/126/6

OK. But ā€¦

ā€¦ from my experience, the sequence of setting Global Property seems to be from top to bottom i.e. if
- GP2 is conditioned by GP1 value,
- GP1 and GP2 are trigged by the same GKC,

the code should be :

set GP1
Trigger to set GP1
ā€¦
set GP2
Trigger to set GP2
ā€¦
Right ?

Ijam.

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.

jmp120 wrote:

(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ā€? :smiley:

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.

Brian

[attachment=0]trait order.png[/attachment]

1 Like

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!

Brian

1 Like

Hey Brian,

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.

1 Like

Yeah that would be the same approach.

Also, you appear to be a Snit!!!

1 Like

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.