Updated the documentation.

master
Pacman Ghost 2 months ago
parent c555614ac6
commit b285a044ab
  1. 2
      examples/README.md
  2. BIN
      vasl_templates/webapp/static/help/images/add-ssr.png
  3. BIN
      vasl_templates/webapp/static/help/images/add-ssr.small.png
  4. BIN
      vasl_templates/webapp/static/help/images/asa-search.png
  5. BIN
      vasl_templates/webapp/static/help/images/asa-search.small.png
  6. BIN
      vasl_templates/webapp/static/help/images/asa-upload.png
  7. BIN
      vasl_templates/webapp/static/help/images/asa-upload.small.png
  8. BIN
      vasl_templates/webapp/static/help/images/chapter-h/ui.png
  9. BIN
      vasl_templates/webapp/static/help/images/chapter-h/ui.small.png
  10. BIN
      vasl_templates/webapp/static/help/images/edit-template.png
  11. BIN
      vasl_templates/webapp/static/help/images/edit-template.small.png
  12. BIN
      vasl_templates/webapp/static/help/images/edit-vehicle.png
  13. BIN
      vasl_templates/webapp/static/help/images/edit-vehicle.small.png
  14. BIN
      vasl_templates/webapp/static/help/images/extras-templates.png
  15. BIN
      vasl_templates/webapp/static/help/images/extras-templates.small.png
  16. BIN
      vasl_templates/webapp/static/help/images/hill-621.png
  17. BIN
      vasl_templates/webapp/static/help/images/hill-621.small.png
  18. BIN
      vasl_templates/webapp/static/help/images/load-template-pack.png
  19. BIN
      vasl_templates/webapp/static/help/images/load-template-pack.small.png
  20. BIN
      vasl_templates/webapp/static/help/images/ob_setup.png
  21. BIN
      vasl_templates/webapp/static/help/images/ob_setup.small.png
  22. BIN
      vasl_templates/webapp/static/help/images/ob_vehicles.png
  23. BIN
      vasl_templates/webapp/static/help/images/ob_vehicles.small.png
  24. BIN
      vasl_templates/webapp/static/help/images/pf.png
  25. BIN
      vasl_templates/webapp/static/help/images/pf.small.png
  26. BIN
      vasl_templates/webapp/static/help/images/quick-start/load-scenario.png
  27. BIN
      vasl_templates/webapp/static/help/images/quick-start/load-scenario.small.png
  28. BIN
      vasl_templates/webapp/static/help/images/quick-start/settings.png
  29. BIN
      vasl_templates/webapp/static/help/images/quick-start/settings.small.png
  30. BIN
      vasl_templates/webapp/static/help/images/quick-start/update-scenario.png
  31. BIN
      vasl_templates/webapp/static/help/images/quick-start/update-scenario.small.png
  32. BIN
      vasl_templates/webapp/static/help/images/quick-start/updated-scenario.png
  33. BIN
      vasl_templates/webapp/static/help/images/quick-start/updated-scenario.small.png
  34. BIN
      vasl_templates/webapp/static/help/images/scenario-vasl.png
  35. BIN
      vasl_templates/webapp/static/help/images/scenario-vasl.small.png
  36. BIN
      vasl_templates/webapp/static/help/images/snippet.png
  37. BIN
      vasl_templates/webapp/static/help/images/ssr-template.png
  38. BIN
      vasl_templates/webapp/static/help/images/ssr-template.small.png
  39. BIN
      vasl_templates/webapp/static/help/images/ssr-template2.png
  40. BIN
      vasl_templates/webapp/static/help/images/ssr-template2.small.png
  41. BIN
      vasl_templates/webapp/static/help/images/ssr.png
  42. BIN
      vasl_templates/webapp/static/help/images/ssr.small.png
  43. BIN
      vasl_templates/webapp/static/help/images/user-file.png
  44. BIN
      vasl_templates/webapp/static/help/images/user-file.small.png
  45. BIN
      vasl_templates/webapp/static/help/images/user-settings.png
  46. BIN
      vasl_templates/webapp/static/help/images/user-settings.small.png
  47. BIN
      vasl_templates/webapp/static/help/images/vc-vasl.png
  48. BIN
      vasl_templates/webapp/static/help/images/vc-vasl.small.png
  49. BIN
      vasl_templates/webapp/static/help/images/vc.png
  50. BIN
      vasl_templates/webapp/static/help/images/vc.small.png
  51. 129
      vasl_templates/webapp/static/help/index.html
  52. 1
      vasl_templates/webapp/static/help/main.css
  53. 2
      vasl_templates/webapp/static/turn_track.js
  54. 4
      vasl_templates/webapp/vassal.py

@ -4,4 +4,4 @@ This directory contains examples of *VASL Templates* in action, with the `.json`
The online versions contain images that will be loaded from the internet, which looks much better, but there will be a short delay when you open the scenario in VASSAL as the images are downloaded.
These scenarios were taken from Multi-Man Publishing's [*ASL Classic* scenario pack](http://www.multimanpublishing.com/Support/ASLASLSK/ASLOfficialDownloads/tabid/109/Default.aspx).
These scenarios were taken from Multi-Man Publishing's [*ASL Classic* scenario pack](https://mmpgamers.com/asl-downloads-ezp-3#scenarios).

Binary file not shown.

Before

Width:  |  Height:  |  Size: 49 KiB

After

Width:  |  Height:  |  Size: 68 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 27 KiB

After

Width:  |  Height:  |  Size: 44 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 186 KiB

After

Width:  |  Height:  |  Size: 169 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 59 KiB

After

Width:  |  Height:  |  Size: 46 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 239 KiB

After

Width:  |  Height:  |  Size: 499 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 112 KiB

After

Width:  |  Height:  |  Size: 147 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 26 KiB

After

Width:  |  Height:  |  Size: 22 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 17 KiB

After

Width:  |  Height:  |  Size: 16 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 74 KiB

After

Width:  |  Height:  |  Size: 74 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 45 KiB

After

Width:  |  Height:  |  Size: 55 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 27 KiB

After

Width:  |  Height:  |  Size: 26 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 13 KiB

After

Width:  |  Height:  |  Size: 13 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 76 KiB

After

Width:  |  Height:  |  Size: 82 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 32 KiB

After

Width:  |  Height:  |  Size: 54 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 1.8 MiB

After

Width:  |  Height:  |  Size: 2.3 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 353 KiB

After

Width:  |  Height:  |  Size: 474 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 33 KiB

After

Width:  |  Height:  |  Size: 30 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 20 KiB

After

Width:  |  Height:  |  Size: 20 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 189 KiB

After

Width:  |  Height:  |  Size: 188 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 87 KiB

After

Width:  |  Height:  |  Size: 89 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 222 KiB

After

Width:  |  Height:  |  Size: 255 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 67 KiB

After

Width:  |  Height:  |  Size: 76 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 82 KiB

After

Width:  |  Height:  |  Size: 110 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 34 KiB

After

Width:  |  Height:  |  Size: 48 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 151 KiB

After

Width:  |  Height:  |  Size: 145 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 48 KiB

After

Width:  |  Height:  |  Size: 47 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 42 KiB

After

Width:  |  Height:  |  Size: 40 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 28 KiB

After

Width:  |  Height:  |  Size: 25 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 47 KiB

After

Width:  |  Height:  |  Size: 43 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 44 KiB

After

Width:  |  Height:  |  Size: 24 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 1.0 MiB

After

Width:  |  Height:  |  Size: 1.1 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 128 KiB

After

Width:  |  Height:  |  Size: 135 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 353 KiB

After

Width:  |  Height:  |  Size: 177 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 67 KiB

After

Width:  |  Height:  |  Size: 83 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.8 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 73 KiB

After

Width:  |  Height:  |  Size: 79 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 42 KiB

After

Width:  |  Height:  |  Size: 40 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 35 KiB

After

Width:  |  Height:  |  Size: 43 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 19 KiB

After

Width:  |  Height:  |  Size: 21 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 170 KiB

After

Width:  |  Height:  |  Size: 162 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 78 KiB

After

Width:  |  Height:  |  Size: 73 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 91 KiB

After

Width:  |  Height:  |  Size: 139 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 39 KiB

After

Width:  |  Height:  |  Size: 36 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 30 KiB

After

Width:  |  Height:  |  Size: 32 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 53 KiB

After

Width:  |  Height:  |  Size: 45 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 8.6 KiB

After

Width:  |  Height:  |  Size: 4.4 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 3.1 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 78 KiB

After

Width:  |  Height:  |  Size: 78 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 36 KiB

After

Width:  |  Height:  |  Size: 52 KiB

@ -43,7 +43,7 @@
<h2 style="margin-top:0;"> Running on Windows </h2>
<p> If you're using Windows, you should get the pre-built version from <a href="https://github.com/pacman-ghost/vasl-templates/releases">Github</a>, unpack it somewhere, then run <tt>vasl-templates.exe</tt>. Note that it can be a bit slow to start, so please give it a few seconds.
<p> If the program won't start because a DLL is missing from your computer, install the <a href="https://www.microsoft.com/en-in/download/details.aspx?id=48145">VC2015 runtime</a> (get the 32-bit version, <tt>vc_redist.x86.exe</tt>, even if you are running 64-bit Windows).
<p> If the program won't start because a DLL is missing from your computer, install the <a href="https://www.microsoft.com/en-in/download/details.aspx?id=48145">VC2015 runtime</a> (get the 32-bit version, <tt>vc_redist.<u>x86</u>.exe</tt>, even if you are running 64-bit Windows).
<p> If you don't see anything in the main window, check the notes below about configuring OpenGL.
<a name="run-docker"></a>
@ -73,14 +73,14 @@ If you have Docker installed, the webapp can be run in a container e.g.
<p> You can also run the program directly from the source code. Get a copy from <a href="https://github.com/pacman-ghost/vasl-templates">Github</a> in the usual way, by <tt>git clone</tt>'ing it, or downloading a ZIP and unpacking it somewhere.
<p> The web server was written and tested using Python 3.8.7, but it doesn't do anything particularly funky, so any recent version of Python <em>should</em> work.
<p> The web server was written and tested using Python 3.10.4, but it doesn't do anything particularly funky, so any recent version of Python <em>should</em> work.
<p> While not essential, it is <em>strongly</em> recommended that you set up a <a href="https://virtualenv.pypa.io/en/stable/">virtual environment</a> first. Then, install the requirements:
<p> While not essential, it is <em>strongly</em> recommended that you set up a <a href="https://virtualenv.pypa.io/en/stable/">virtual environment</a> first. Then <tt>cd</tt> into the project's root directory, and install the requirements (note the trailing period):
<div class="code">
pip install .[gui]
pip install --editable .
</div>
<h4> Running the web server </h4>
<h3> Running the web server </h3>
<p> The simplest option is to run the web server:
<div class="code">
@ -88,11 +88,14 @@ python vasl_templates/webapp/run_server.py
</div>
and then connect to it in a browser at <tt>http://localhost:5010</tt>.
<h4> Running the desktop application </h4>
<h3> Running the desktop application </h3>
<p> If you want to run the desktop application, you will need to have the Qt runtime installed.
<p> If you want to run the desktop application, you must install the GUI dependencies:
<div class="code">
pip install --editable .[gui]
</div>
<p> If you're on Linux, you <em>may</em> need to install Qt 5.15.4. On Fedora 35, running the "gui" install above should install everything you need.
<p> You will also need to have the Qt 5.15.4 runtime installed. If you're on Linux, you <em>may</em> need to manually install this.
<p> If you're on Windows, the Qt runtime will have been installed as part of PyQt5 (when you did the <tt>pip install</tt> above), but if you're in a virtual environment and you're getting <em>"DLL load failed"</em> errors, this is due to a problem with the way Python sets up the virtualenv. In the virtualenv's <tt>scripts/</tt> sub-directory, there should be <em>two</em> Python DLL's, so if you're missing <tt>python3.dll</tt>, copy it over from the Python installation the virtualenv was created from, and you should be good to go.
@ -101,10 +104,11 @@ and then connect to it in a browser at <tt>http://localhost:5010</tt>.
<a name="install-webdriver"></a>
<h2>Installing a webdriver</h2>
<p> <div style="float:right;width:40%;margin-left:1em;">
<div class="warning"> The webdriver is tightly coupled with the browser, so make sure that the webdriver you use supports the version of the browser you have. </div>
<div class="info" style="margin-top:0.5em;"> Since browsers usually automatically update themselves as new versions are released, this means that the webdriver you use will eventually become out-of-date, and may stop working. In this case, simply get a new version of the webdriver that supports the version of the browser you have. </div>
</div>
<p> <div style="float:right;width:40%;margin-left:1em;"> <div class="warning">
The webdriver is tightly coupled with the browser, so make sure that the webdriver you use supports the version of the browser you have.
<p> You must also make sure to get the correct type (32- or 64-bit) for your browser (check the About box).
<p> Since browsers usually automatically update themselves as new versions are released, this means that the webdriver you use will eventually become out-of-date, and may stop working. In this case, simply get a new version of the webdriver that supports the version of the browser you have.
</div> </div>
Some features require a <em>webdriver</em> to be installed. You can use either:
<ul>
<li> <a href="https://github.com/mozilla/geckodriver/releases"><tt>geckodriver</tt></a> (requires Firefox to be installed)
@ -150,18 +154,18 @@ Configuring the program
<p> Choose <em>Settings</em> from the <em>File</em> menu and configure the highlighted settings. As a guide, here are some example settings:
<table class="settings">
<tr> <td class="key"> VASSAL installation: </td> <td class="val"> <nobr>C:\Program Files\VASSAL-3.6.6\</nobr>
<tr> <td class="key"> VASL module: </td> <td class="val"> <nobr>C:\bin\vasl\vasl-6.6.4.vmod</nobr>
<tr> <td class="key"> VASL extensions: </td> <td class="val"> <nobr>C:\bin\vasl\extensions\</nobr>
<tr> <td class="key"> VASL boards: </td> <td class="val"> <nobr>C:\bin\vasl\boards\</nobr>
<tr> <td class="key"> VASSAL&nbsp;installation: </td> <td class="val"> <nobr>C:\Program Files\VASSAL-3.6.6\</nobr>
<tr> <td class="key"> VASL&nbsp;module: </td> <td class="val"> <nobr>C:\bin\vasl\vasl-6.6.4.vmod</nobr>
<tr> <td class="key"> VASL&nbsp;extensions: </td> <td class="val"> <nobr>C:\bin\vasl\extensions\</nobr>
<tr> <td class="key"> VASL&nbsp;boards: </td> <td class="val"> <nobr>C:\bin\vasl\boards\</nobr>
<tr> <td class="key" valign="top"> Java: </td> <td class="val"> <nobr>C:\Program Files\VASSAL-3.6.6\jre\bin\java.exe</nobr>
<div class="hint" style="margin:0.5em 1em;"> Leave this field blank to use the Java that comes with VASSAL (Windows only), or on your PATH. </div>
<tr> <td class="key"> Web driver: </td> <td class="val"> <nobr>C:\bin\geckodriver.exe</nobr>
<tr> <td class="key"> Web&nbsp;driver: </td> <td class="val"> <nobr>C:\bin\geckodriver.exe</nobr>
</table>
For the webdriver, download and unpack one of the following:
<ul>
<li> <a href="https://github.com/mozilla/geckodriver/releases">geckodriver</a> (you must have Firefox installed)
<div class="note"> Make sure to download the correct version (32- or 64-bit) for your browser (check the About box). </div>
<div class="note"> Make sure to get the correct version and type (32- or 64-bit) for your browser (check the About box). </div>
<li> <a href="http://chromedriver.chromium.org/downloads">chromedriver</a> (you must have Chrome installed)
<div class="note"> Make sure to download the version that corresponds to the version of Chrome you are running. </div>
</ul>
@ -170,12 +174,12 @@ For the webdriver, download and unpack one of the following:
<h2> Setting up a scenario </h2>
<p> <img src="images/quick-start/scenario-card.png" class="preview" style="float:right;">
We'll set up <em>The Streets Of Stalingrad</em>, and the scenario card tells us that this is played on Board 1, so fire up VASL, add this board, then save the scenario somewhere (e.g. <tt>streets-of-stalingrad.vsav</tt>).
As an example, we'll set up <em>The Streets Of Stalingrad</em>. The scenario card tells us that this is played on Board 1, so fire up VASL, add this board, then save the scenario somewhere (e.g. <tt>streets-of-stalingrad.vsav</tt>).
<br clear=all>
<br>
<p> <img src="images/quick-start/load-scenario.png" class="preview" style="float:left;">
In <em>VASL Templates</em>, open the save file for this scenario (<tt>The Streets Of Stalingrad (Scenario C).json</tt>; you'll find it in the <tt>examples/</tt> directory).
In <em>VASL Templates</em>, open the save file for this scenario (<tt>The Streets Of Stalingrad (Scenario C).json</tt>) in the <tt>examples/</tt> directory.
<p> Browse through the tabs, and you'll see all the scenario details e.g. Victory Conditions, SSR's, setup instructions.
<p> Click on the info icon in the top-right corner of the <em>Scenario</em> panel to get more detailed information about the scenario.
<div class="info" style="float:right;margin-top:1em;"> This information is provided by the <a href="https://aslscenarioarchive.com">ASL Scenario Archive</a>. </div>
@ -183,7 +187,7 @@ In <em>VASL Templates</em>, open the save file for this scenario (<tt>The Street
<br>
<p> <img src="images/quick-start/update-scenario.png" class="preview" style="float:right;">
We now want to create labels in the VASL scenario for all this information. Choose <em>Update VASL scenario</em> from the menu, and select the VASL scenario file you created earlier (e.g. <tt>streets-of-stalingrad.vsav</tt>). The program will now launch VASSAL to do the work, so be patient since it may take a minute or two, and you may see VASSAL momentarily appear on-screen.
We now want to create labels in the VASL scenario for all this information. Choose <em>Update VASL scenario</em> from the menu, and select the VASL scenario file you created earlier (e.g. <tt>streets-of-stalingrad.vsav</tt>). The program will now launch VASSAL to do the work - be patient, since it may take a minute or two, and you may see VASSAL momentarily appear on-screen.
<p> Once it's done, save the updated <tt>.vsav</tt> file somewhere. Go back to VASSAL, open the updated <tt>.vsav</tt> file, and you will see all the labels with the scenario information: <br>
<img src="images/quick-start/updated-scenario.png" class="preview" style="margin:0.5em 0 0 2em;"> <br>
In particular, note the data tables for the vehicles, which contain useful information that you can refer to during your game.
@ -204,18 +208,18 @@ In particular, note the data tables for the vehicles, which contain useful infor
<h2> Adding the scenario details </h2>
<p> <img src="images/asa-search.png" class="preview" style="width:30em;float:left;">
We start by entering the basic scenario details, such as its name, location and date. The easiest way to do this is by searching the <a href="https://aslscenarioarchive.com">ASL Scenario Archive</a>.
We start by entering the basic scenario details, such as its name, location and date. The easiest way to do this is by finding the scenario in the <a href="https://aslscenarioarchive.com">ASL Scenario Archive</a> and loading the information from there.
<p> Click on the search button, enter the name of the scenario, and once you've found the correct one, click on <em>Import</em> to transfer the details into <em>VASL Templates</em>.
<p> If the <em>Downloads</em> button is enabled, this means that somebody has contributed the entire scenario setup and/or VASL save file, and these are available for download.
<div class="info" style="float:right;width:40%;margin:1em 0;"> The scenario card may list special rules and errata, and have screenshots of the map setup, all of which will help you set up your scenario correctly. </div>
<br clear="all">
<p> <img src="images/draggable-overlays.png" class="preview" style="width:20em;float:right;">
Once the scenario details are in, click on one of the <em>Snippet</em> buttons, and the program will generate an HTML snippet and put it into your clipboard, which you can then copy into a VASL label.
Once the scenario details are in, click on one of the <em>Snippet</em> buttons (<img src="images/snippet.png" style="height:1em;margin-bottom:-3px;">), and the program will generate an HTML snippet and put it into your clipboard, which you can then copy into a VASL label.
<p> To create a label in VASL, open the <em>Draggable Overlays</em> window, and drag a label onto the main window.
<div class="warning" style="width:40%;margin:1em;"> Make sure to use the <em>"Label (no background)"</em> label, as indicated in the screenshot, since the others may not work properly! </div>
<p> 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.
<p> 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.
<p> 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.
<br clear="all">
<p> <img src="images/scenario-vasl.png" class="preview" style="width:20em;float:left;">
@ -224,7 +228,7 @@ Once you have a label in VASL, copy the HTML snippet generated above into it.
<br><br>
<h4 style="clear:none;"> Automatically adding labels to the VASL scenario </h4>
<h3 style="clear:none;"> Automatically adding labels to the VASL scenario </h3>
<p>Once you've got the hang of adding labels to your VASL scenario, you can get <em>VASL Templates</em> to do it automatically for you. After entering all the scenario details, choose <em>Update VASL scenario</em> from the menu, select the <tt>.vsav</tt> file you want to update, and all the labels will be inserted into the scenario (or updated, if they're already there).
<div class="info" style="width:50%;margin:1em;"> 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. </div>
@ -234,10 +238,10 @@ Once you have a label in VASL, copy the HTML snippet generated above into it.
<h2> Adding victory conditions and SSR's </h2>
<p> <img src="images/vc.png" class="preview" style="width:20em;float:left;">
Adding the scenario's victory conditions is straight-forward. We're generating <em>HTML</em> snippets, so we can type in things like <tt>&amp;ge;</tt> to get <tt>&ge;</tt> in the VASL label.
<img src="images/vc-vasl.png" class="preview" style="display:block;width:15em;margin:0.5em 0 0 2em;">
<p> &nbsp;
<p> 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 <tt>&lt;br&gt;</tt> tags where you want line-breaks.
Adding the scenario's victory conditions is straight-forward. The content is HTML, but the WYSIWYG editor lets you format things without having to worry about that, or you can click on the angled brackets icon to edit the raw HTML.
<p> The content in the screenshot on the left will produce a snippet that looks this:
<img src="images/vc-vasl.png" style="display:block;padding:0.25em 0 1em 1em;">
<p> 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 <tt>&lt;br&gt;</tt> tags where you want line-breaks (or press Shift-Enter, if you're in WYSIWYG mode).
<br clear="all">
<p> <img src="images/add-ssr.png" class="preview" style="width:15em;float:right;">
@ -253,32 +257,34 @@ Once they're all in, click on the <em>Snippet</em> button to get a nicely format
<h2> Adding each player's OB </h2>
<p> <img src="images/ob_vehicles.png" class="preview" style="width:20em;float:right;">
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.
<p> The scenario date is taken into account when generating these tables e.g. APCR for the Pz IVH is A5<sup>2</sup>, 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.
Adding the vehicles 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.
<p> The scenario date is taken into account when generating these tables e.g. APCR for the Pz IVH is A5<sup>2</sup>4<sup>3</sup>3<sup>4</sup>, but since the program knows the scenario is set in 1944, it just shows A3. Had the scenario been set in 1941, it wouldn't be shown at all.
<div class="info" style="width:40%;margin:1em;"> It's also possible to include Chapter H notes in your scenarios, although you will need to <a href="#" onclick="select_tab('chapterh');">set some things up</a> first. </div>
<p> <img src="images/edit-vehicle.png" class="preview" style="width:15em;float:left;">
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.
Double-click on an entry to edit it e.g. because an SSR changes its capabilities, or you'd like to add a note.
<br clear="all">
<p> <img src="images/ob_setup.png" class="preview" style="width:15em;float:left;">
We can also add ad-hoc notes describing where and how units should setup.
<p> Click on the icon in each note to generate its snippet, or Shift-click on it.
<p> Click on the icon in each note to generate its snippet, or Shift-Click on it.
<br clear="all">
<p> <img src="images/pf.png" class="preview" style="width:15em;float:right;">
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.
<br clear="all">
<h4> Analyzing a VASL scenario </h4>
<h3> Analyzing a VASL scenario </h3>
<p> If you have already set up the VASL scenario, you can choose <em>Analyze VASL scenario</em> from the menu, and the program will scan the <tt>.vsav</tt> 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.
<p> If you have already set up the VASL scenario, you can choose <em>Analyze VASL scenario</em> from the menu, and the program will scan the <tt>.vsav</tt> file for vehicles and ordnance, and automatically create entries for each one.
<div class="info" style="margin:1em;"> Only counters from the two configured nationalities will be imported, <br> so make sure you set these first. </div>
<a name="extras-templates"></a>
<h2> Extra templates </h2>
<p> <img src="images/extras-templates.png" class="preview" style="width:15em;float:right;">
<p> 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.
<p> 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 boxes that you can use to hold off-board counters.
<a name="user-images"></a>
<h2> Including your own images </h2>
@ -307,9 +313,9 @@ or a <tt>width</tt> and/or <tt>height</tt> parameter to explicitly set the image
<p> <ul>
<li> Set up the VASL scenario, with the boards and counters.
<li> In <em>VASL Templates</em>, search the ASL Scenario Archive, and use it to get your scenario configuration started.
<li> In <em>VASL Templates</em>, find the scenario in the ASL Scenario Archive, and use it to get your scenario configuration started.
<li> Enter the other scenario details e.g. Victory Conditions, SSR's and setup instructions.
<li> Analyze the VASL scenario, to automatically create entries for vehicles and ordnance.
<li> Analyze your VASL scenario, to automatically create entries for vehicles and ordnance.
<li> Update the VASL scenario, to automatically create labels for all the scenario details and vehicles/ordnance.
</ul>
@ -324,10 +330,10 @@ When the scenario has been completed and checked, you can contribute it back to
<p> <img src="images/lfa.png" class="preview" style="width:400px;float:right;">
As an added bonus, <em>VASL Templates</em> can also analyze VASL log files, to generate a report on how the game went. Choose <em>Analyze log files</em> from the menu, and add one or more VASL log files.
<p> You will be shown a report showing distribution graphs for the dice, and how the dice went over time. You can filter by the type of dice roll (e.g. only Morale Checks or To Kill rolls), as well as change the window size for moving averages. You can even download the data as a CSV, for further analysis!
<p> You will be shown a report showing distribution graphs for the dice, and how the dice went over time. You can filter by the type of dice roll (e.g. only Morale Checks or To Kill rolls), as well as change the window size for moving averages. You can even download the data as a CSV, for further analysis.
<p> Click on the flaming dice to see how many 2's and 12's each player rolled, as well as Sniper Activations. <br>
<img src="images/lfa-2s-and-12s.png" class="preview" style="margin:0.5em 0 0 2em;width:200px;">
<p> And if there is more than one log file, you can also drill down into each individual session: <br>
<p> If there is more than one log file, you can also drill down into each individual session: <br>
<img src="images/lfa-files.png" class="preview" style="margin:0.5em 0 0 2em;width:200px;">
<p> <img src="images/lfa-hotness.png" class="preview" style="width:300px;float:right;">
The report also calculates <em>"hotness"</em>, which is a measure of how hot your dice were. The more low rolls you make, the higher your hotness score, while rolling high makes it go down.
@ -341,29 +347,30 @@ The report also calculates <em>"hotness"</em>, which is a measure of how hot you
<img src="images/user-settings.png" class="preview" style="width:300px;float:right;">
<h4 style="clear:none;"> VASL user name</h4>
<p> Configure your VASL user name here, to have it always shown first when analyzing VASL log files.
Configure your VASL user name here, to have it always shown first when analyzing VASL log files.
<h4 style="clear:none;"> HTML snippet font </h4>
<p> This setting lets you change the font, and its size, used in VASL labels.
This setting lets you change the font, and its size, used in VASL labels.
<h4 style="clear:none;"> Hide unavailable multi-applicable notes </h4>
<p> Turn this on to completely omit vehicle/ordnance multi-applicable notes that haven't been set up (instead of showing them as <em>"unavailable"</em>).
Turn this on to completely omit vehicle/ordnance multi-applicable notes that haven't been set up (instead of showing them as <em>"unavailable"</em>).
<h4 style="clear:none;"> Confirm settings before updating scenarios </h4>
<p> Turn this on to show the <em>User Settings</em> dialog before updating a VASL scenario. This is useful if you are often creating VASL setups with different settings, and gives you a chance to make sure they are correct.
Turn this on to show the <em>User Settings</em> dialog before updating a VASL scenario. This is useful if you are often creating VASL setups with different settings, and gives you a chance to make sure they are correct.
<br><br>
<h4> Images in scenarios </h4>
<p> Images cannot be stored in a VASL scenario file, so they must stored elsewhere, which means that VASL needs to be told where to get them from:
Images cannot be stored in a VASL scenario file, and so must be stored elsewhere. This means that VASL needs to be told where to get them from:
<ul style="font-size:90%;">
<li> <em>From this program</em>: the <em>VASL Templates</em> program must be running before you open the scenario in VASSAL. If you are playing with someone online, they must have the program running as well.
<li> <em>From the internet</em>: you must have a working internet connection when you open the scenario in VASSAL. There will be a short delay when opening the scenario, as VASSAL downloads the images.
</ul>
<p> VASSAL can be slow downloading images (which causes the main window to blank out and hang when opening scenarios), so options are provided to disable them.
<h4> Show Chapter H vehicle/ordnance notes as images </h4>
<p> If you have set up the <a href="#" onclick="select_tab('chapterh');">Chapter H vehicle/ordnance notes</a> 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 <em>VASL Templates</em> to render the HTML itself (using a modern browser) and send it as an image to VASSAL, which is slower but gives better results.
<p> To optimize this process, the generated images are cached, and if you want to keep these cached images between sessions, configure <tt>VO_NOTES_IMAGE_CACHE_DIR </tt> in your <tt>site.cfg</tt> file. To pre-load this cache with all the available images, open <tt>http://localhost:5010/load-vo-notes-image-cache</tt> in a browser.
If you have set up the <a href="#" onclick="select_tab('chapterh');">Chapter H vehicle/ordnance notes</a> 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 <em>VASL Templates</em> to render the HTML itself (using a modern browser) and send it as an image to VASSAL, which is slower but gives better results.
<p> To optimize this process, the generated images are cached. If you want to pre-load this cache with all the available images, open <tt>http://localhost:5010/load-vo-notes-image-cache</tt> in a browser.
</div>
@ -371,7 +378,7 @@ The report also calculates <em>"hotness"</em>, which is a measure of how hot you
<div id="helptabs-chapterh">
<p> 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.
<p> <em>VASL Templates</em> can be configured 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.
<a name="setup-chapter-h"></a>
<h2> Setting up the Chapter H data files </h2>
@ -386,11 +393,11 @@ The report also calculates <em>"hotness"</em>, which is a measure of how hot you
</div>
<div class="info" style="width:60%;margin:1em 0;"> Because Windows has case-insensitive filenames, the convention is that Multi-Applicable Note "A" is stored in a file called <tt>a.html</tt>, while Multi-Applicable Note "a" is stored in <tt>a_.html</tt> (with a trailing underscore). </div>
<p> <img src="images/chapter-h/psw-234.1-note74.png" style="float:left;" class="preview"> 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 <tt>german/vehicles/74.png</tt> (because it's note #74).
<p> <img src="images/chapter-h/psw-234.1-note74.png" style="float:left;" class="preview"> 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 - download and save it on top of <tt>german/vehicles/74.png</tt> (because it's note #74).
<br clear="all">
<div class="hint" style="width:60%;margin:1em;"> 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 <tt>.png</tt> file, rename it to have a <tt>.html</tt> extension, and then put the HTML in there.
<p> 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 <em>VASL Templates</em> 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.
<p> Unfortunately, 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 <em>VASL Templates</em> 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.
</div>
<a name="add-chapter-h-labels"></a>
@ -408,13 +415,13 @@ The report also calculates <em>"hotness"</em>, which is a measure of how hot you
<p> <img src="images/chapter-h/notes-snippet.png" style="margin-left:2em;" class="preview">
<div class="hint" style="float:left;width:50%;margin:1em;"> 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. </div>
<div class="hint" style="float:left;width:35%;margin:1em;"> 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. </div>
<div class="warning" style="float:left;width:35%;margin:1em;"> 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. </div>
<a name="cheat-sheet"></a>
<h2> Creating a scenario reference sheet </h2>
<p> If you Shift-click on the Snippet buttons, an <em>image</em> 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!
<div class="info" style="margin:1em;"> This feature requires a <em>webdriver</em> to be installed. </div>
<p> If you Shift-Click on the Snippet buttons, an <em>image</em> 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!
<div class="info" style="margin:1em;"> This feature requires a <a href="#install-webdriver" onclick="select_tab('installation');"><em>webdriver</em></a> to be installed. </div>
</div>
@ -442,7 +449,7 @@ We'll take a look at the <tt>ssr.j2</tt> file, which is used to generate snippet
&lt;meta charset="utf-8"&gt;
&lt;style&gt;
{{CSS:common}}
ul#ssr { padding: 0 5px 0 13px ; }
ul#ssr { padding: 0 5px 0 15px ; }
ul#ssr li { margin-top: 2px ; }
&lt;/style&gt;
&lt;/head&gt;
@ -516,7 +523,7 @@ Note that if they enter HTML into the SSR text, it will be inserted verbatim int
<a name="template-packs"></a>
<h2> Template packs </h2>
<p> 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.
<p> If you want to customize how the HTML snippets are generated, you could just edit the template 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.
<p><img src="images/load-template-pack.png" class="preview" style="width:10em;float:right;">
A better way is to create your own set of template files, ZIP them up and load it as a <em>template pack</em>.
<p> 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.
@ -525,6 +532,8 @@ vasl-template.exe --template-pack my-template-pack.zip
</div>
You can specify a ZIP file, or the directory containing the files (probably easier).
<p> &nbsp;
<p> <img src="images/edit-template.png" class="preview" style="width:20em;float:left;">
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).
<p> 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.
@ -557,25 +566,25 @@ pytest --webdriver chrome --headless
<h2> Running the test suite</h2>
<p> The test suite communicates with the web server being tested using gRPC, which runs over a socket. To configure this port, rename the provided <tt>debug.cfg.example</tt> file to <tt>debug.cfg</tt>, and configure it there (or use -1 to have one automatically assigned.).
<p> You should also provide at least one installation of VASSAL, and at least one VASL <tt>.vmod</tt> file. If there are multiple installations of VASSAL and/or VASL, the tests will be run against each combination thereof.
<p> You should also provide at least one installation of VASSAL, and at least one VASL <tt>.vmod</tt> file. If there are multiple installations of either, the tests will be run against each combination thereof.
<a name="compile-vassal-shim"></a>
<h2> Compiling the VASSAL shim </h2>
<p> The program uses VASSAL to update VASL scenarios (<tt>.vsav</tt> files), and since this is written in Java, a helper program has been written in Java to do this.
<p> To compile the program, go to the <tt>$/vassal-shim</tt> directory and type:
<p> To compile the program, go to the <tt>$/vassal-shim</tt> directory and run the following command:
<div class="code">
make all VASSAL_DIR=...
</div>
where <tt>VASSAL_DIR</tt> points to VASSAL's <tt>lib/</tt> directory (the program needs <tt>Vengine.jar</tt>).
<p> Since this program doesn't change very often, the resulting artifact (<tt>vassal-shim.jar</tt>) is checked into source control, so that it can be used without needing to install a JDK and compiling it first.
where <tt>VASSAL_DIR</tt> points to VASSAL's <tt>lib/</tt> directory (because the program needs <tt>Vengine.jar</tt>).
<p> Since this program doesn't change very often, the resulting artifact (<tt>vassal-shim.jar</tt>) is checked into source control, so that it can be used directly, without needing to install a JDK and compiling it first.
<a name="code-linting"></a>
<h2> Code lint'ing </h2>
<p> Python code is checked using <a href="https://pylint.readthedocs.io/en/latest/"><tt>pylint</tt></a> (installed during the <tt>pip install</tt> above), which should be run from the root directory of the repo.
<p> Javascript is checked using <a href="http://jshint.com"><tt>jshint</tt></a>, run using <a href="https://www.mozilla.org/rhino">Rhino</a>, both of which need to be installed manually. Then, set the <tt>JSHINT_RHINO</tt> environment variable to point to the script that will run <tt>jshint</tt> using Rhino e.g.
<p> Javascript is checked using <a href="http://jshint.com"><tt>jshint</tt></a>, run using <a href="https://github.com/mozilla/rhino">Rhino</a>, both of which need to be installed manually. Set the <tt>JSHINT_RHINO</tt> environment variable to point to the script that will run <tt>jshint</tt> using Rhino e.g.
<div class="code">
export JSHINT_RHINO=~/bin/jshint-2.6.3/dist/jshint-rhino.js
</div>

@ -3,6 +3,7 @@ html { height: 100% ; }
body { height: 100% ; overflow: hidden ; }
h2 { margin-top: 1em ; clear: both ; color: #666 ; }
h3 { margin-top: 0.5em ; clear: both ; color: #666 ; }
h4 { margin-top: 0.5em ; clear: both ; color: #666 ; }
p { margin-top: 0.5em ; }

@ -142,6 +142,8 @@ function editTurnTrackSettings()
function onFlagClick( turnNo, playerNo ) {
// NOTE: This method gets called by a click handler in the snippet HTML.
// toggle the player turn reinforcements
// NOTE: Partisans have no flag, which makes it difficult for the user
// to configure reinforcements for them, but this is unlikely to happen :-/
if ( gTurnTrackReinforcements[playerNo][turnNo] )
delete gTurnTrackReinforcements[playerNo][turnNo] ;
else

@ -385,8 +385,6 @@ class VassalShim:
def update_scenario( self, vsav_fname, snippets_fname, output_fname, report_fname ):
"""Update a scenario file."""
# locate the boards
return self._run_vassal_shim(
"update", VassalShim.get_boards_dir(), vsav_fname, snippets_fname, output_fname, report_fname
)
@ -409,7 +407,7 @@ class VassalShim:
# NOTE: If VASSAL is taking a really long time to run (when it's loading the VASL module),
# check if any NIC's are enabled, but there isn't actually any internet access. I suspect
# that VASL is checking for something online, and taking a really long time to time-out.
# If there are no NIC's, then the attempt to connect fails immediately, but there are,
# If there are no NIC's, then the attempt to connect fails immediately, but if there are,
# the networking stack tries to find a route online.
# initialize

Loading…
Cancel
Save