Terrain Recording

Custom Terrain Recording

In this tutorial, we will add Terrain recording to the Battle for Moscow (BfM) module. BfM is am introductory war game with a simplified map.

Download and unzip the Java class files

Filename	Filetype	Size	Date	Compatibility
1.0
TerrainHexGrid_v10.zip	Custom Code	156 KB	unknown	3.2
1.1
TerrainHexGrid_v11.zip	Custom Code	161 KB	18-Oct-2021	3.5+

Version 1.1 contains several minor fixes and has been compiled against Vassal version 3.5.8 and is compatible with all 3.5 and 3.6 versions of Vassal.

After downloading and extracting the TerrainHexGrid.zip file, you should have three folders named src, terrain and qtree. The src folder contains all of the Java source code for this customisation for your reference. The terrain and qtree folders contain the Java class files that need to be added to your module.

Make a copy of your module

Make sure you have a copy of your module in a safe and secure place before starting!!!

Edit the buildfile to add new Command Encoder

Edit the buildfile (look for instructions elsewhere in the wiki).

Globally replace the string 'VASSAL.build.module.BasicCommandEncoder' with 'terrain.TerrainCommandEncoder'.

Add the terrain and qtree class folders to your module

Use a tool like 7zip to add the terrain and qtree folders to your module at the top level. Here is a shot of what it should look like when using 7Zip:

Don't worry abut the other folders. Your module probably only has the 'images' folder. If you look inside the 'terrain' folder, you should see .class files something like this:

Close 7zip. The custom code has now been added to your module.

Add Terrain Definitions

Next step is to define the different types of terrain that will be used in your module.

Edit your module using Vassal. Right-click on the Module component (at the top) and select Add Imported Class.

Type terrain.TerrainDefinitions into the Input box, click OK and save and re-load your module.

In the Module Editor, you should now see the following at the bottom:

Full Hex Terrain Definitions

Full Hex terrain fills the entire hex and there can only be one type assigned to each hex. This is typically used for the classic board game 'Terrains' such as Clear, Forest, Mountain etc. The Full Hex terrain in a hex is available to units via the {currentTerrain}/$currentTerrain$ pseudo- Global Variable. For BfM, we will define 3 types of Full Hex Terrain:

Clear terrain
Forest terrain
Defensive Zone Terrain

For each terrain type, right-click on the 'Full Hex Terrain Definitions' component and select 'Add Hex Terrain'. Give the terrain type a name a select a colour to represent the terrain when editing the Terrain map.

Leave the 'Blocking Terrain?' and 'Possible Blocking Terrain?' options unchecked, these can only be accessed using custom Java code.

Tag Definitions

Tag Definitions define attributes that will be visible to units in the hex as 'Global Properties'. Each hex can have any number of Tags attached to it. Each Tag can be true/false, a selection from a pre-defined list or free text. The value of the Tags are available to any units in the hex as a pseudo- Global Variable with the same name as the Tag terrain type. So the name of the Town in the current hex will be {Town}/$Town$ (using the tag names below).

For BfM, we will define four tag types:

Town - The value of the tag will be the town name.
City - The value of the tag will be the city name.
GermanSetup - The value of the tag will be true/false.
RussianSetup - The value of the tag will be true/false.

For each tag type, right-click on the 'Tag Definitions' component and select 'Add Tag Terrain' and give it a name and a colour. Select the Tag Type and a value to be returned from hexes that do not have this Tag defined.

Leave the Blocking Terrain options unticked, these can only be used by custom Java Code.

Hex Edge Terrain Definitions

NOTE: Hex Edge Terrain is only usable by custom Java code

Edge terrain defines a terrain feature that completely occupies a hex edge between two adjacent hexes. Only one type can be assigned to each edge. In BfM, you would define an Edge Terrain type of River.

Line Terrain Definitions

NOTE: Line Terrain is only usable by custom Java code

Line terrain defines a terrain feature that joins one hex center to the center of an adjacent hex. Only one type can be assigned to each hex pair. In BfM, you would define a Line terrain type of Railway.

Add a TerrainHexGrid to your map

Now that some terrain has been defined, we can add a Terrain Hex Grid to our map. Save your module and reload.

There are two ways to add a terrain Hex Grid:

Add a grid to a board by importing the TerrainHexGrid class.
Convert and existing Hex Grid to a Terrain Hex grid by editing the buildfile.

Importing TerrainHexGrid

Right-click on the Board component and select 'Add Imported Class'. Import class terrain.TerrainHexGrid

Converting an Existing Hex Grid by editing the buildfile

Edit the buildfile (look for instructions elsewhere in the wiki). Globally replace the string 'VASSAL.build.module.map.boardPicker.board.HexGrid' with 'terrain.TerrainHexGrid'.

Edit the Grid

The Hex Grid editor has been expanded with additional tabs to display and update each of the terrain types.

Set Grid geometry

The Grid tab allows you to change the Grid geometry, much the same as the standard Grid editor.

Edit Full Hex Terrain

The Hex tab allows you to allocate terrain types to hexes. Click and drag on the map to select hexes. Use Shift click/drag to add to an existing selection. Use Ctrl click/Drag to remove from an existing selection. Click on one of the Terrain buttons at the bottom to set the terrain type of all selected hexes.

Edit Tag Terrain

The Tag tab allows you to set the value of the tags in different hexes.

Follow this process:

Select a group of hexes that you want to have the same tag values.
Change the values in one or more of the tag items in the bottom box. All select hexes will get the tag values of the tag items you change.
Click on the big 'Save Changes' button, NOT THE SMALL 'Save' BUTTON which will save the whole grid.

The 'Select' buttons can be used to select all hexes on the map with tags of a certain value. Enter/select a tag value and click the adjacent Select button.