Script to convert ZunTzu GameBox to VASSAL module

[cholmcc]

Hi all,

I’ve made a script that can convert a ZunTzu GameBox, including nested scenarios, to a VASSAL module. You can find it at

• wargames_tex / pywargame · GitLab

Use the script like

$ ztexport.py <ZTB file> [<OPTIONS>]

to generate a VASSAL module. Pass the option --help for help on options. For example the option -p which allows you to pass a Python script to patch the generated VASSAL module.

The generated module should be considered a draft, and you may need to flush things out in the VASSAL editor (or by other means).

The script is not omnipotent and your milage may vary

The script is part of the project pywargame which also has a tool to convert a CyberBoard scenario to a VASSAL module as well as the Python module vassal.py to programmatically create and modify a VASSAL module.

You do not need to have ZunTzu or VASSAL installed to use these tools. All you need is Python.

Yours,
Christian

[KevOs4]

Christian -

Every attempt I have made to use this utility on my 64-bit Windows 10 system yields this sort of error:

I:\Documents\ZunTzu>ztexport.py “Honour Alone v1.1c.ztb”
Failed to build Honour Alone v1.1c.vmod: name ‘v’ is not defined
Traceback (most recent call last):
File “i:\documents\ZunTzu\ztexport.py”, line 12375, in
raise e
File “i:\documents\ZunTzu\ztexport.py”, line 12363, in
exporter.run(output,patch)
~~~~~~~~~~~~^^^^^^^^^^^^^^
File “i:\documents\ZunTzu\ztexport.py”, line 10727, in run
self.createBuildFile()
~~~~~~~~~~~~~~~~~~~~^^
File “i:\documents\ZunTzu\ztexport.py”, line 11620, in createBuildFile
self.addScenarios()
~~~~~~~~~~~~~~~~~^^
File “i:\documents\ZunTzu\ztexport.py”, line 12154, in addScenarios
self.addScenario(sc,menu)
~~~~~~~~~~~~~~~~^^^^^^^^^
File “i:\documents\ZunTzu\ztexport.py”, line 12190, in addScenario
piece_map = self.remapIds(scenario)#self._gamebox._piece_map
File “i:\documents\ZunTzu\ztexport.py”, line 12164, in remapIds
v(f’Missing counter sheet {layout._name} - maybe map’)
^
NameError: name ‘v’ is not defined

Any suggestions? Thanks.

[alecrespi]

Hi,
try renaming the original file (Honour Alone v1.1c.ztb) to something simpler (like HA11.ztb) and see if it gives the same error message…

[cholmcc]

@KevOs4

File “i:\documents\ZunTzu\ztexport.py”, line 12164, in remapIds
v(f’Missing counter sheet {layout._name} - maybe map’)
^
NameError: name ‘v’ is not defined

A bug had snug in when fixing another bug Try redownloading the script.

@alecrespi

try renaming the original file (Honour Alone v1.1c.ztb) to something simpler (like HA11.ztb) and see if it gives the same error message…

While spaces in file names are sometimes problematic - @KevOs4 did correctly quote the file name - that was not the issue. It was a mistake on my part

Yours,
Christian

[cholmcc]

@KevOs4

File “i:\documents\ZunTzu\ztexport.py”, line 12164, in remapIds
v(f’Missing counter sheet {layout._name} - maybe map’)
^
NameError: name ‘v’ is not defined

BTW, consider to put logs, errors, etc. in between a set of triple back-tics ``` like

```
File “i:\documents\ZunTzu\ztexport.py”, line 12164, in remapIds
v(f’Missing counter sheet {layout._name} - maybe map’)
^
NameError: name ‘v’ is not defined
```

That makes the error messages far easier to read and makes it easier for anyone to help you. Thanks.

N.B.: The Forum platform allows for use of MarkDown, which can give your posts rich formatting and really make them stand-out and easier to read.
Bold face is done by putting two * around the thing to put in bold face as in **Bold**.
Italics can be done with two _, as in _Italics_.

Links are [Link text](link url) - e.g., [VASSAL](https://vassalengine.org).

Images can be included with ![Alternate text](image url) - for example [VASSAL banner](https://vassalengine.org/images/wordmark-path.svg).

Tables are also possible with | and -, as

| Column 1 header | Column 2 header |
|-----------------|-----------------|
| Row 1 column 1  | Row 1 column 2  |
| Row 2 column 1 | Row 2 column 2     |

to give (note - spaces are largely irrelevant)

Column 1 header	Column 2 header
Row 1 column 1	Row 1 column 2
Row 2 column 1	Row 2 column 2

Lists are easily done with a - or * at the start of the line, and they can be nested by putting 2 spaces in front of subsequent - or *

- First item
- Second item
  - 1st sub item of second item 
  - 2nd sub item of second item
- 3rd item

to give

• First item
• Second item
  • 1st sub item of second item
  • 2nd sub item of second item
• 3rd itemd

Numbered lists are similar, except they start with some number followed by a period ., e.g., and sub items are indented by 3 spaces

1. foo
   1. bar 
   4. baz 
5. Gnus
2. Gnat

yielding

1. foo
   1. bar
   2. baz
2. Gnus
3. Gnat

Yours,
Christian

[KevOs4]

Christian -

Yes, that fixed the problem. The conversion works remarkably well now, although the results are (as you admit) not perfect. Thank you.

TG

[KevOs4]

Christian -

I suggest that you convert counters to have twelve steps of rotation rather than six in order to match the ZT standard.

TG

[cholmcc]

@KevOs4

although the results are (as you admit) not perfect.

Do remember to play with the various options for the script - in particular the -a option. The default is to assume that boards are alternative boards. That’s true in some cases, and not in others - depending on how the developer made the Zun Tzu game box (the distinction is a little clear in VASSAL). Hence, for some game boxes it makes sense with the default and for others it make sense to use the -a. There’s no way, as far as I can tell, to figure the right setting form the Zun Tzu game box itself.

@KevOs4

I suggest that you convert counters to have twelve steps of rotation rather than six in order to match the ZT standard.

I was considering that too. ZunTzu seems to allows an almost infinite number of rotations, which is possible in VASSAL, but is often not the right thing.

Also, the ZunTzu save format allows one to specify a rotation and a front-back flip state. That is also possible in VASSAL, but because of the rather obscure save format of VASSAL, it is a bit of a head-ache to implement.

Yours,
Christian

[cholmcc]

Hi all,

I’ve updated the script a bit more, and fixed some rather annoying bugs that meant the script got a lot of stuff wrong much of the time. Should be OK now. Also, the flipped and rotated states of pieces is now propagated to the generated save files. Should make life a little easier.

Yours,
Christian

[KevOs4]

Christian -

Thanks for this work. Converted scenarios now show rotation, but, unfortunately, it is not the correct rotation. Here’s an example:

I think this could be at least partly due to the 6 steps vs. 12 steps issue. The gamebox in question is Atlanta Campaign.

By the way, I have never encountered a ZTB that had anything other than 12 steps of rotation.

TG

[cholmcc]

@KevOs4

I think this could be at least partly due to the 6 steps vs. 12 steps issue

You can set the number or rotation steps with the option -R. If you set it to 1 you will get infinite rotations.

Yours,
Christian

[KevOs4]

Christian -

My guess was wrong. Adding the switch -R12 does indeed change the setup, but now all rotated pieces have exactly the same orientation in the Vassal module regardless of their original facing in the ZunTzu gamebox:

But, at least now it is possible to correct the rotations manually, which previously required an initial edit of the Basic prototype in the VMOD.

I really do appreciate your diligence in addressing this issue.

TG

[cholmcc]

@KevOs4

The gamebox in question is Atlanta Campaign.

Could you provide a link? That really would help in finding any possible bugs, as it is difficult to test against all possible variantions of game boxes.

@KevOs4

Adding the switch -R12 does indeed change the setu

There should be a space between -R and 12 as in

./ztexport.py -R 12 AtlantaCampaign.ztb ... 

Otherwise, it may be interpreted incorrectly. which may be the reason for

@KevOs4

ow all rotated pieces have exactly the same orientation

@KevOs4

I really do appreciate your diligence in addressing this issue.

No worries. But I would still like test against your game box, so please provide a link. Thanks.

Yours,
Christian

[cholmcc]

@KevOs4

now all rotated pieces have exactly the same orientation

OK, I think I found the problem - VASSAL has a very funny way of calculating rotation index when using a fixed number of rotations.

@KevOs4

By the way, I have never encountered a ZTB that had anything other than 12 steps of rotation.

ZunTzu as such does not define a way to specify the number of rotation steps. Instead, it seems to allow for arbitrary rotations (or at least a great many number of them), so it would seem wrong to say they always allow 12 rotations - ZunTzu has no concept of limiting rotations at all. If you pass -R 1 you will get more or less the same behaviour in the generated VASSAL module.

Still, I’d like to test things on the game box you are playing with - please provide a link.

Yours,
Christian

[KevOs4]

Christian -

I did not post this particular gamebox to the ZunTzu website due to intellectual property concerns, but you can use Iron Brigade for testing instead, as a conversion appears to exhibit the same behavior.

TG

[cholmcc]

@KevOs4

I did not post this particular gamebox to the ZunTzu website due to intellectual property concerns,

Not sure exactly what you mean by “Intellectual Property” - Copyright? Trademark? …?

@KevOs4

but you can use Iron Brigade for testing instead, as a conversion appears to exhibit the same behavior.

Well, the Iron Brigade game box saves do not really rotate pieces beyond the 60° intervals, so in that sense, it’s not a good test.

Also, I looked through the source code of ZunTzu and it seems that ZunTzu does rotations in increments of 10° always. In that sense, a reasonable default would be -R 36.

Anycase, try re-downloading ztexport.py - I’ve fixed a number of things, and also add symbolic dice - similar to ZunTzu’s (though not animated).

Yours,
Christian

[KevOs4]

Christian -

I should clarify. Facing changes are so quick and easy in ZunTzu that there is no need to limit the degree of change. In contract, with Vassal it is best to optimize the number of rotations in order to avoid the need for repeated keypresses. But, twelve steps are desirable in the conversions so that the output can handle any combination of facing type (hexside or hexpoint) and grain (vertical or horizontal).

“Intellectual property” is the collective legalese term covering patent, trademark, and copyright.

TG

[cholmcc]

@KevOs4

I should clarify. Facing changes are so quick and easy in ZunTzu that there is no need to limit the degree of change. In contract, with Vassal it is best to optimize the number of rotations in order to avoid the need for repeated keypresses. But, twelve steps are desirable in the conversions so that the output can handle any combination of facing type (hexside or hexpoint) and grain (vertical or horizontal).

If you choose free rotation, -R 1 with ztexport.py, you have a similar behaviour to ZunTzu: Select piece or stack, press short cut or select from context menu, and drag to rotate. Not a question of key strokes, but of meaningful rotations relative to the game. For most hex’n’counter 6 facings is all you want, if at all ZunTzu does not have those considerations and applies a one-rule-fits-all approach.

You can of course choose whatever number of facings, including “infinite” , that best fit your needs.

@KevOs4

“Intellectual property” is the collective legalese term covering patent, trademark, and copyright.

“Intellectual property” has no well-defined legal meaning, and is mostly used by cooperate people to refer to some vague, ill defined concept. Historically, “Intellectual property” has been used to scare competitors without much substance. In terms of games, I generally refer to this thread on BGG, which lays out the legal terms quite well.

I hope the recent changes to ztexport.py works for you and you can get a good starting point for further VASSAL developments.

Yours,
Christian