Trait order in counters

[Brent Easton]

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
http://forums.vassalengine.org/mailman/ ... engine.org

Post generated using Mail2Forum (http://www.mail2forum.com)

[bsmith]

Good post Brent, I made it a sticky.

[brucesears]

thanks brent

[Damiste]

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

[Damiste]

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.

[kpilkington]

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

[pgeerkens]

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:
viewtopic.php?p=21891#p21891

[ijam]

Each trait is only affected by other traits that are BELOW it in the expanded list of traits after taking prototypes into account.

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.

[samuelw3]

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?

[jmp120]

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.

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.

[Stiglr]

jmp120 wrote:

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

[ChuckS]

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!

[jestew]

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...

[Cattlesquat]

Here's a quick explanation of the current architecture:

The traits in VASSAL are implemented using the "Decorator pattern" (https://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

trait order.png (28.91 KiB) Viewed 4224 times

[Cattlesquat]

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