Questions about Prototyping and Best Practices

Dear Moderators and VASSAL Gurus,

After being away for a while due to a serious family illness, I returned to find 3.2.12 released, including the fine documentation for Expressions and the Bean Shell items. Thanks to all (esp. Brent) for that helpful addition, as I’ve been stumped a few times regarding syntax with Calculated Property Expressions.

I have three questions that all relate in some way to Prototypes and “best practices” in VASSAL coding (and coding in general):

  1. Copying Code - This may have been asked previously, but I cannot find the thread for some reason. Is there a way to transfer Prototypes or other portions of module code between modules? By this I mean via the GUI, such as having 2 modules open and C/P between them? I think someone said that you could do this by opening the file that stores all the raw code, but that this file was not entirely human-readable, so it might be hard to track down individual parts of a module that you wish to clone. Am I recalling this correctly, or has something changed with recent updates? If this capability is not currently available, is it at all feasible? Surely this is a common occurance for those of us who work or have worked on multiple modules.

  2. Global vs. Zone Properties - In Java (and in many other languages), programmers are vehemently discouraged from using global variables, as this violates encapsulation and risks generating effects / errors that are hard to trace. I realize that in VASSAL, Global Properties are both necessary and essential to overcome certain issues with the interface. However, I was wondering if people often create Properties within Zones or Boards in an attempt to maintain encapsulation. Is this common practice, or does this tend to create collateral problems with visibility that, in the end, must be solved by making a Property global to the Module after all? Should I potentially revamp a work-in-progress to restrict the visibility of some Properties? How do people feel about this and what do all of you do in this kind of situation?

  3. “Best Practices” Library - Is there some place (a sub-forum, sticky thread, etc.) were people could post snippets of Prototypes or Traits that constitute “standardized” ways of achieving certain actions or characteristics? For instance, I have figured out on several occasions how to use various Global Properties, Markers, etc. to create generic Prototypes that can apply to many different units in all kinds of modules. In addition, I have by trial and much error discovered how to automate some types of common game rules using various combinations of Properties, generic Prototypes and Traits. Is there a clearing house in which developers could post some of these discoveries so that we can share our collective knowledge? I’m certain that amongst us we re-invented the wheel many times over. Moderators, if this was possible and practical, what would be the best way to do this? In conjunction with this, could a portion of this “area” be set up as a “tutorial clinic” for newer users, thereby expanding the user base? I know the web site has some examples, but something within the forums may be easier to manage and maintain. Thoughts?

Thanks to everyone who has helped me in the past. Sometimes we all need a second (or third) pair of eyes to catch the errors!

Can’t help you with the rest of your post, but I can say that the buildfile is 100% human-readable, easy to decipher and a fairly convenient way of copying code between modules.

You just have to be very careful not to open a module in Vassal while it is also open in 7zip, or the module breaks and becomes unrecoverable.

For #3, I would suggest just using the wiki. It could prove to be quite valuable over time.

Rommel14

I am in a development process for a new module for Sword of Rome and have made extensive use of prototypes.

I have been heavily influenced by the work done in the TS module (credit), which leverages prototypes heavily and combines card artwork (layer traits) and card behaviour (trigger traits) together. As a best practice this ensures you get a visual confirmation with associated behaviours all at the right ‘level’. Change and improvements become sensible and appropriate to the change being performed.

This prototype structure is for card driven games (specifically the family of games from GMT) and I think represents a design pattern as such for these types of games that could be re-used in other similar games. A link to some documentation I have included in the thread for this is here:

http://www.vassalengine.org/forum/viewtopic.php?f=6&t=6288&start=45#p44755

I hope this is the sort of thing you are after.

Tim

I would not say the buildFile is 100% human readable, but it is still mostly human readable…

It’s mostly XML, which means that if you know the basics of XML you should be able to read it, and the tags names are explicit enough to be understandable. The inside of the XML is sometimes dirty with fields without names stored as a csv list :astonished:
eg :

<VASSAL.build.widget.PieceSlot entryName="Western 38b - Sextant Conference (Tot)" gpid="123" height="350" width="250">+/null/prototype;Card: TK Western	prototype;Card: total war\	piece;;;T7_cards_west_01_23.png;Western 38b - Sextant Conference (Tot)/	\	null;0;0;123</VASSAL.build.widget.PieceSlot>

I have no idea what the “null;0;0;123” or the “;;;” parts mean in this piece of code (probably some list of prototypes or similar stuff). I don’t know either whether the number of white spaces is significant or not, or why some spaces are protected by ‘’ and some aren’t… The rest is relatively human-readable.

But the good thing is, if you want to copy a prototype (or larger stuff), you don’t need to get inside, you just need to copy a whole tag and you can easily find it by its name which is written in it.
eg, for a rather complicated prototype :

<VASSAL.build.module.PrototypeDefinition name="Need supply">+/null/report;83\,715;supply: $supplied$;;;debug supply	emb2;Activate;2;;;2;;;2;;;;1;false;0;0;red-cross.png,;unsupplied +,;true;Supply status;;;true;supplied;0;1;true;65,130;;\	PROP;supplied;true,0,1,true;Toggle Out of Supply:79\,195:I\,1\\	piece;;;;/-1	2\	1\\	null;283;26;</VASSAL.build.module.PrototypeDefinition>

Here also, I have no idea how all the traits, properties, triggers and such are stored inside the XML, but I can copy the whole code into another module. Just need to put it in the right place (ie between the opening/closing tags of <VASSAL.build.module.PrototypesContainer>).

To make your life easier, give explicit names to your prototypes as you’ll be searching the buildFile for a string which is the prototype name (in this case, “Need supply”).

So, it is relatively easy to copy/paste whole prototypes, pieces, … but it is way harder to copy/paste only part of it. For this task, I recommend copy/pasting the whole prototype from the buildFiles and then copy/pasting the right traits from the Vassal GUI.
Note that the buildFile is pretty big (in my case, around 9000 lines of XML, most of them like the ones above) and you’ll want a good text editor to handle it…

Editing directly the XML is doable for certain part of it where it is more explicit than for the prototypes or pieces. For example, I have been using Perl scripts to add hilight and GP to each hex of a huge map (~4000 hexes). Doing it from the GUI would have taken way too much time but doing it with a script was OK. But the XML code for zones is way more human readable than the one for prototypes and pieces. Here’s an example of resulting code:

<VASSAL.build.module.map.boardPicker.board.mapgrid.Zone highlightProperty="eur_highlight_weather_north" locationFormat="$name$" name="wEur4213 (Dublin, Ireland)" path="1072,1277;1111,1300;1111,1346;1072,1369;1034,1346;1034,1300" useHighlight="true" useParentGrid="true"> <VASSAL.build.module.properties.ZoneProperty initialValue="normal" isNumeric="false" max="null" min="null" name="terrain" wrap="false"/> <VASSAL.build.module.properties.ZoneProperty initialValue="true" isNumeric="false" max="null" min="null" name="rail" wrap="false"/> <VASSAL.build.module.properties.ZoneProperty initialValue="true" isNumeric="false" max="null" min="null" name="city" wrap="false"/> <VASSAL.build.module.properties.ZoneProperty initialValue="true" isNumeric="false" max="null" min="null" name="port" wrap="false"/> </VASSAL.build.module.map.boardPicker.board.mapgrid.Zone>
As you can see, this is readable.

By the way, if the XML for prototypes and pieces could be as readable as the one for zones, rather than using csv to store traits and such, I would be so happy…

Another “best practices” related thing that I regret not having is the ability to put comments in the code. I need some comments to organise stuff, both because we are several people working on a module and because I forget stuff after 6 months without touching my code. Currently, I use fake prototypes or fake GP just to use the name as a comment visible from the GUI. That is not satisfactory…

Thus spake Jym:

By the way, if the XML for prototypes and pieces could be as readable
as the one for zones, rather than using csv to store traits and such, I
would be so happy&

This is one of my design goals for VASSAL 4. The entire data format
will be human-readable and documented.

Another “best practices” related thing that I regret not having is
the ability to put comments in the code. I need some comments to
organise stuff, both because we are several people working on a module
and because I forget stuff after 6 months without touching my code.
Currently, I use fake prototypes or fake GP just to use the name as a
comment visible from the GUI. That is not satisfactory&

The V4 data format and scripting will both have comment syntax.


J.

:mrgreen: YaY ! :mrgreen: