Tank Crew Template Creation
A guide to creating new templates for the Tank Crew Mission Generator
Map Template structure (CoopTemplate_PROKHOROVKA)
Static
All static objects such as buildings, bridges go in here. You can make sub groups in here as long as the group names are always unique across the whole mission file!
2. Helpers
Helpers are defined by the Helper: Reference point MCU in the template to define all the possible locations where to put objects such as objectives, smoke columns, AAA etc.
'helpers_smoke' and 'helpers_AAA' do not need a lot of explanation, just a bunch of possible locations. The mission generator will try to pick most of these close to the front, so there is no need to take that into account. Just define a bunch of locations that can be used, regardless of the front position as long as they are within the map boundary.
' helpers_patrols is just a bunch of random waypoints that the AI planes will use to create a simple flight plan. 'helpers_planes' is where they can spawn. You can have multiple per side, but keep the numbering consistent.
'helpers_positions' is where all the locations are that are used to place objectives, but also to define start positions for a platoon. The name is now always 'position_150' which means an object with size smaller than 150m across can be placed here. In future there may be more sizes to cater for more specific objectives as is already done for the standard Easy Mission Generator. Size and orientation of the MCU do not matter for the generator, but it is practical to keep it 150m so you can see if it fits.
Some notes:
Make sure there are enough helpers around. If there are not enough locations to choose from the mission generator may throw an error. I have tried to catch these exceptions, but this is still WIP.
Check in 3D that the location is relatively flat and is not closed in by cliffs or building to avoid awkward placement of artillery for example
3. Airfields
Defines the airfield locations, but not used in Tank Crew as AI planes spawn in the air
4. Path_AI
Currently the most challenging part of the mission generator is how to make sure the AI tanks can find their way around the map, or 'pathfinding' as it is called in game development. Without this the AI will try to follow a straight line from A to B and then bump into buildings, drown in rivers or fall off cliffs.
First Person shooter games usually have map editors with tools that automatically calculate the areas where AI can navigate, see for example the blue area in this picture from the CryEngine editor.
IL2/TankCrew doesn't have this. The vehicles are capable of avoiding collisions with each other and are able to follow roads but navigating the terrain off-road is not possible in real time. Therefore we have to do this in the mission editor by defining exactly where the vehicles may go using waypoints. Doing this by hand is not very difficult, but when we want to generate a mission using random locations on the map we need to define beforehand what are valid waypoints and what not.
To define this navigation area I use a grid of waypoints in the mission editor. It's a bit like an invisible road network for the AI. This is called a 'graph' in mathematics and by doing so one can use smart algorithms to determine the shortest route between two endpoints; the most famous being the Dijkstra algorithm which is the one I am using. Besides the location it is also useful to know if the vehicle is driving over a road or in open terrain so the formation type can be changed.
Waypoint size ('Area' in the mission editor properties) determines the formation: 5m is considered as 'on road' and a size > 5 is 'off road'.
When a vehicle uses 'on road' formation it will always stick to the road, avoiding any navigation issues
In the template the direction of the arrow between two waypoints has no meaning, the algorithm will consider both directions when trying to find the shortest path
Except between 'on road' waypoints always make sure that the line between two waypoints is free of obstacles. This includes any possible objects that may get spawned, so also take into account any helpers_positions (see Helpers).
In this picture we see several waypoints. The ones on a road have Area=5 and the others have Area=250 and some have Area=50 to make sure the AI do not cut a corner too soon.
When a vehicle drives from a waypoint with Area=5 to another waypoint with Area=5 it uses 'on road' formation and thus will stick to the road.
When it drives from a waypoint with Area>5 to another one with Area>5 it will follow a straight line between the two waypoints in ' off road' formation.
When a vehicle drives from an 'offroad' waypoint to an 'onroad' waypoint it will set formation to 'on road' and will try to get to the road as quickly as possible then move to the other waypoint.
When going from 'on road' waypoint to an 'off road' waypoint it will leave the road immediately
When the vehicle reaches the boundary of a waypoint, defined by Area, it will immediately switch to the next waypoint, not passing the center.
5. Lines_A
This group defines the front lines and the total battle area. There can be multiple, suffixed by a capital letter. This picture shows the contents of such a group which defines a 'front'.
Icons are used to draw the border (one in each corner) and the front lines. You can copy the settings (Icon ID, Line Style) from the existing Prokhorovka template. The location of the front line is important as it is used to orient some objects when placed on the map, ie artillery will always face the front. The borders are used to define the total battle area: all static objects outside this area will get deleted from the mission to improve performance.
Then there are two Influence Areas that define the territory. These are important to determine where suitable locations (Helpers) are for which faction.
Objects Template structure (CoopTemplate_TANKCREW)
This template contains generic groups for all maps. If you just want to add a new map there is no need to change this template.
In 'Assets' are the various groups for a player or AI platoon or flight. Be careful with changing these as the generator will transform these groups (ie adding waypoints) which can only work if certain MCU's exist in the group. The others like AAA, Smoke and Defences are simply templates and can be changed.
In 'Objectives' are the templates for the various objectives. There should always be one for each side. If there are multiple for each side then the generator will pick one at random to add more variety. These groups can be changed as long as the reference_point (location marker) and success_trigger (gets connected to the mission scoring logic) are there.
Adding a new map
In order to add a completely new map you need to create a new map template file as described above and the following config file needs to be adjusted: maps.json
This is json file that holds the map definitions. The structure is as follows:
{
"<map name>": {
"template": "<name of the template mission file>",
"theatre": "<there are 3 theatre of wars defined: WW2_EAST, WW2_WEST and WW1_WEST>",
"fighters_allied": [<NOT USED IN TANKCREW>],
"bombers_allied": [<NOT USED IN TANKCREW>],
"fighters_axis": [<NOT USED IN TANKCREW>],
"bombers_axis": [<NOT USED IN TANKCREW>],
"attackers_allied": [<a list of allied attackers that are used as AI, full name>],
"attackers_axis": [<a list of axis attackers that are used as AI, full name>],
"transports_allied": [<NOT USED IN TANKCREW>],
"transports_axis": [<NOT USED IN TANKCREW>],
"tanks_allied": [<a list of allied tanks that are used for players, full name. Example: "KV-1s", "M4A2 Sherman">],
"tanks_axis": [<a list of axis tanks that are used for players, full name>],
"scouts_allied": [<a list of allied scouts that are used for AI only, full name>],
"scouts_axis": [<a list of axis scouts that are used for AI only, full name>],
"targets_tank": [<a list of possible target types. Supported types are: "artillery", "buildings", "bunker", "vehicles">],
"lines": {<NOT USED IN TANKCREW, but not yet deprecated. Leave empty for now>},
"scenarios": [<a list of possible mission types. Supported types are: "Random", "Attack", "Defend", "Skirmish">],
"periods": {<key value pairs of fronts with associated letter in the template. Example: "july 11, '43": "A", "july 12, '43 AM": "B">},
"seasons": { <defines how the landscape files are named in the mission editor per season. Prokhorovka only has one season>
"spring": {"landscape": "LANDSCAPE_Prokhorovka", "guimap": "prokhorovka"},
"summer": {"landscape": "LANDSCAPE_Prokhorovka", "guimap": "prokhorovka"},
"autumn": {"landscape": "LANDSCAPE_Prokhorovka", "guimap": "prokhorovka"},
"winter": {"landscape": "LANDSCAPE_Prokhorovka", "guimap": "prokhorovka"} }
}
}
When you add a new map you should copy the existing entry for "Prokhorovka" and then at least change the values in blue. The red ones you can re-use or change as needed. Any tank/vehicle type that is used in the tanks_ and scouts_ lists should be in the vehicle definition in \data\vehicles.json