VASL Templates
  • Installation
  • User Guide
  • Chapter H
  • Template packs
  • For developers
  • License

VASL Templates is a web application that runs in a browser, but since it hasn't been set up as a web site on the public internet, you will need to run the web server yourself.

As a convenience, a program is provided that bundles the web server together with an embedded browser, so that it runs as if it were a normal desktop application.

Installing on Windows

If you're using Windows, you should get the pre-built version from Github, unpack it somewhere, then run vasl-templates.exe

If the program won't start because a DLL is missing from your computer, install the VC2015 runtime (get the 32-bit version, vc_redist.x86.exe, even if you are running 64-bit Windows).

If you don't see anything in the main window, check the notes below about configuring OpenGL.

Running from source

If you're on a Mac or Linux, you can run the program directly from the source code. Get a copy from Github in the usual way, by git clone'ing it, or downloading a ZIP and unpacking it somewhere.

The web server was written and tested using Python 3.6, but it doesn't do anything particularly funky, so any recent version of Python should work.

While not essential, it is strongly recommended that you set up a virtual environment first. Then, install the requirements:

pip install .[gui]

Running the desktop application

If you're on Windows, the Qt runtime will have been installed as part of PyQt5 (when you did the pip install above), but if you're in a virtual environment and you're getting "DLL load failed" errors, this is due to a problem with the way Python sets up the virtualenv. In the virtualenv's scripts/ sub-directory, there should be two Python DLL's, so if you're missing python3.dll, copy it over from the Python installation the virtualenv was created from, and you should be good to go.

If you're on Linux, you will need to install Qt 5.10.0. While your distro may have it as a package, I didn't have much luck on Fedora 27, and had to install it manually using their installer.

Then, just run the vasl-templates command.

Running just the web server

The simpler option is to just run the web server:

python vasl_templates/webapp/run_server.py
and then connect to it in a browser at http://localhost:5010.

Running a Docker container

If you have Docker installed, the webapp can be run in a container:

docker run --rm -it --name vasl-templates \ -p 5010:5010 \ -v /home/pacman-ghost/vasl/vasl-6.4.4.vmod:/data/vasl.vmod \ -v /home/pacman-ghost/vasl/extensions/:/data/vasl-extensions \ vasltemplates/images:latest
To include Chapter H data, add the following:
-v /home/pacman-ghost/vasl/chapter-h:/data/chapter-h-notes

Then open a browser and connect to the webapp at http://localhost:5010.

Note that some features (e.g. updating and analyzing VASL scenario files) may not be available.

If you have SElinux enabled, it may prevent the container from accessing files on the host. Access can be allowed like this:
chcon -Rt svirt_sandbox_file_t /home/pacman-ghost/vasl/

Installing a webdriver

Some features require a webdriver to be installed. You can use either:

  • geckodriver (requires Firefox to be installed)
  • chromedriver (requires Chrome to be installed)

Unpack the download ZIP file somewhere (it will contain a single executable file), and configure the location in the Server Settings dialog (or set WEBDRIVER_PATH in site.cfg, if you are running from source).

I'm having problems running the desktop application

The desktop application uses OpenGL for the embedded browser, so if you are getting error messages about OpenGL, or the main window is not displaying properly, you can try configuring OpenGL to work in a different way.

Create a file called debug.cfg in $/config/ (the same directory that contains a file called app.cfg) that looks like this:

[Debug] OPENGL_TYPE = AA_UseSoftwareOpenGL
Other possible values are AA_UseDesktopOpenGL and AA_UseOpenGLES.

If you're on Windows, this page might also help.

In the worst case, you can set up your debug.cfg file like this:

[Debug] DISABLE_WEBENGINEVIEW = 1
The program will then not attempt to create the embedded browser, and will just start the web server, which you can then connect to in an external browser at http://localhost:5010.

VASL Templates makes it easy to set up attractive VASL scenarios, with loads of useful information embedded to assist with game play.

We'll show how by walking through a setup of everyone's favorite scenario, Hill 621. Click on the screenshot to the right to see the finished scenario.

You can find more examples here, with files that you can load into the program, together with the generated VASL scenarios.

Adding the scenario details

First, we enter the basic details about the scenario.

Click on one of the Snippet buttons, and the program will generate an HTML snippet and put it into your clipboard, which you can then copy into a VASL label.

You can also click on the Search ROAR button, to look for a scenario in ROAR. The basic details for the scenario will be loaded, along with the latest results.

To create a label in VASL, open the Draggable Overlays window, and drag a label onto the main window.

Labels come in two parts, which are accessible via the right-click menu, or press Ctrl-L and Ctrl-2 to access each one. I always just use the first line, so I delete everything in line 2.

The thick black box indicates that the label is selected. If you click elsewhere on the main window, it goes away, and the label will remain in place even if you click on it, or try to drag it. To select it again, Shift-click somewhere in the box, and you will be able to move it around, or edit it. This can sometimes be difficult to find, since it's not visible on-screen, but it will be in the middle (vertically and horizontally) of the label.

Once you have a label in VASL, copy the HTML snippet generated above into it.

Repeat the process to add the ELR and SAN for both players, and you will now have two labels that you can position in the VASL scenario.

Automatically adding labels to the VASL scenario

Once you've got the hang of adding labels to your VASL scenario, you can get VASL Templates to do it automatically for you. After entering all the scenario details, choose Update VASL scenario from the menu, select the .vsav file you want to update, and all the labels will be inserted into the scenario (or updated, if they're already there).

VASSAL will be run to update the scenario, so you may see it temporarily appear on-screen. The process can be a little slow, and may take several minutes to complete.

Adding victory conditions and SSR's

Adding the scenario's victory conditions is straight-forward. We're generating HTML snippets, so we can type in things like ≥ to get ≥ in the VASL label.

 

Note that we explicitly set a width for the snippet (240px), which caused the text to wrap onto a new line. You could also do this by manually inserting <br> tags where you want line-breaks.

To add SSR's, click on the green plus button in the SSR section and add the SSR text.

Click on the OK button when you're done, or press Ctrl-Enter.

If you want to go back and change the text of an SSR, just double-click on it.

Once they're all in, click on the Snippet button to get a nicely formatted bullet list.

Adding each player's OB

Adding each vehicle and ordnance for each player is just a matter of selecting them from a list, and the generated HTML snippet will produce a table of information for each one (see right). Very handy if you have a menagerie of armor and you're, say, looking for something that can fire Smoke.

The scenario date is taken into account when generating these tables e.g. APCR for the Pz IVH is A52, but since the program knows the scenario is set in 1944, it just shows A5. Had the scenario been set in 1941, it wouldn't be shown at all.

It's also possible to include Chapter H notes in your scenarios, although you will need to set some things up first.

Double-click on an entry to make changes to it e.g. because an SSR changes its capabilities, or you'd like to add a note.

We can also add ad-hoc notes describing where and how units should setup.

Click on the icon in each note to generate its snippet, or Shift-click on it.

Finally, if special support weapons such as PF and BAZ are in play, snippets are available with information for them. As with vehicles/ordnance, they are date-aware and update themselves accordingly.

Analyzing a VASL scenario

If you have already set up the VASL scenario, you can choose "Analyze VASL scenario" from the menu, and the program will scan the .vsav file for vehicles and ordnance, and automatically create entries for each one. Only counters from the two configured nationalities will be imported, so make sure you set these first.

Extra templates

Extra templates are also available to generate other kinds of snippets e.g. to keep track of how many PF shots you have left, or to generate a shaded box that can be inserted behind the Turn Track to indicate an LV Hindrance.

Including your own images

You can also include your own images in scenarios e.g. the picture from the scenario card, or CG reinforcement tables.

In the Server Settings dialog, configure the directory where you keep your files, then in a template, use {{USER_FILES}} at the start of an image URL e.g.

<img src="{{USER_FILES}}/hill-621.png">
You can add a scaling parameter to resize the image (as a percentage of the original) e.g.
<img src="{{USER_FILES}}/hill-621.png?scaling=50">
or a width and/or height parameter to explicitly set the image size (in pixels).
If you use this feature in your scenarios, the images won't be available if you share the VASL scenario with someone else (since the files are only on your computer). However, if you upload them to a web server on the internet, you can configure the "User files" directory as a URL, and any image URL's that use {{USER_FILES}} will now get them from there.
VASSAL caches images (which can't be turned off), so if you're making changes that don't seem to be having any effect, try restarting VASSAL.

Suggested workflow

  • Set up the VASL scenario, with the boards and counters.
  • In VASL Templates, set the two player nationalities, then analyze the VASL scenario, to automatically create entries for vehicles and ordnance.
  • Enter the other scenario details e.g. the scenario name and date, Victory Conditions and SSR's, setup instructions.
  • Update the VASL scenario file, to automatically create labels for all the scenario details and vehicles/ordnance.

Configuring the program

Showing VASL counter images in the UI

If you want VASL counter images to appear in the UI, you need to tell the program where to find the VASL module (i.e. the vasl-X.X.X.vmod file you load into VASSAL):

  • If you are running the Windows desktop application, open the Server settings dialog from the File menu and configure it there.
  • If you are running the web server directly, create a file called site.cfg in the $/config/ directory and configure it there (there is an example file you can rename and edit).

Once you've configured the VASL module, if you want to also show VASL counter images in the OB snippets that you copy in the VASL scenario, turn this on in the User settings dialog from the main application menu.

Show Chapter H vehicle/ordnance notes as images

If you have set up the Chapter H vehicle/ordnance notes as HTML, it may not be possible to get the layout you want, since VASSAL's HTML engine is very old and doesn't support many HTML/CSS features. To work around this, this option tells VASL Templates to render the HTML itself (using a modern browser) and send it as an image to VASSAL, which is slower but gives better results.

It is possible to include Chapter H notes in your VASL scenarios, but since this is copyrighted material, the data files are not included in releases, and you will need to set them up yourself.

Setting up the Chapter H data files

Unpack this ZIP file somewhere, and configure the location in the Server Settings dialog (or the CHAPTER_H_NOTES_DIR setting in site.cfg, if you are running from source).

The ZIP file contains placeholder files for the Chapter H vehicle/ordnance notes and multi-applicable notes, so all you have to do is update these files with the real content.

Multi-applicable notes are stored as HTML, so for example, for German Multi-Applicable Vehicle Note A, change the file german/vehicles/a.html as follows:

<p> MA and CMG (if so equipped) have AA capability - signified by "MA:AA" being printed on the counter.
Because Windows has case-insensitive filenames, the convention is that Multi-Applicable Note "A" is stored in a file called a.html, while Multi-Applicable Note "a" is stored in a_.html (with a trailing underscore).

The vehicle and ordnance notes themselves are stored as image files, so you need to scan your Chapter H pages, and crop each individual note. For example, an image for the German PSW 234/1 can be seen to the left. Right-click on it, download it, and save it on top of german/vehicles/74.png (because it's note #74).

It is also possible to store the vehicle/ordnance notes as HTML, and while it is significantly more work to set things up this way, it gives much better results. Using the placeholder files from the ZIP above, wherever there is a .png file, rename it to have a .html extension, and then put the HTML in there.

Note that the HTML engine used by VASSAL is ancient and doesn't support floating images, which is needed to format this content in the same way as the ASLRB. To work around this, an option is provided (in the User Settings) to show these vehicle/ordnance notes as images. If this is enabled, the vehicle/ordnance notes will be rendered by the VASL Templates program (using a modern browser), and sent to VASSAL as an image, which is slower but gives the expected layout. If you don't use images in your HTML, you can leave this option disabled, and the raw HTML will be inserted into the VASL scenario, where it will be displayed much more quickly by VASSAL.

Adding Chapter H notes to your VASL scenario

Restart the VASL Templates program, and add a PSW 234/1 to the German OB. You will see some changes in the UI (see screenshot).

In the bottom-right, there are new controls for generating an HTML snippet for the multi-applicable notes. Click on the Snippet button, create a label in a VASL scenario, and you see the multi-applicable notes for the vehicles in the OB (the program will only include those that are needed). This content was taken from the a.html file you set up earlier.

Each individual vehicle and ordnance can also now have its own snippet button. Click on the one for the PSW 234/1, transfer the snippet to your VASL scenario, and you will see the image for Note 74 you set up earlier.

Depending on how you scanned the Chapter H pages, the image may not be the right size, so you can set a scaling factor for these images in the Server Settings dialog. As a guide, I scanned my ASLRB at 300dpi, and a scaling factor of 40% produced images that fit in with the rest of the scenario. However, if you have a lot of these images, there will be a noticeable delay when loading the scenario in VASSAL (because the program has to resize all the images), so you will be better off shrinking the images yourself, then setting the scaling factor to 100, so that no resizing needs to be done.
VASSAL caches images (which can't be turned off), so if you're making changes that don't seem to be having any effect, try restarting VASSAL.

Creating a scenario reference sheet

If you Shift-click on the Snippet buttons, an image of the snippet will be copied to the clipboard, instead of the raw HTML snippet. You can then copy these into Microsoft Word (or any other editor that can accept images), and print it out, to get a reference sheet with all the Chapter H notes for a scenario. Very handy, even if you're not using VASL!

This feature requires a webdriver to be installed.

How template files work

The HTML snippets are generated from template files, which are simply text files that contain the HTML you want to insert into the VASL labels, but with placeholders for the scenario name, victory conditions, each player's OB, etc. The user enters these details into the program, and when they want to generate a snippet, all the placeholders are replaced in the template with the real values, thus producing an HTML snippet specific to that scenario.

The template files can be found in $/data/default-template-pack/ (where $ is where you've installed the program).

Placeholders and template conditionals

We'll take a look at the ssr.j2 file, which is used to generate snippets for the SSR's.

Open the file in a text editor (if you're on Windows, you will probably need to right-click on the file and choose Open with...), and you'll see something like this:

<html> <!-- vasl-templates:id {{SNIPPET_ID}} --> <head> <meta charset="utf-8"> <style> {{CSS:common}} ul#ssr { padding: 0 5px 0 13px ; } ul#ssr li { margin-top: 2px ; } </style> </head> <table style=" {%if SSR_WIDTH%} width: {{SSR_WIDTH}} ; {%endif%} "> <tr> <td style=" background: #f0f0f0 ; border-bottom: 1px solid #c0c0c0 ; padding: 2px 5px ; font-size: 105% ; font-weight: bold ; "> Scenario Special Rules <tr> <td> <ul id="ssr"> {%for ssr in SSR%} <li> {{ssr}} {%endfor%} </ul> </table> </html>

The template looks like normal HTML, but with some extra stuff. Things that look like {% ... %} are commands to the template processor. At the top of the file, we see this:

<table style=" {%if SSR_WIDTH%} width: {{SSR_WIDTH}} ; {%endif%} ">
This is saying if the user has specified SSR_WIDTH, then insert into the generated HTML snippet everything up to the next {%endif%}. In this case, that's the following:
width: {{SSR_WIDTH}} ;
Things that look like {{...}} are the actual values entered by the user into the UI, in this case, the SSR width.

So, if the user has specified a width of, say 300px, this is what will be inserted into the final HTML snippet:

<table style="width: 300px ;">
But if the user hasn't specified anything for this field, what's between the {%if ...%} and {%endif%} will be ignored, and we get this:
<table style="">

Looping over lists

There will often be multiple SSR's, and near the bottom of the file, we can see how these are handled:

<ul id="ssr"> {%for ssr in SSR%} <li> {{ssr}} {%endfor%} </ul>
This sets up an HTML list (<ul>) and repeats everything between the {%for ...%} and {%endfor%}, once for each entry in the SSR variable, which contains the SSR's entered by the user in the UI. Each time around, {{ssr}} will be updated to hold the next entry, which will be inserted into the generated HTML snippet as a <li> node.

If the user had entered the SSR's as shown in the screenshot, then we would get the following inserted into the generated HTML snippet:

<ul style="margin:0 0 0 10px;"> <li> This is an SSR. <li> This is <em>also</em> an SSR. <li> And one more. </ul>
Note that if they enter HTML into the SSR text, it will be inserted verbatim into the HTML snippet, thus allowing them to format the content.

Template packs

If you want to customize how the HTML snippets are generated, you could just edit the files directly, but the down-side of doing this is that if you install a new version of the program, you will lose your changes.

A better way is to create your own set of template files, ZIP them up and load it as a template pack.

If you're running the desktop application, you can specify the template pack to start with, so that you don't have to manually upload it each time i.e.

vasl-template.exe --template-pack my-template-pack.zip
You can specify a ZIP file, or the directory containing the files (probably easier).

When you're writing a new template file, it would be painful to have to ZIP up and upload a new template pack every time you made a change, so you can edit templates directly within the program (see screenshot).

Changes you make are live i.e. they will take effect immediately, but note that there is no way to save your changes, so once you're happy with how the template is working, you need to copy it out and save it somewhere.

Setting up

After cloning the repo, install the developer requirements:

pip install --editable .[dev]
The tests use pytest and Selenium WebDriver, so you will need geckodriver and/or chromedriver somewhere in your PATH. The driver to use can be specified via the --webdriver parameter, and you can also run the tests headless e.g
pytest --webdriver chrome --headless

Note that since pylint is run as part of these tests, this should be done from the root directory of the repo.

Internet Explorer is also supported as a WebDriver, but due to differences in the way it works, some tests are currently failing for this.

Compiling the VASSAL shim

The program uses VASSAL to update VASL scenarios (.vsav files), and since this is written in Java, a helper program has been written in Java to do this.

To compile the program, go to the $/vassal-shim directory and type:

make all VASSAL_DIR=...
where VASSAL_DIR points to VASSAL's lib/ directory (the program needs Vengine.jar).

Since this program doesn't change very often, the resulting artifact (vassal-shim.jar) is checked into source control, so that it can be used without needing to install a JDK and compiling it first.

Code lint'ing

Python code is checked using pylint (installed during the pip install above), which should be run from the root directory of the repo.

Javascript is checked using jshint, run using Rhino, both of which need to be installed manually. Then, set the JSHINT_RHINO environment variable to point to the script that will run jshint using Rhino e.g.

export JSHINT_RHINO=~/bin/jshint-2.6.3/dist/jshint-rhino.js
Note that both of these are run as part of a normal pytest run.

Docker

The webapp can be run using Docker. To create an image, cd to the project root and build the image e.g.

docker build --tag vasl-templates .
To allow the test suite to be run against the container, add --build-arg ENABLE_TESTS=1 to the command.

Then run the container:

docker run --rm -it --name vasl-templates \ -p 5010:5010 \ -v /home/pacman-ghost/vasl/vasl-6.4.4.vmod:/data/vasl.vmod \ -v /home/pacman-ghost/vasl/extensions/:/data/vasl-extensions \ vasl-templates
The "Update VASL scenario" and "Analyze VASL scenario" features are currently not available in a container.

Note that if you have SElinux enabled, it may prevent the container from accessing files on the host, in which case access can be allowed like this:

chcon -Rt svirt_sandbox_file_t /home/pacman-ghost/vasl/

Creating a pre-compiled package

It is possible to compile the desktop application down to a single binary. This is typically done for the benefit of Windows users, but also works for other platforms. From the root directory of the repo:

python freeze.py --output c:\temp\vasl-templates.zip
The script will compile the program, then package it all up with the necessary support files into a single archive file.