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 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 Menu [menu] (Optional - ?) - Preferred game menu 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
-
Suggested Rules [rules] (Optional) - Contains the suggested rules for a map
-
Daily Events [dyev] (Deprecated) - 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)
Todo: Get a very simple picture of this map to drive the point home :P
"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)
- Commander Specific List (Optional) - A list of Commanders that will get this specific building (if blank or not present, it will default to all Commanders in the game)
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, ['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, 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]
- Ownership - Player Team Faction # [0-index based] (-1 => Neutral Army)
- Commander Specific List (Optional) - A list of Commanders that will get this specific unit (if blank or not present, it will default to all Commanders in the game)
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, ['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.
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)
-
Teams [team] (Optional) - Contains the suggested teams ( [ ['A', 0, 1], ['B', 2, 3, 4] ] for OS+BM vs GE+YC+BH)
-
Special Rules [rules] (Optional) - Contains the game rules for a map like victory conditions, turn limits, 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.
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).