How to convert to a module from other tools to VASSAL

cholmcc · April 5, 2025, 4:08pm

How to convert modules from other tools

Beside VASSAL, there are a number of other tools available for playing board games virtually. A non-exhaustive list include

Various contributors have developed modules (in VASSAL parlance) to play specific games using these tools. That means, that sometimes there is a module available for one tool but not for other tools.

For example, The Cossacks are Coming is available for ZunTzu and CyberBoard, but not VASSAL.

It is therefore useful to be able to translate modules from one tool to another. Here, we will look at how to translate from other tools to VASSAL, as, after all, that is the tool this site is dedicated to :-).

Specifically, we will look at how to convert modules from

Aide de Camp 2,
CyberBoard, and
ZunTzu

Overview of some tools

Tool	Type	Scripting	Module repositories
CyberBoard	Open-source	No	Limey Yank Games
Aide de Camp 2	Proprietary	No	Aide de Camp Die HauptKampfLinie
ZunTzu	Open-source	No	ZunTzu Limey Yank Games
VASSAL	Open-source	Yes	VASSAL Limey Yank Games

	Platforms
	Available for Linux
	Available for MacOSX
	Available for Windows
	Platform independent

From the above, it is easy to see that with VASSAL you can reach a larger audience and you can provide your end-users are better experience via scripting.

Aide de Camp 2

In Aide de Camp 2 (ADC2) modules, or specific games and possible scenarios, are called game sets.

Most of the modules available for ADC2 are linked through the ADC2 website or Die HauptKampfLinie. Notably, there is a repository of GMT ADC2 modules.

The conversion of a ADC2 module (or “game set”) is done via the VASSAL module manager.

Fire up VASSAL as per usual
In the module manager menu-bar select Tools → Convert Module… as shown in the image above.
A dialog will prompt you to select an ADC2 save file (ends in .OPS) to convert.
Select the file and let VASSAL do the work.
The module will be opened in the VASSAL editor once the conversion is done.

It may take a little while for VASSAL to complete the conversion, so have some patience.

Note, the tool converts a single save - or scenario - file at a time. Thus, the generated VASSAL module will be for one scenario only. If you want to make a VASSAL module that has more scenarios, then you need to merge the generated modules yourself.

Below is an example of converting the Wittstock scenario GMT’s Sweden Fights On

Aide de Camp 2	VASSAL
wittstock-adc2800×493 611 KB	wittstock-vassal800×505 499 KB

CyberBoard

In CyberBoard modules are called game boxes and are typically stored in files ending in .gbx, while saves, or scenarios, are typically saved in files ending in .gsn.

Both game boxes and scenarios are stored in Microsoft Archive files, which is a somewhat obscure format.

VASSAL has no built-in functionality to convert a CyberBoard module or save to a VASSAL module. However, there is a Python script that can do it.

Requirements

Python. Please see the instruction for how to install Python on your platform. Python is widely available on most platforms (if not all).
Python modules. The script requires that you have some Python modules installed. That is easily done by opening a command line and run
```
$ pip install numpy pillow svgwrite wand 
```
(see also below)
The script gsnexport.py. More information about the script can be found here.

For Windows specific issues see below

Usage

As mentioned above, a CyberBoard module consist of a game box file (.gbx) and a scenario file (.gsn). Both are needed for the conversion. If you have both these files in the same directory, then do

$ gsnexport.py <GSN-file> [<OPTIONS>]

where <GSN-file> is the name of the scenario file (ending in .gsn), and <OPTIONS> are various, optional, options for the conversion script. For more on available options, do

$ gsnexport.py --help

If you do not know how to run a script, see below.

By default, the generated module will have the same file name as the scenario file, but with the ending .vmod (rather than .gsn).

The conversion may take a while - especially if the input game box and scenario is large. Be patient. If you are in doubt that something is happening, pass the --verbose option to get a trace of what is going on.

The generated VASSAL module should be considered a draft, and further editing may be needed. One way is to use the regular VASSAL module editor. Another way is to supply a Python script (option --patch) to process the draft module exploiting the pywargame VASSAL API.

Below is an example of converting Deutches Afrika Korps from CyberBoard to VASSAL

CyberBoard	VASSAL
dak-cb800×495 223 KB	dak-vassal800×495 273 KB

Boards

CyberBoard game boxes typically define boards via drawing commands. The script translates these commands into a Scalable Vector Graphics (SVG) image. The SVGs are then turned into PNGs, which are used in the generated VASSAL module.

However, the SVG image is also stored in the generated VASSAL module. This will allow a developer to make changes in to the board image.

If the --verbose option is passed, then the SVG images are also written to disk.

Multiple scenarios

The script can only translate one scenario into one VASSAL module. If you want to convert multiple scenarios, then you must generate a VASSAL module for each of them.

It is often possible, with a bit of work, to manually merge the scenarios into a single VASSAL module and possibly multiple VASSAL save files.

Another possibility, is to use the script gsnextract.py to extract information from other scenarios, and then use a patch script to include those scenarios into the generated VASSAL module.

Modules prior to version 3.0

Note, the gsnexport.py script only supports version 3 or higher of the CyberBoard format. If you want to convert a version 2 module, then you first have to update the game box (.gbx) and scenario (.gsn) files. To upgrade the game box file open it with CBDesign.exe (Windows or Wine)

$ CBDesign.exe <GBX-file>

where <GBX-file> is the name of the game box file, and then save it.

For example, the Deutches Afrika Korps (DAK) module is version 2.1 with game box DAK.gbx and scenario 12sep40.gsn. If you open the game box

$ CBDesign.exe DAK.gbx

and then save it as DAK-v3.gbx. We also need to update the scenario file (12sep40.gsn) with CBPlay.exe (Windows or Wine) by

$ CBPlay.exe 12sep40.gsn

and then save it as for example 12sep40-v3.gsn.

We can now convert the 12sep40.gsn scenario. However, because the scenario files explicitly refers to the game box DAK.gbx (and CBPlay.exe cannot change that), we must override that when running gsnexport.py. We do that by passing the upgraded game box file as argument to the option --gamebox:

$ gsnexport.py 12Sep40-v3.gsn --gamebox DAK-v3.gbx

Issues

If the script fails on some game box, then fell free to open an issue. Please provide

a link to the game box and scenario file you are having trouble with
Your computer’s operating system (Linux, MacOSX, Windows, …) and version.
Your Python version
```
python --version
```

See also below for some common Windows problems

ZunTzu

In ZunTzu modules are called game boxes and are typically stored in files ending in .ztb, while saves, or scenarios, are typically saved in files ending in .zts.

A ZunTzu game box (really a ZIP archive) always comes with at least one scenario (really an XML file) embedded with the module.

VASSAL has no built-in functionality to convert a CyberBoard module or save to a VASSAL module. However, there is a Python script that can do it.

Requirements

Python. Please see the instruction for how to install Python on your platform. Python is widely available on most platforms (if not all).
Python modules. The script requires that you have some Python modules installed. That is easily done by opening a command line and run
```
$ pip install numpy pillow svgwrite wand 
```
(see also below)
The script ztexport.py. More information about the script can be found here.

For Windows specific issues see below

Usage

As mentioned above, a ZunTzu module consist of a game box file (.ztb) with at least one embedded scenario file (.zts). Do

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

where <ZTB-file> is the name of the game box file (ending in .ztb), and <OPTIONS> are various, optional, options for the conversion script. For more on available options, do

$ ztbexport.py --help

If you do not know how to run a script, see below.

By default, the generated module will have the same file name as the scenario file, but with the ending .vmod (rather than .ztb).

The conversion may take a while - especially if the input game box and scenario is large. Be patient. If you are in doubt that something is happening, pass the --verbose option to get a trace of what is going on.

The generated VASSAL module should be considered a draft, and further editing may be needed. One way is to use the regular VASSAL module editor. Another way is to supply a Python script (option --patch) to process the draft module exploiting the pywargame VASSAL API.

It is a good idea to play around with the various possible options for the conversion script. In particular mutually exclusive options --all-maps and --one-map.

Below is an example of converting _Strike the Bear from ZunTzu to VASSAL

ZunTzu	VASSAL
stb-zt800×502 229 KB	stb-vassal800×502 307 KB

Multiple scenarios

All scenarios found in the ZunTzu game box are converted to VASSAL saves (.vsav) which are then stored in the generated module (.vmod) and listed as Predefined setup.

The script cannot convert a standalone ZunTzu save file. However, if you place your favourite ZunTzu save file (.zts) inside the game box (.ztb), using your favourite ZIP file manager, before the conversion, then that save will also be made into a scenario.

Resolution

If you get the error cache resources exhausted try lowering the
resolution (-r).

Multiple maps

If the ZunTzu gamebox does not use selectable boards, pass the option -a to generate maps for all defined maps. Otherwise, the script will assume that all maps are alternatives for the default map.

Issues

If the script fails on some game box, then fell free to open an issue. Please provide

a link to the game box and scenario file you are having trouble with
Your computer’s operating system (Linux, MacOSX, Windows, …) and version.
Your Python version
```
python --version
```

See also below for some common Windows problems

Running scripts

On Linux

To open a Terminal. If you are using Linux, then you probably already know how to do that. If you don’t use your Desktop environment to locate a Terminal (search for it). You can also see this video.

You will get a new window with a command prompt in it - something like

In this prompt, you can execute commands and script. For example, to change directory to your Downloads, Documents, or VASSAL folder, you would do

$ cd ~/Downloads
$ cd ~/Documents
$ cd ~/VASSAL

respectively.

Here, ~/ means your home directory. To see which files are in a given directory, say Downloads, you can do one of

$ cd ~/Downloads
$ ls
 12Sep40.gsn   DAK.gbx   gsnexport.py  'Strike the BearATO.ztb'   ztexport.py

or

$ ls ~/Downloads
 12Sep40.gsn   DAK.gbx   gsnexport.py  'Strike the BearATO.ztb'   ztexport.py

To run a script, say foo.py located in current directory, do

$ ./foo.py

To run a script, say ~/Documents/bar.py in some other directory, do

~/Document/bar.py

On MacOSX

First, you need to open a Terminal. To do that you can open Finder, click Applications in the left-hand pane, and find and open the Utilities folder. Then find the Terminal application and double-click that. See also this video.

You will be greeted by a yellow-ish window with black text (by default), which a prompt like

user@host ~ #

or something similar.

Everything else is done the same as for Linux above.

On Windows

First, you need to open a command prompt. To do that, press ![windows](upload://elIS1R7NWhqqZb07mFyAHGQs55d.png)-R and type

cmd

in the pop-up dialog. You will be greeted by a black window with light-gray text and a command prompt

C:\Users\foo>

where foo is your user name.

At this prompt (which should be familiar to any ol’school DOS users), you can execute commands.

An alternative to cmd.exe is the so-called PowerShell. While marginally better than cmd.exe it does not have the power that warrants the name “power-shell”.

To change directory to your Downloads, Documents, or VASSAL folder do

C:\Users\foo> %HOMEDRIVE%
C:\Users\foo> cd %USERPROFILE%\Downloads
C:\Users\foo> cd %USERPROFILE%\Documents
C:\Users\foo> cd %USERPROFILE%\VASSAL

respectively (%HOMEDRIVE% switches to the “drive” where your home directory is located, typically C:). Here, %USERPROFILE% is an environment variable holding the value of your home directory

To see which files are in a given directory, say Downloads, you can do one of

C:\Users\foo> cd %USERPROFILE%\Downloads
C:\Users\foo\Downloads> dir
Directory of C:\Users\foo\Downloads

MM/DD/YYYY  HH:MM AM    <DIR>          .
MM/DD/YYYY  HH:MM AM    <DIR>          ..
MM/DD/YYYY  HH:MM AM            21,526 12Sep40.gsn
MM/DD/YYYY  HH:MM AM           992,144 DAK.gbx
MM/DD/YYYY  HH:MM AM           516,865 gsnexport.py
MM/DD/YYYY  HH:MM AM        76,116,870 Strike the BearATO.ztb
MM/DD/YYYY  HH:MM AM           431,864 ztexport.py
       5 files               78,079,269 bytes
       2 directories           a lot of bytes free

or

C:\Users\foo> dir Downloads
Directory of C:\Users\foo\Downloads

MM/DD/YYYY  HH:MM AM    <DIR>          .
MM/DD/YYYY  HH:MM AM    <DIR>          ..
MM/DD/YYYY  HH:MM AM            21,526 12Sep40.gsn
MM/DD/YYYY  HH:MM AM           992,144 DAK.gbx
MM/DD/YYYY  HH:MM AM           516,865 gsnexport.py
MM/DD/YYYY  HH:MM AM        76,116,870 Strike the BearATO.ztb
MM/DD/YYYY  HH:MM AM           431,864 ztexport.py
       5 files               78,079,269 bytes
       2 directories           a lot of bytes free

To run a script, say foo.py located in current directory, do

Z:\Some Directory> ./foo.py

To run a script, say ~/Documents/bar.py in some other directory, do

Z:\Some Directory> %USERPROFILE%\Documents\bar.py

Common Windows issues

As with anything Windows, it can sometimes be a hassle to get things to work - and often for entirely obscure reasons. Below are some issues that have been reported.

Over-zealous Windows anti-virus software may block scripts from running, or may quarantine generated files. Check your anti-virus software settings.
When installing Python, you should enable the option Add python.exe to PATH.
You may need to install ImageMagick by hand (typically, wand from above would pull that in itself). Make sure to enable the option Add application directory to your system path.
If you execute a Python script and nothing seems happen, even if you pass a verbose option, then try f.ex.
```
Z:\Some Directory> python foo.py
```
to see if you get more information.

If the command prompt cannot find the program python, try giving the full path - e.g.,
```
Z:\Some Directory> C:\Program Files\Python\PythonXYZ\python.exe foo.py
```
if you installed Python system-wide, or
```
Z:\Some Directory> C:\Users\foo\AppData\Local\Programs\Python\PythonXYZ\python.exe foo.py
```
if you installed Python for a single user (foo).

The same also applies to pip, e.g.,
```
Z:\Some Directory> C:\Program Files\Python\PythonXYZ\Scripts\pip.exe install ...
```
if you installed Python system-wide, or
```
Z:\Some Directory> C:\Users\foo\AppData\Local\Programs\Python\PythonXYZ\Scripts\pip.exe install ...
```

A word about copyright

Caveat: I am not a lawyer.

Note, if you use these tools to convert a CyberBoard or ZunTzu GameBox to say a VASSAL module, then you are creating a derived product from the original, possibly copyrighted, product (the game box). Thus, if you want to distribute, even to friends, the generated VASSAL module, you must make sure that you are licensed to do so.

If the GameBox is licensed under an Open Source license, like Creative-Commons Attribution, Share-Alike, GPL-3, or similar, you are explicitly permitted to distribute your derived work.

Note, if the converted data contains graphics or the like, it may not be the module developer that holds the copyright to those materials. The developer may (or may not) have obtained permission to distribute the materials, but that does not imply that permission is given to third party.

However, what is copyrightable and what is not obvious. Only original and artistic forms of expression can be copyrighted. Ideas, and similar, cannot. That means that the mechanics of a game cannot be copyrighted. The exact graphics and phrasing of the rules can.
If you make distinctive new graphics and rephrase the rules, it is not subject the original copyright. Note, however, that it is not enough to change a colour or font here or there - it has to be original.

Note that you are free to make your own copy, as long as you obtained the original legally. Copyright only matters if you plan to redistribute, irrespective of whether or not you monetise the redistribution, or if the redistribution is private or public.