The General Staff Black Powder Map Editor

Contents

The General Staff Black Powder Map Editor (hence referred to as the Map Editor) allows you to create new battlefield maps for use with the General Staff Black Powder Wargaming System. In many ways the Map Editor is a traditional multi-layered paint program with similar functionality as popular paint programs like PhotoShop,

In the above schematic image we see that there are four possible layers in a General Staff battlefield map: Place Names & Victory Points (optional), Terrain, Elevation and Background Image (optional).

After a map is created and saved in the Map Editor it can be loaded into the General Staff Black Powder Scenario Editor and used to create new or historical battles that are then played in the General Staff Black Powder Wargame. It is important to remember that how your map looks when it is saved (with terrain and elevation opacity settings) is how it will appear in the game.

You will be drawing Terrain Objects (such as forests, lakes, roads, etc.) on your map. These objects can be individually deleted or merged with similar terrain objects.

You also have the ability to import digital scans of historical battlefield maps, add terrain and elevation data, and save the map for use with the General Staff Wargaming System.

The Map Editor creates two zip files when you 'save' or 'save as'. One is the design file which is used by only the map editor. The other zip file will be used by the scenario editor and game. What you're aiming to produce for the game is:

1) A jpg picture which is a visual representation of terrain allows the user to understand what is where. This image is exactly what the user sees at the moment the file is saved. It is a combination of the background, terrain and elevation layers each effected by the level of opacity set by the user. In other words, What You See Is What You Get. This is the image that will appear in the Scenario Editor and in the actual General Staff Wargame.

2) A list of Places with optional Victory Points. These are displayed visually to the user and contribute to the 'score' of any battle on that map. They usually represent strategically important locations. These are considered separately from all other terrain you draw and do not just become part of a background jpg.

3) A matrix (two dimensional array) of terrain types. Each cell corresponds to a display pixel and has a value for the underlying terrain on the battlefield. This is used by the computer to tell it where terrain effects apply such as a road allowing faster movement or a river which is incredibly slow to cross. Each cell only has one value. In case any terrain overlap, the order things are added matters and the last added terrain covering a cell "wins". Hence a road over a river defines a crossing place where your infantry will not drown.

4) A matrix (two dimensional array) of elevation. This is sometimes referred to as a 'height map'. Each pixel has a height in metres. On the real battlefield you cannot see through hills or woods. Hence the high ground advantage. The elevation matrix is used by the computer to know what height each cell is.

It is due to the last three points that you cannot just grab any old map or picture and meaningfully use that as the background. If you did then the computer would have no way of knowing what terrain is where. It'd be just a picture as far as the computer is concerned. In fact the picture is not used for any calculations by the apps.

The minimum memory and system requirements for the Map Editor is Windows 7 and 3 GB of memory. The Map Editor supports multi-threading and will take advantage of this when required to process multiple intensive tasks such as drawing rivers and calculating elevations. When this happens these icons (below) will appear:

When these icons appear in the upper right hand corner of the Map Editor window it indicates that processing is taking place in the background. Each icon represents a different thread.

Whilst everything kind of works on a machine that has just 2 cores, you would need to be very careful and draw slowly. It is recommended you use a machine with 4+ cores and preferably hyper threading.

If, when working on a minimum spec machine, drawing outlines (such as for a forest) become jerky or you get noticeable points rather than a smooth rounded outline it is an indication that you are pushing processor threading limitations.

The screen is divided into two areas: the Tool Pane on the left hand side of the screen and the Drawing Canvas which takes up most of the screen. Above these two sections are a standard Menu Bar. The grid lines and the Compass Rose are optional and can be toggled on/off from the Layers menu.

Drawing tools, tool options and map information is entered in the Tool Pane area on the left portion of the screen. Clicking on the left or right arrows on either side of the tab title will scroll to the previous / next tab (see above image).

You can select the DPI (Dots Per Inch) resolution that the map will be saved at from the list of 96 through 2400. The default of 96dpi will often be sufficient. Remember: the greater the DPI the larger the file size! You may wish to save the map at higher DPI resolution if you intend to print out the map (very handy for board gamers) or if you have a very high resolution monitor.

Your monitor would have to be very high resolution before you'd need even 300 dpi. 96dpi looks ok on a monitor 3440 x 1440.

The Drawing Options tab. From this tab you can select Area drawing (Forests, Lakes, Swamps, Mud, Field, City and Contours), Line drawing (Roads, Rivers, Fortifications, Boundaries, Bridges, and Fords) and Point options (Place names and buildings).

These are the tools that you will be using to draw on the Drawing Canvas portion of the screen. When you choose to work with one of the Area or Line tools on the... Drawing Options Tab your map cursor will change to a pen:
Note: You are drawing on the Terrain Layer.

Area Drawing Tools are tools for drawing filled in areas on the map like Forests, Lakes and Swamps. When you draw on the Drawing Canvas with an Area Drawing Tool your start and end points are automatically connected and the enclosed area is filled in with the selected terrain type.

If you are using a mouse to draw the start point is where you click down with the left mouse button. Hold the left mouse button down until you have arrived at your end point and then release the left mouse button. The start and end points are automatically connected.

If you are using a digitizing table and pen press down on the tablet with the pen at the start point, continue drawing with the pen until you reach the end point and then lift the pen off of the drawing tablet. The start and end points are automatically connected.

If you're using a stylus then the harder you press, the higher the pressure applied and the wider a line terrain will get. If you're instead using a mouse ( most users will probably only have a mouse ) the width is fixed to the value equivalent to 0.5 pressure. Pressure ranges from 0 to 1.

You can set the base width for each line terrain. You need a mouse or a stylus which has a scroll wheel (yes, some styli do). Position the cursor over the desired tool option (for example, River) you should see a tooltip appear like the picture below. Then use the mouse scroll wheel to increase or decrease the values. "As drawn" is 0.5 pressure and what you will get with a mouse. Max is the maximum width you will get with 1 pressure or at the end of a river you use the widening option on.

You can adjust the pressure sensitivity (min and max width) by hovering the cursor over the desired tool button and using the mouse scroll wheel to adjust the values higher or lower.

This will allow you to draw rivers that widen or decrease in width based solely on the amount you press down on the digital pen.

An example of using the Forest Drawing Tool. Note the quill pen indicates progress adding the trees as "children" of the forest. The process which adds the trees calculates how many to add based on area. It looks for a space to fit one by randomly picking a point and checking whether there's a tree there already. As trees are added there are less and less points "free" and finding each new space takes a bit longer. The size of the trees is reduced as you go but you will notice it can take quite some time for large complex forests.

This mechanism of adding "children" is used in other area tools ( waves for lakes ) except there are less children and they will usually run much faster.

Use the Contour Drawing Tool to draw elevation contours (above). Important: this tool does not add elevation to the map. That is done by processing your contours using the Greyscale tab, importing from Google, importing and processing a greyscale picture or drawing using the various shaper options. (see below)

You will see a representation of the current width for a line in a tooltip when you hover over one of the line categories. Each has a default width which may be changed.

You can adjust that width by scrolling the wheel up or down. At the risk of stating the obvious - this will decrease or increase the width.

Using a mouse, any line you draw will be the width labelled "As drawn". If you click one of the buttons available for river and narrow it from one end to the other then it will go from the maximum to none.

The convention with a stylus is that the harder you press the wider a line will get as you draw. That's how they work with all drawing packages. Our software follows this convention. Pressure internally is measured from zero to 1 and this is applied as a factor against the base width to give actual width of a line.

Hence with maximum pressure (of 1) you would get a line as wide as that Max.

It is pressure which is manipulated to narrow/broaden a river when you click the buttons. This will over-ride whichever pressure you applied to the stylus whilst drawing.

Most line types should really be constant width. The way most line terrains work, the pressure you start with will be applied to the entire line in order to avoid strangely wobbly roads or fences.

Rivers are an exception and will retain the pressure you apply at any point.

There are a number of modifications available for the River drawing Line Tool. These include:

Tapering the width of the river by selecting this option in the Edit Terrain tab:

Select the left chevron (<) to make the river increase in width from where you started drawing to the end. Select the right chevron (>)) to make the river decrease in width from where you started drawing to where you finished. Select the button (-) to make the river the same width along the entire length of the river. Click to enlarge.

When you click on the map with the Place tool the text 'Unknown' appears on the map.

Go to the Edit Terrain tab and change the text to desired label. You can also change the color of the text by clicking on the color boxes and selecting either White, Yellow or Black type.

An example of a Place label. This Place has no value and is simply used to add information about the map.

If you add a value to the Place in the Edit Tab you have created a Victory Point Area. In the example, Last Stand Hill is worth 50 Victory Points.

Victory Points can be either Yellow (not controlled by other side), or Red or Blue indicating which army last passed over this area. You can select Red, Blue or Yellow when on the Edit Terrain tab; select the Victory Point and select the color from the drop-down color box.

Once you have added at least one terrain then you will see it appear in the list on the Edit Terrain Tab.

You will have various options in the left pane for each terrain.

In the right, you can right click area terrains and choose one of three options.

Removing the children will remove the trees, redoing the children will remove and then re-fill with trees and setting the background transparent will remove the speckled fill.

The latter is particularly useful if you already have a background map which includes imagery you wish to retain. This could be a forest or city on a map out a history book or scan that you're using as background.

Whatever terrain is drawn last is on the top. For example, if you draw a river and then a forest over the river, it will look like this:

If you first draw a river and then draw a forest over the river it will look like this. Probably not want you wanted. Click to enlarge.

However, you can change the order in which terrain is drawn by selecting the desired terrain on the Edit Terrain tab and clicking either the (-) or (+) boxes. Minus will cause the terrain object to be drawn later. Plus will make the terrain object drawn sooner. For example:

This is the result of selecting River in the Edit Terrain tab and clicking on the (-) box. This has the effect of drawing the river on top of the forest. Click to enlarge.

When the Edit Terrain tab has been selected, position the cursor over the Compass Rose in the upper right hand corner of the map. Use the mouse scroll wheel to move the Compass Rose clockwise or counter-clockwise.

This tab uses data from Google Maps. In order to use this (optional) functionality you will need to create a Google Maps Platform account. The relationship for this service is of course between you and Google. The details are explained:

Although you register a credit card, the service is effectively free for normal usage since you get $200 "credit" each month. If you want to create many maps using this service then use Google's pages to check usage. Current costing is $5 per 1,000 calls. A map's worth of data is 579 calls.

You will be given a unique id which is necessary to call the service.

Once you have registered and have this long string of characters and numbers, create a txt file ( notepad ) called googlekey in:

%localappdata%/generalstaff

The reason this is a manual process external to GeneralStaff is to ensure you understand this is not part of our code you will be using.

Google's Elevation API is by far the most convenient source of real world elevation data but rather quirky. Presumably due to past abuses the service was sensitive to the high number of calls necessary for our purposes. Until recently it was taking two runs to obtain a full map's worth of data. If the download stops mid run, save your map and try again several hours later to obtain the rest. If you try immediately and the failure was because Google decided you were asking for too much data, it will always fail.

On the plus side the recent change to force credit card registration seems to have allowed them to remove or reduce the sensitivity of the usage checks.

You might think that Google's elevation api is a bit of a nuisance what with the registering and sensitivity.

Which it is.

So why on earth are we using it?

That's because it works reasonably predictably, offers effectively 100% coverage and is easy to use. The alternatives fail on most or all of these criteria. I could probably write something much more user friendly with no registration and zero cost. The problem is that would be a significant project of itself. Downloading, translating, securing and providing a convenient UI to provide elevation data would take substantial effort. The hosting would also necessitate passing charges on to you the user.

This uses either contours or an imported picture to work out elevations for each 1px cell of your map.

The contours are those you draw ( covered above ).

A picture can be any jpg or png picture which will be converted to 255 shades of grey internally. Although inadvisable, you could theoretically use a colour picture. Whichever picture you choose will be stretched to 1155 x 805 px.

For the most predictable and precise results it is therefore advisable to use a greyscale picture which is 1155 x 805.

The Flatten tool. Note that the elevation has been set to 25 meters (in the Set field at the top of the Elevation Shapers tab). Click to enlarge.

This sets an ellipse to a specific height.

You could conceivably create a raised cylinder by setting an ellipse to a higher elevation to the terrain around it or lower an area similarly but this is not the intended use. The idea is you use this to flatten anomalies of some sort out of your map.

You can size the ellipse before or after you drag it onto the map.

The brass sliders control height and width.

If you hover over the ellipse you can rotate it using the mouse wheel.

This is particularly useful if you've downloaded elevation data from google for an area and it has some modern village or feature which you want to remove. EG the "Lions mound" at Waterloo is a big cone shaped hill added after the battle so it wasn't there back in 1815.

The value in "Set" will be used as the elevation for the area covered by the ellipse.

You can overtype that or right click some point on the map you've already got elevation data for.

Once you have the height you want and the ellipse is in the right position, right click the ellipse and your new value is applied.

The Ridge tool. When you first create a ridge it will draw a dark red line and then calculate the ridge following the line using the defined settings. Click to enlarge.

This is a greyscale tool.

With this you draw a sort of a long hill or valley. Whilst very powerful, this tool is complicated and pretty tricky to get good results from. It is strongly recommended you use an experimental "scratch" map to explore how this works before using it for real.

Valleys are done using a negative value for Set. This will gouge an area out like you were cutting out of expanded polystyrene. Just like you'd need enough thickness in a sheet of polystyrene you should also ensure there's enough depth above zero in the map before you gouge anything out. This technique is very useful for creating river valleys.

Unpredictable results are likely if you cut a valley that ends up with negative elevation.

A natural ridge will taper and lower towards it's end.

You're using ink to draw this and pressure is used both to taper and reduce the height at the narrow end of a tapered ridge. If a skilled artist and use a stylus then this will be unexpected. For most users who just have a mouse then this is something you won't have to worry about.

You must set options before drawing but you can draw multiple ridges before clicking the apply button.

If you check the "Tapered" box then you get a narrowed lower end either at the start or end depending on whether you check the "From Start" box.

If you wanted a ridge tapered at both ends then draw two overlapping - from one end and then from the other. Then click apply.

The Proportion Tapered slider controls how much of the ridge is tapered none is with the slider to the left and all to the right.

Width is the width of the ridge.

Blur Depth increases of decreases the extent the whole set of ridges you draw is blurred and can be changed before or after you draw.

Black background allows you to easily just see what you're drawing but haven't committed using the Apply button.

The Undo arrow removes the last ridge you added. You can keep on clicking and removing until all you added but have not applied are removed.

You're likely to want to use this a lot when you're learning how ridges work.

Raise

This tool increases the elevation for ALL the cells on the map by the value you have in Set. This is an Additive value.

Custom allows you to apply a picture you have drawn externally in a similar way to Cone. The picture is internally converted to greyscale so you could potentially use a coloured picture which has suitable tonal values. A grey scale picture is advisable though.

The picture to the left is an example png. Most of this is transparent and (obviously) no change will be applied. This is a relatively small picture which could be used repeatedly to add many low rises as "texture" to a map. You could alternatively use a much larger picture once if you really wanted to but first consider whether you should really just be importing a greyscale image for elevation.

Select this menu item to choose a background image. These images can be scans of historical battle maps or textured paper that will make your map appear to be old.

Important note: Depending on the opacity settings (see The Layers Menu, below) the background image may not be immediately visible. This could be because the Elevation Layer is a higher layer and is set for 0% opacity, not allowing the background image to be seen at all.

This check box toggles displaying the Background Image on / off and the slider adjusts the opacity (transparency) of the image. Move the slider to the right for greater opacity. Important note: the Background Layer has the lowest precedence. This means that if the Elevation Layer is on and is set to 0% transparency it will block out the Background Layer.

An example of the Elevation Map displayed with 0% opacity. This is from the Little Bighorn map. Note that the river and tributaries are dark (lower elevation) and the hills and ridges are lighter (higher elevation). Click to enlarge.

This check box toggles displaying the Elevation Map on / off and the slider adjusts the opacity (transparency) of the Elevation Map. Move the slider to the right for greater opacity. Important note: the
Background Layer has the lowest precedence. This means that if the
Elevation Map is on and is set to 0% transparency it will block out
the Background Layer.

This options toggles displaying the Compass Rose on/off. Important Note: to adjust where the Compass Rose points, go to the Edit Terrain Tab, position the cursor over the Compass Rose and use the mouse scroll wheel to rotate the compass rose.

The Terrain Visualizer tool. Note that the blue line indicates where the terrain is being 'sliced'. Click to enlarge.

Select the Terrain Visualizer from the Layers tool to see a 'slice' of the map displayed in a separate window. The window can be moved about freely. As you move the cursor back and forth a vertical line will appear in the Terrain Visualizer showing information about that specific cell (terrain and height). Select the Terrain Visualizer menu item again to make this window and tool disappear. Click to enlarge.

The scale of this map is set at 450 meters for the length of this red line between the two points within the circles. Enter the length of this line in meters and select Save. Click to enlarge.

Tick the Ground Scale box in the Layers menu and a line with two circles will appear. Click and drag the two circles to locations on the map that you know the distance of. Enter the distance in meters at the bottom and select Save.

Bear in mind the range at which units are likely to engage during your game. If you make a map that covers a very large area then pieces could end up looking very close together whilst still thousands of metres apart.

Considerable thought and effort has gone into creating all these tools and options. The intention is to broadly cover the things most users will want. For obvious practical reasons, they cannot possibly cover all the options anyone could ever think of. In order to provide total flexibility there is a final option intended for the advanced enthusiast.

This allows you to add another layer in a canvas and or over ride styling. Whilst this might sound great in theory there is a catch ( isn't there always ). This is low level development in extended Application Markup Language ( XAML ).

How this works is you create a XAML file called a Resource Dictionary in:

%localappdata%\GeneralStaff\BlackPowder\Maps

This must be named CustomResources.xaml.

The content will be loaded dynamically when you run the map editor and merged into it's resources.

If there is a Canvas with an x:Key="CustomCanvas" then this will be added as an extra layer on top of everything.

You can add many things to this canvas but most likely are some sort of shapes. You could use predefined ones such as Rectangle or Ellipse but most likely you will be interested in Path.

A path is a type of generic shaped object which is used in both xaml and svg format graphics. There's a very simple triangular path shape example here:

If you're not a WPF developer then stick to simple stuff first. XAML is rather like HTML so you will immediately see there's xml format opening and closing tags.

Whilst manually editing it is very easy to make mistakes. Complicated paths will be WAY bigger than that triangle so you can't just look at them and work out what you're going to get. Some sort of tooling is advisable so you can test what you will get looks right.

You could install Visual Studio community ( free ) but this is quite a big install.

There are various XAML pad options which are far quicker lighter installs - such as XampPadX

Note that the Windows store XAML Pad is aimed at a different version of XAML than WPF and therefore not a good option.

In order to test my markup in XamlPadX it needs a bit of adaptation.

When you start up the app it gives you a Page to host your markup.

Add a resources section to that and paste your resource dictionary markup into that.

Then reference the canvas using a StaticResource.

This is probably way clearer when seen than described.

You should have something like:

The "Geometry" is used to (loosely speaking) define a series of X,Y co-ordinates which tell it where the path is to be drawn and filled. Rather like one of those children's join-the-dots pictures where each co-oordinate is a dot.

You could type all these in for simple shapes but it's way easier to convert an svg or trace a bitmap picture using a graphics app. I didn't create all that stuff for the starfort manually.

If you find a picture you want to turn into a piece of terrain you can use InkScape's automatic conversion to get the data for a Geometry.

If you have or draw an SVG file then this can contain vector paths and all you would need to do is save as > xaml.

If you have a bitmap source then InkScape can automate tracing of shapes. It's way simpler if you just have one set of shapes to deal with. You are best advised therefore to draw in separate layers with one for roads, another for rivers etc and save these separately or to just draw one layer's worth in a file.

InkScape is fairly mainstream software and I recommend you watch a video explanation of how tracing works.

There are a load of options but you can either choose colour and multiple layers = multiple geometries. Or you can choose black and white. The Star Fort was done using black and white.

It is best if you have one colour for a given terrain - so draw (say ) solid blue or black rivers. If you then want texture, add that later to your picture or flood fill.

Altering the sensitivity is likely to be necessary for a picture containing greys or colours.

Reducing the number of passes is usually a good idea. You will need 2 or more.

Check the preview box which will give you a rough idea of what you'll get.

If you see nothing at all you either have a colour source and aren't using colours OR you haven't selected your picture. Click the picture to select it and see if a preview appears.

Click OK to trace.

Once done click Simplify.

You will now have two layers, one is the original picture and the other your new vector representation.

When you save this you will have a picture as well as your paths in the file. You will be copying and pasting paths out this file rather than using as-is so there's no need to remove the picture.

Choose Save As > XAML ( checking the Silverlight option is usually best ).

This gives you a text file with a .xaml extension.

Open this using notepad ( or your preferred text editing tool such as notepad+ ).

There will be a load of stuff in there. Up the top of the file will probably be your bitmap picture represented by a bunch of letters. Use search to fine on "Path". There will be one or more of these. You will see the characteristic long string of the odd letter but mostly x,y co-ordinates. Cut and paste these into your own geometries in your custom resource dictionary.

When you see these initially they will have a Name tag. Remove that. You will also have an xmlns tag on them, which you could optionally remove. They will often be VERY long. Don't worry about the content of them too much, just make sure you copy all the Path including the closing /> tag.