Skip to content

Chapter F: Create Update Boards

Jump to bottom
Doug Rimmer edited this page Jul 22, 2025 · 1 revision

INTRODUCTION

This page describes the process for adding newly created (or updated) VASL boards to the VASL system, including the addition of LOSData to enable LOS checking. It includes all of the steps required to ensure that new boards can be accessed by the automatic board synchronization feature contained in VASL 6.4.x and higher. This page does not describe the process for creating new VASL map images using graphical tools. Instructions for doing so are found elsewhere.

AUTOMATIC BOARD SYNCING

The automatic board synchronization feature in VASL, introduced in version 6.3 uses the GitHub VASL board repository as the "source of truth" for the current version of the boards along with the board version document, located in the VASL code base, which maintains the active version of each board. These two vehicles need to be kept in sync when a board is created or updated. As of VASL6.4.3, an updated methodology for board synchronization was introduced, using an .xml metadata board version document.

For instructions on how to create a "bare-bones" board, suitable for playtesting or personal use, see the end of this document.

VASL BOARDS

VASL board files (or boardarchive files as they are often called) are .zip files with the extension .zip removed from the file name (for example, bd20 is bd20.zip without the .zip extension). As such, a VASL board file is a collection of other files, including the map graphic, all of which are required for the board to function properly in VASL. A VASL board must contain the following files:

  1. A .gif or .png file which is the actual graphical image of the map (for example, bd20.gif). The name of the graphic file should follow the pattern “bd” & yourboardname & “.gif/.png”.
  2. A file named boardmetadata.xml, which is an .xml file following a prescribed structure. See example at vasl-developers/vasl/dev documentation/BoardMetadata - sample.xml for details.
  3. A file named data which is a .txt file with the .txt extension removed from the name. It follows a prescribed structure: Version x.x. That is all that is required. Data is a legacy file used before the Boardmetadata.xml file was introduced but in some testing is still needed if using overlaySSR (which is pretty much every geo board). Comments, such as who created the board graphic or updated it can be added on a separate line and should be proceed by “//”.
  4. Three additional txt files, all without the .txt extension in their name, named “colors”, “colorSSR”, and “SSRControls”. These files are used to govern terrain transformations on the map when being used in VASL. They are all created during the map-making process, following the requirements set out for them. Colors defines the color palette used to enable colorSSR terrain changes. ColorSSR defines the rules which substitute one color for another when certain SSR terrain settings are applied (i.e. snow, mud). These 2 files (colors and colorSSR) are really only needed if the colors or rules need to be customized for a particular board since the most recent version of them is included in the VASL build, but they should be included in every bdXX file just to be safe and consistent). The SSRControls file is used to add specific terrain transformation items to the TerrainSSR dialog box in VASL. In addition, a VASL board may contain the following files:
  5. A number of additional .gif files representing overlay files specific to the board. The map-making process includes directions on creating and naming these files.
  6. A file named LOSData, which contains the LOS data used by VASL when performing LOS checks on the board. This file is created from an initial version of the VASL board file as described below.

CREATING OR UPDATING VASL BOARDS

Map elves create a VASL board file as the output of the map-making process. Having first created all of the mandatory and optional files required (with the exception of the LOSData file which is not created at this state), a number of steps are necessary to create the board file and add it to the VASL system:

  1. For new boards, assign a version number to the board in the boardmetadata.xml file. For board updates, change the version number (to enable auto-synching).
  2. Add all of the required files to a directory/folder in the VASL code repository at github.com/vasl-developers/vasl/develop/boards/src. The folder should follow the naming convention evident in the /src directory.
  3. Compile/build (the terms are interchangeable), the board file manually or by using BoardBuilder. See separate instructions on the Wiki for using Boardbuilder. To manually build the board file, zip all of the necessary files into a single file named bdBOARDNAME.zip and then remove the .zip extension.
  4. Place a copy of the VASL board file into the VASL board repository at github.com/vasl-developers/vasl/develop/boards/bdFiles.
  5. Update the board version document named “v5boardVersions.xml” located in the VASL code repository /boards directory on github.
  6. Step 3 must be completed before step 4 and the two should be done in close succession. In addition, map elves are asked to place the layered file (PSD/XCF) used in the map-making process into the VASL code repository /src/bdxx directory along with the other files as per step 1 above. This would include the matching layered file for each of the .gif/.png files in the board. These layered files should not be included in the boardarchive file produced in step 3 above. Updating an existing board involves the same steps, but first, map elves should clone a copy of the VASL code repository and the vasl board repository. They will use the code repository to obtain the necessary files from the /src directory. Using those files, map elves can make changes to the board. They should then use steps 1 to 5 above to update the board files in the VASL code repository and VASL board repository as appropriate.

ADDING LOSDATA TO A BOARD

Adding LOSData to a board begins with an already existing board file and involves the following steps, which are very similar to those in the preceding section with one major addition.

  1. Obtain a VASL board file from the VASL board repository at github.com/vasl-developers/vasl/develop/boards/bdFiles.
  2. Open the VASL board file using the LOS-GUI program that is part of the VASL code repository.
  3. Edit the LOSEditor.properties file in the VASL.LOS-GUI folder to set BoardDirectory to the local folder containing the VASL board file.
  4. The LOS-GUI program uses the boardmetadata.xml file and the map .gif/.png file contained in the VASL board file to automatically generate most of the LOS data required. Add any missing data or correct errors by using the LOS-GUI functionality.
  5. Save the board file from within the LOS-GUI program. At this step a LOSData file is created and automatically added to the VASL board file.
  6. Update the board version number in boardmetadata.xml.
  7. Add the LOSData file and the updated boardmetadata.xml file to the board folder in the VASL code repository in the at github.com/vasl-developers/vasl/develop/boards/src. This can be done via SourceTree in certain circumstances.
  8. Compile/build the board file by using BoardBuilder. See separate instructions on the Wiki for using Boardbuilder.
  9. Place a copy of the updated VASL board file into the VASL board repository at github.com/vasl-developers/vasl/develop/boards/bdFiles.
  10. Update the board version number in “v5boardVersions.xml” in the VASL code repository /boards directory on github.
  11. Step 7 must be completed before step 8 and the two should be done in close succession.

At this stage the process is complete. All of the source files are stored in the VASL code repository boards/src directory. The compiled VASL board file is in the VASL board repository /bdFiles directory. VASL 6.4.3 and higher will use this repository to automatically check for updates of the board and download them when VASL users select the board for use in a scenario.

CREATING A PLAYTEST BOARD

Sometimes it is useful to create a simple board with minimal effort to support playtesting. In these cases, all that is required is (1) the board image file and (2) the data file as described above. Zip those two together as described above and the board will work (without VASL los checking of course).

Clone this wiki locally