HexBattle Scenario Designer

Designed & Developed by Derek Hohls

Quick Start Guide - v1.2 (6 April 2009)



This guide assumes you have downloaded the HexBattle Scenario Designer program (CLICK HERE TO DOWNLOAD IT), have installed it successfully (under Windows XP), and are now wanting to use it to create a scenario.
It also assumes you know all the details of your scenario: the program does not - unfortunately! - design the scenario for you; it is merely an aid to help you store
the scenario details and easily create a more formal output for it; in graphical or text format.


Before You Start

In order to see the graphics displayed by this program, you will either need:

  1. Internet Explorer 5.5 (or higher), with the Adobe SVG Plugin installed; or
  2. FireFox 1.5 (or higher); or
  3. An SVG editor (for displaying maps only - see Quick Links)

Of the two browsers, Internet Explorer is more flexible with pure SVG displays (allowing zooming and resizing and copying of the graphic), and has no bugs when printing; but Firefox allows SVG graphics and normal text to be easily mixed together on a page (albeit with some printing bugs on fonts in early versions of the program). Try both to see what works best!

You must have the "Java Runtime Environment" (JRE) installed. Most modern Windows installations will already have it. You can test for a JRE by clicking on "Start" (the green button on your Windows taskbar) then "Run", then typing cmd in the box that appears, then clicking the "OK" button. A small window will appear. Type java.exe -version and press the "Enter" key. If you see some information displayed with version details, you already have a copy installed (otherwise see Quick Links if you need to get a copy). You can now close the window.


Quick Preview

Before you get going with your own scenario, you can get an idea of how the HexBattle Scenario Designer works, by using the menu File | Open to open the TestScenario.xml file from the "ancients" directory. Once the file is loaded, click on the Create View menu to see the output. If nothing appears, then you will need to read further...

The menu bar buttons provide quick access to the commonly-used program functions. As you mouse-over these, their function is displayed as a tooltip.


Quick steps to use the HexBattle Scenario Designer

The following steps assume you are creating a scenario for Command & Colors: Ancients. If you want another game type, you can click on the menu Tools | Options, then click on the "Program" tab. The steps for that game will be similar to the ones below, but the interface appearance and styling options may differ for that game. The game type that is active will appear in the status bar at the bottom of the main window.

Use the Tools | Validate menu to run a check that there is a minimum amount of information available, and that any obvious omissions are identified. Validation will not check for any duplicate or incorrectly overlapping units or terrain - combinations and permutations allowable in scenarios are too complex for automated checking in a flexible tool such as this. Caveat emptor!


Step 0: Start a New Scenario

Click on the File | New menu to clear any existing information from the program.



Step 1: Fill in your Scenario Details

You need to complete as much of the information as possible. Each item of information is captured in a specific place; either by typing it into a small edit box, or a larger text field, or as an item in a grid, or by making a choice from a drop-down list.

Each "section" of the scenario's details is accessed by clicking on the appropriate tab name.


Designer Tab

Here you complete as many of your personal details as possible. For the "ID" field, which must be filled in, it is suggested that you use your online "handle" e.g. your ConsimWorld, or BoardGameGeek login ID. Otherwise your name and surname written as one word will be fine. Hint: if you are going to creating many scenarios, use the Tools | Options "Designer" tab to fill in your details; these will be automatically added to this section when you create a new scenario.


Scenario Tab

This is the basic info about the scenario; the name of the battle and its date are the key fields to fill in here, as well as an ID (e.g. XB21).

NOTE: It is highly recommended that you use a numbering scheme that will fit into the one adopted by commandsandcolors.net/ancients, as this has the most comprehensive set of identified battles for Command & Colors: Ancients.

Other information to complete here is: the gameset in use (e.g. the basic game, or possibly an expansion); as well as flagging the "official" scenario checkbox, if this scenario is one created by the game publisher.

Note that many of the fields, e.g. "day" and "month", are optional; if you do not have the information simply leave the fields blank or with their defaults.


History Tab

You can, if you have the information to hand, add a brief description of the actual battle, to provide some historical context.


Victory Tab

Describe the winning condition for the battle. In a Command & Colors: Ancients scenario, this is typically defined by the number of banners.


Rules Tab

Describe any special rules applicable to this scenario e.g. setup or start conditions, or new rules applying to the units or terrain.


Terrain & Markers Tab

Here you will need to fill in a grid; one row of the grid corresponds to one terrain tile on the board.

Choose the location of the tile from the row/column drop-down lists. Some tiles have a facing, where a direction of "1" corresponds to the top point of a hex, or the top right-hand hexside, and other numbers are located in a clockwise direction. The terrain/marker type will usually be "terrain", though provision is made for other types of markers. The style is where the specific terrain tile is chosen from a list. If the terrain tile is a known location, e.g. a river or hill, a name can be recorded for it.

Use the toolbar above the grid to add or delete rows; or right-click on the grid for the pop-up menu.


Army "A" Tab

By convention, Army "A" is located on the lower edge of the board i.e. in the same place that "White" would be on a chess board.

On this tab, you will need to fill in the name of the Army leader, as well the name of their army. You will also need to specify which blockset is being used; the number of cards it starts with; whether or not it is the army that moves first; and how many banners it requires for victory.

You will also need to fill in the army grid; one row of the grid corresponds to one army unit on the board. Choose the location of the unit from the row/column drop-down lists. The unit type column is where the specific unit is chosen from a list. In the case of a leader, or even a special troop type, a name can be recorded for that unit. Depending on your output format, that name may be displayed on the map.

Use the toolbar above the grid to add or delete rows; or right-click on the grid for the pop-up menu.

Below the grid is a text field where instructions for the army can be filled in e.g. the number of command cards to be taken at setup, as well as any special rules for that army.


Army "B" Tab

This is filled in a similar way to Army "A".


Summary Tab

You do not enter any information here. This tab shows you a quick summary of the information you have already entered; and will highlight any unit miscount.



Step 2: Save your Scenario

Click on the File | Save menu option (or use Ctrl-S as a keyboard shortcut) to save your scenario information.



Step 3: Choose the Output Stylesheet

NOTE: This step can be skipped if you do not want to change the active (selected) stylesheet

The Tools | Options menu item will show the program options window. Here the program settings can be created or changed. The key area to work on here is the grid on the "Stylesheets" tab.

The program comes with a set of pre-defined stylesheets that are used to create a specific output view of the scenario. Click on the check box in the "Use?" column to select the one that will generate the type of view you want.

The various pre-created stylesheets for the Command & Colors: Ancients scenarios are:


  • Detail HTML: the scenario "written out" as an HTML page
  • Detail HTML for Ancients Dot Net : the scenario "written out" as an HTML page, for use on the commandsandcolors.net/ancients website, with a link to a map image
  • Plain Text: the scenario "written out" as an ASCII text page
  • XHTML with Color SVG Map: the scenario with an embedded SVG map, and descriptive HTML text, inside an XHTML page [requires Firefox 1.5 or higher, or similar browser, to view; for scenarios with a lot of text use the parameter layout=full]
  • Color SVG Map: a stand alone SVG map, without descriptive text [can be resized with a parameter of size=0.n, where n is a number from 0 to 9]
  • Color SVG Map for Ancients Dot Net : a stand alone SVG map, with some descriptive text and annotations, for use on the commandsandcolors.net/ancients website
  • XHTML with Color SVG Map for Ancients Dot Net: the scenario with an embedded SVG map, and descriptive HTML text, inside an XHTML page [requires Firefox 1.5 or higher, or similar browser, to view, for use on the commandsandcolors.net/ancients website
  • Color SVG and Summary: an alternative stand-alone SVG map, with as much descriptive text as can fit in a fixed-size right-hand column.

(Stylesheet names and parameter options will differ for other types of games.)

NOTE: Earlier versions of Firefox appear to render SVG text properly on screen, but have a fault when printing. Map text is therefore altered so it appears small on screen, but prints more-or-less normally. If you want to change this, add a parameter of print=false to the stylesheets whose output is SVG. It is highly recommended that you download and use Firefox version 3 (or higher) in order to avoid these problems.



Step 4: Generate the Scenario View

Select the Create View menu item to generate the output from the program; typically HTML, SVG, XHTML or even plain text, depending on the stylesheet selected in Step 3. The output will be shown by whatever program is associated, in your Windows setup, with the file extension chosen. For example, HTML (.htm) will be displayed in a web browser.

Before a scenario can be viewed, it must validate properly (see above).


Quick Questions

Q: How does this all work?
A: In short: your scenario is stored in an XML file; this is transformed via Saxon (an external program), using the XSLT stylesheet chosen, to give the desired output in text, HTML, XHTML, or SVG!

Q: What is SVG?
A: SVG stands for "Scalable Vector Graphics", an open standard for displaying graphics on (and off) the web. SVG is a form of XML, designed to be easily created and manipulated. You will keep hearing more of it...

Q: What is XHTML?
A: The updated version of HTML. More easily read/written by automated systems. Capable of display of advanced data types. Presently supported by advanced browsers such as Firefox or Opera.

Q: What is XML?
A: A means of storing hierarchical information in a well-structured manner. Typically used to store data in a way that is independent of how it is created or could be presented. Can be easily read by both people and machines.

Q: If I have problems using the program, who do I contact?
A: Derek - This email address is being protected from spambots. You need JavaScript enabled to view it.



Quick Links