Map File Documentation
Well, this is THE document that will cover how the map and campaign files are organized for Custom Wars Tactics. We chose the JSON file format to achieve this, because no other format allows the flexibility and scale that this file format can achieve. This document is a living one that will be used for the game and any editors that we need to control map data with.
The goal for this is huge, because the files have to be flexible enough to handle the onslaught of custom terrain, property, units, and Commanders that will eventually make it into the game. Elegance is also very important, because these files should be fairly small for quick loading into the system, so a 'little is much' KISS (Keep It Simple, Stupid) mentality is important.
Like all things in Custom Wars Tactics, this document is a reference. The short term goal within this document is to make sure we not only explain what is in the files, but possibly the reason why things exist within them as well. As such, we will try our best to keep this information contained within up-to-date to the best of our ability.
Custom Wars Tactics is a program with desktop roots in Java and web roots in JavaScript. To meet the demand for an easy to integrate system that'll work for both portions of the code base, we decided that all external data files should be written in one file format. The format chosen for this is JSON.
JSON, though a bit verbose at times, is the most lightweight solution for this task. It easily integrates with JavaScript, and has support for many other major coding languages. Flexibility and readability is JSON's greatest asset, as it allows you to quickly modify and expand data at will. It is one of the few 'human editable' metadata formats that allows full control over scale. It is also why we chose it as the defacto data type for CWT.
JSON Loose Example - CWT Map File - TestMap
The above example is from Custom Wars Tactics - Version 0_3_5 and does not represent how a current map file looks. This will be updated when we get an official map
I realize there is a few ways we can handle organizing the files, so for now I'll document a few ways we can curate the data. Each way, of course, has pros and cons. All data should be represented in hard values determined by the mod it was designed for to discourage percentage floats within the files.
- Within each JSON file, each contains a 'type' attribute so we can tell them apart.
"type": "map"
- We can append a suffix to the end of the file name to tell them apart
spann_island_map.json
- All groups of files can be contained within a separate folder
maps/
Nothing is really stopping us from employing all of these methods, but I'm listing them all here so we can discuss which is the best way to handle it for our system.
This JSON file contains all the data required for starting a Versus Map. Listed below will be the main element (ex in bold -> "name": "value") of a map file:
-
Type [type] (Optional) - Contains the type of file this is
-
Modification [mod] - Contains the game this map belongs to (AW1, AW2, AWDS, AWDR, CW, CWT)
-
Search Tags [tags] (Optional - ?) - Preferred game menu filters you'd like this to appear on (2v2, Classic, FOW, Competitive)
-
Map Name [name] - Contains the debug name of the map (for organizational purposes)
-
Type Map [typeMap] - Used to determine how terrain ID's are organized in a map file
-
Map [map] - The map itself (uses Type Map for representation of tiles)
-
Players [player] - Contains how many players are in this map
-
Map Height [mph] - Contains how many tiles on the y-axis
-
Map Width [mpw] - Contains how many tiles on the x-axis
-
Properties [prps] (Optional) - Contains information regarding the properties and inventions in the map
-
Units [units] (Optional) - Contains information regarding units in the map
-
Display Name [disp] (Optional) - Contains the display name of the map, will use the file name if not present
-
Author [auth] (Optional) - Contains the author of the map
-
Description [desc] (Optional) - Contains the description of the map, allows HTML markup for formatting
-
Suggested Rules [rules] (Optional) - Contains the suggested rules for a map like victory conditions, turn limits, tile sets, weather, and/or fog of war
A list of Terrain Types that is used to organize how the map is represented using 0 as a starting number for the index.
"typeMap": ["PLIN","MNTN","FRST","SEAS","ROAD"],
In this example:
- 0 -> Plain (PLIN)
- 1 -> Mountain (MNTN)
- 2 -> Forest (FRST)
- 3 -> Seas (SEAS)
- 4 -> Road (ROAD)
As an extension, the typeMap will also allow for terrain file names:
AWDS(C)_PLIN(L)$~~~~~~~~
This will allow users to hand pick the tiles that end up on the map, even if the connections do not make much sense. (I'm looking at you bottom left tiny rock in the middle of the sea of Spann Island. :P)
[F]PLIN
The 'F' connection is a special connector for Fire Tiles (specific for CWT) which will make a tile light aflame. This will be the notation to allow for special connections (a.k.a. Terrain Attributes)
Using the type map, map width, and map height, makes a 2 dimensional array of ID's corresponding to the map.
"map": [ [0, 0, 1], [2, 3, 4] ],
Using the Type Map in the previous section, the example above would be a 3x2 map containing (from left->right top->bottom):
- [0,0] Plain (PLIN)
- [1,0] Plain (PLIN)
- [2,0] Mountain (MNTN)
- [0,1] Forest (FRST)
- [1,1] Seas (SEAS)
- [2,1] Road (ROAD)
Todo: Got the picture, have to post it now
"prps": [ [0, "HQTR", 2, 1, 0, [[]], 0, [] ], (...) ],
This handles the ownership and position of properties and inventions for a map. The data for a property is handled as follows:
-
Property ID - The unique ID for a property or invention
-
Property Type ID - The 4-letter abbreviation for a property or invention
-
X-Axis Location - The x-axis tile location (in 0-index format)
-
Y-Axis Location - The y-axis tile location (in 0-index format)
-
Ownership - Player Team Faction # [0-index based] (-1 => Neutral Army)
-
Attribute List (Optional) - A list of numerical attributes describing a building [capt points, hit points] (if blank or not present, it will default to normal game play)
-
Status List (Optional) - A bit representation of status describing a building [disabled, empty] (if blank or not present, it will default to normal game play)
-
Commander Specific List (Optional) - A list of Commanders that will get this specific building (if blank or not present, it will default to normal game play a.k.a all commanders)
Items inside the property list are defined as LIFO (Last In, First Out) if there are multiple of the same Property IDs. As an example:
"prps": [ [1, "HQTR", 2, 1, 0], [1, "BASE", 2, 4, 0], (...) ]
Only the BASE will show up on the map here. The Headquarter will be overwritten and will not show up on this map. If there are Commanders involved however as an example:
"prps": [ [1, "HQTR", 2, 1, 0], [1, "BASE", 2, 4, 0, ['ANDY']], (...) ]
In this case, Sami (and other non-Andy CO's) would get a Headquarter and not a Base. But, Andy will only get a Base because the Headquarter will get overwritten.
"units": [ [1, "RECN", 4, 8, -1, 0, [[]], 0, [] ], (...) ],
This handles the ownership and position of units for a map. The data for a unit is handled as follows:
-
Unit ID - The unique ID for a unit (used for units contained inside units)
-
Unit Type ID - The 4-letter abbreviation for a unit
-
X-Axis Location - The x-axis tile location (in 0-index format)
-
Y-Axis Location - The y-axis tile location (in 0-index format)
-
Load ID - Controls which unit ID this unit is attached to (a.k.a. loaded inside of) [negative => not loaded]
-
Ownership - Player Team Faction # [0-index based] (-1 => Neutral Army)
-
Attribute List (Optional) - A list of numerical attributes describing a unit [hit points, ammo, fuel/rations] (if blank or not present, it will default to normal game play)
-
Status List (Optional) - A bit representation of status describing a unit [wait, hidden] (if blank or not present, it will default to normal game play)
-
Commander Specific List (Optional) - A list of Commanders that will get this specific unit (if blank or not present, it will default to normal game play a.k.a all commanders)
Items inside the unit list are defined as LIFO (Last In, First Out) if there are multiple of the same Unit IDs. As an example:
"units": [ [1, "RECN", 4, 8, -1, 0], [1, "INFT", 6, 3, -1, 0], (...) ]
Only the Infantry will show up on the map here. The Recon will be overwritten and will not show up on this map. If there are Commanders involved however as an example:
"units": [ [1, "RECN", 4, 8, -1, 0, [] ], [1, "INFT", 6, 3, -1, 0, ['SAMI'] ], (...) ]
In this case, Andy (and other non-Sami CO's) would get a Recon and not an Infantry. But, Sami will only get a Infantry because the Recon unit will get overwritten.
Building and Unit - Options (Describes the optional attribute list, status list, and commander list)
The Unit Options where created to define an expansive way of handling attributes, status, and specific commanders for units and buildings (a.k.a. properties and inventions). Below will describe the nuances of each way, as well as describe how these are defined. Except for commanders, the list for building attributes, building status, unit attributes and unit statuses will be generated by an external object_options JSON file that will contain the following information:
"unit_attrib" : [ ["H", 100, "Hit Points", "How many hit points before unit dies], ["A", -1], ["F", 99, "Fuel"], [...] ]
"unit_status" : [ ["W", "Wait/Active"], ["H", "Hidden/Visible"], [...] ]
This is a rough example, but there are a few things to note about this file
- There will probably be a different file per modification
- Negative values in this document will fall back to an external rule sheet defining the defaults
- The order listed in the external sheet will determine the order the values have to be in the array (especially in the case of status)
- The first element of the array must be a unique letter
The attribute list for buildings and units 'must' be a dual array [ [] ] with legal values being determined by the external file described earlier. The two ways to represent this data in the file is:
[ [100, 0, 99] ]
This version describes the values in the order they were written in the external file. In this examples case, it is (hit points, ammo, fuel)
[ [100, 99], ["H", "F"] ]
This version allows you to omit values if you don't want to describe them, and will default to the external file to get the defaults if those values are omitted
The status list for units and buildings 'must' be either a number (0) or a string ("W") and it controls the status of a unit initially when the map is loaded in. The two ways to represent this in data is as follows:
2
A bitwise representation of whether a status is True defined by a number. The order of bits is defined by the order the status was written in the external file
"WH"
The string version allows you to omit values if you don't want to describe them, and will default to the external file to get the defaults if those values are omitted. In this case, in the external file written with (W - "Wait/Active"; H - "Hidden/Visible"; D - "Detected/Visible") it will cause the unit to wait and be hidden the first day, with D omitted, the units will not have a detected icon when the day starts.
The attribute list for commanders 'must' be a single array [] with legal values being determined by the Commanding Officer external file. This list is described as the following:
['ANDY', 'SAMI', 'MAX']
If there is nothing in the list, it'll default to all Commanding Officers
This JSON file is used to organize standalone versus maps into ones that can support scenarios for campaigns. They structure the maps used in a mission, control in game dialogue, and handle the in-game triggers for the maps.
As stated above, this is massively under construction. A lot of the items here are just place holder until we get a better idea of what should be contained in these files and how it should be organized.
-
Type [type] (Optional) - Contains the type of file this is
-
Modification [mod] - Contains the game this mission belongs to (AW1, AW2, AWDS, AWDR, CW, CWT)
-
Map List [list] - A list of maps for this mission
-
Actions [action] - Contains the game triggers (timed, turn, positional) and actions caused by those triggers for a map
-
War Room Speed [wrs] (Optional) - Speed rating: How many days this scenario should take to complete in War Room for a perfect score
-
Commanders [CO] (Optional) - An multidimensional array describing the Commanders and their positions in this scenario (default is character select) (Partnered CO's can be defined as 1A, 1B, 2A, 2B)
-
Mission Type [mtyp] (?) - The kind of mission (dual strike, normal, multi-map)
-
Special Rules [rules] (Optional) - Contains the game rules for a map like victory conditions, turn limits, tile sets, and/or fog of war
-
Daily Events [dyev] (Optional - ?) - Contains the daily events for the map file
-
Dialogue [dia] (Optional - ?) - Contains the game dialogue for a map
A system for handling events in an elegant way is essential for this file type. One of the biggest challenges for this would be to have it easy to understand, while still allowing for many different kinds of events to happen within this file. There is a possibility that there will only be a list of triggers containing actions to perform, but this is totally something we should discuss in the future.
Status List Note for safekeeping: It is possible to also describe multiple days of a status using this method with like "W2H3" for wait (2 days) and be forced hidden (3 days), but that seems more scenario-ish and it'll complicate the simple design.
Defined in both the map file and the mission file, these are the optional rules of the game that structure how the game play will play out. The whole point of rules like these is to create a custom experience, hopefully catered towards your needs so it hits a lot of people's overall likes. Here is a list of the majority of rules within the Advance Wars setting:
- Tile Set [tile] - "" - Which tile set this map should be using ([C]lear, [S]now, [D]esert, [A]pocalypse)
- Fog of War [FOW] - # - Which Fog of War to use (None, AWDS, AWDoR)
- Weather (Start) [weat] - [] - Various attributes describing weather (Random?, Starting?, [Legal Weather Types])
- Teams [team] - Contains the team composition ( [ ['A', 0, 1], ['B', 2, 3, 4] ] for OS+BM vs GE+YC+BH)
- Time Limit [time] - "" - Defeat condition for the physical clock time ("00:10:00" - Defeat in ten minutes)
- Turn Limit [turn] - # - Defeat condition for the amount of days
- Property Limit [prop] - # - Defeat condition for the amount of captured properties
- Unit Limit [unit] - # - Sets the unit limit for the game (because in CWT that's infinite due to no limitations)
- Starting Funds [start] - # - The number of Gold (G.) you start with in game
- Income [income] - # - The amount of Gold (G.) you get per owned property
- Powers [pwrs] - (T/F) - Powers enabled (determined by mod)
- Rank [rank] - (T/F) - Rank enabled (determined by mod)
- AI [ai] - "" - Which AI variant to use, if multiple variants are available
This JSON file is used to organize a collection of mission scenarios into a full blown campaign. This file will handle the grouping of scenarios, where the world map is connected, the unlock requirements of certain scenarios, where the flag nodes are in the world map, and the overall conditions of the campaign.
As stated above, this is massively under construction. A lot of the items here are just place holder until we get a better idea of what should be contained in these files and how it should be organized.
-
Type [type] (Optional) - Contains the type of file this is
-
Modification [mod] - Contains the game this campaign belongs to (AW1, AW2, AWDS, AWDR, CW, CWT)
-
Mission List [list] - A list of scenarios for this campaign, their connectivity to each other, and their place in the world map
-
World Map File [wmf] - Contains the path to the world map file
-
World Map Color [wmc] - Contains coloring information for the world map (if wanting to show completion by changing a color node
-
Daily Events [dyev] (Optional - ?) - Contains the daily events for the map file
-
Rules [rules] (Optional - ?) - Contains the game rules for a map
-
Dialogue [dia] (Optional - ?) - Contains the game dialogue for a map
The save file should double as a replay file, but it doesn't necessarily have to be in JSON. It just needs to contain the necessarily information for serialization (saving and loading a persistent game world).
This section is to document the old method of doing things for posterity.
Custom Wars Tactics is a program with desktop roots in Java and web roots in JavaScript. To meet the demand for an easy to integrate system that'll work for both portions of the code base, we decided that all external data files should be written in one file format. The format chosen for this is JSON.
JSON, though a bit verbose at times, is the most lightweight solution for this task. It easily integrates with JavaScript, and has support for many other major coding languages. Flexibility and readability is JSON's greatest asset, as it allows you to quickly modify and expand data at will. It is one of the few 'human editable' metadata formats that allows full control over scale. It is also why we chose it as the defacto data type for CWT.
JSON Example - CWT Map File - TestMap
I realize there is a few ways we can handle organizing the files, so for now I'll document a few ways we can curate the data. Each way, of course, has pros and cons. All data should be represented in hard values determined by the mod it was designed for to discourage percentage floats within the files.
- Within each JSON file, each contains a 'type' attribute so we can tell them apart.
"type": "map"
- We can append a suffix to the end of the file name to tell them apart
spann_island_map.json
- All groups of files can be contained within a separate folder
maps/
Nothing is really stopping us from employing all of these methods, but I'm listing them all here so we can discuss which is the best way to handle it for our system.
This JSON file contains all the data required for starting a Versus Map. Listed below will be the main element (ex in bold -> "name": "value") of a map file:
-
Type [type] (Optional) - Contains the type of file this is
-
Modification [mod] - Contains the game this map belongs to (AW1, AW2, AWDS, AWDR, CW, CWT)
-
Tileset [tileset] (Optional) - Contains the preferred starting tile set of the map
-
Map Name [name] - Contains the debug name of the map (for organizational purposes)
-
Type Map [typeMap] - Used to determine how terrain ID's are organized in a map file
-
Map [map] - The map itself (uses Type Map for representation of tiles)
-
Players [player] - Contains how many players are in this map
-
Map Height [mph] - Contains how many tiles on the y-axis
-
Map Width [mpw] - Contains how many tiles on the x-axis
-
Suggested Rules [rules] (Optional - Unused) - Contains the suggested rules for a map
-
Daily Events [dyev] (Optional - Unused) - Contains the daily events for the map file
A list of Terrain Types that is used to organize how the map is represented using 0 as a starting number for the index.
"typeMap": ["PLIN","MNTN","FRST","WATER","ROAD"],
In this example:
- 0 -> Plain (PLIN)
- 1 -> Mountain (MNTN)
- 2 -> Forest (FRST)
- 3 -> Seas [SEAS] (WATER)
- 4 -> Road (ROAD)
As an extension, the typeMap will also allow for terrain file names:
AWDS(C)_PLIN(L)$~~~~~~~~
This will allow users to hand pick the tiles that end up on the map, even if the connections do not make much sense. (I'm looking at you bottom left tiny rock in the middle of the sea of Spann Island. :P)
Using the type map, map width, and map height, makes a 2 dimensional array of ID's corresponding to the map.
"map": [ [0, 0, 1], [2, 3, 4] ],
Using the Type Map in the previous section, the example above would be a 3x2 map containing (from left->right top->bottom):
- [0,0] Plain (PLIN)
- [1,0] Plain (PLIN)
- [2,0] Mountain (MNTN)
- [0,1] Forest (FRST)
- [1,1] Seas (SEAS)
- [2,1] Road (ROAD)
"prps": [ [0, 2, 1, "HQTR", 20, 0, [] ], (...) ],
This handles the ownership and position of properties and inventions for a map. The data for a property is handled as follows:
- Property ID - The unique ID for a property or invention
- X-Axis Location - The x-axis tile location (in 0-index format)
- Y-Axis Location - The y-axis tile location (in 0-index format)
- Property Type ID - The 4-letter abbreviation for a property or invention
- Capture/Hit Points - Positive # => Capture Points [negative# => Hit points]
- Ownership - Player Team Faction # [0-index based] (-1 => Neutral Army)
Items inside the property list are defined as LIFO (Last In, First Out) if there are multiple of the same Property IDs. As an example:
"prps": [ [1, 2, 1, "HQTR", 20, 0], [1, 2, 4, "BASE", 20, 0], (...) ]
Only the BASE will show up on the map here. The Headquarter will be overwritten and will not show up on this map. If there are Commanders involved however as an example:
"prps": [ [1, 2, 1, "HQTR", 20, 0], [1, 2, 4, "BASE", 20, 0], (...) ]
In this case, Sami (and other non-Andy CO's) would get a Headquarter and not a Base. But, Andy will only get a Base because the Headquarter will get overwritten.
"units": [ [1, "RECN", 4, 8, 100, 0, 40, -1, 0], (...) ],
This handles the ownership and position of units for a map. The data for a unit is handled as follows:
- Unit ID - The unique ID for a unit (used for units contained inside units)
- Unit Type ID - The 4-letter abbreviation for a unit
- X-Axis Location - The x-axis tile location (in 0-index format)
- Y-Axis Location - The y-axis tile location (in 0-index format)
- Hit Points - The amount of initial hit points of a unit
- Ammo - The amount of initial ammo of a unit [negative => infinite]
- Fuel/Rations - The amount of initial fuel of a unit [negative => infinite]
- Load ID - Controls which unit ID this unit is attached to (a.k.a. loaded inside of) [negative => not loaded]
- Ownership - Player Team Faction # [0-index based] (-1 => Neutral Army)
Items inside the unit list are defined as LIFO (Last In, First Out) if there are multiple of the same Unit IDs. As an example:
"units": [ [1, "RECN", 4, 8, 100, 0, 40, -1, 0 ], [1, "INFT", 6, 3, 100, 0, 15, -1, 0 ], (...) ]
Only the Infantry will show up on the map here. The Recon will be overwritten and will not show up on this map. If there are Commanders involved however as an example:
"units": [ [1, "RECN", 4, 8, 100, 0, 40, -1, 0 ], [1, "INFT", 6, 3, 100, 0, 15, -1, 0 ], (...) ]
In this case, Andy (and other non-Sami CO's) would get a Recon and not an Infantry. But, Sami will only get a Infantry because the Recon unit will get overwritten.