[messages] [Module Design] Questions about Prototyping and Best Practices

Jym jean-yves.moyen at ens-lyon.org
Tue Jul 15 13:01:24 CEST 2014

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  :o 
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
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:

highlightProperty="eur_highlight_weather_north" locationFormat="$name$"
name="wEur4213 (Dublin, Ireland)"
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"/>

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…

Read this topic online here:

More information about the messages mailing list