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 Main Page

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.

In CWT, there are a few file layers which describe how the files relate to each other. There are four distinct layers of files for Custom Wars Tactics:

• Layer 1 - Object File - This Layer handles initializing objects for modifications, and contains all the base stats for an object.
• Layer 2 - Map File - Handles positioning of an object within the map, and may alter the statistics and attributes of that object.
• Layer 3 - Scenario File - Handles special rules and heavy alterations of objects within the world where almost all data entries can be altered.
• Layer 4 - Campaign File - This organizes groups of Scenario Files together to create campaigns and other grouped events that are intended to be played as part of some sequence.

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.

(Version 0.999 - Release Candidate 3 [RC3])

Below follows a complete example of a valid map file representing the map shown above (Wrench Island from AW1). The rest of this document will break down each section in further detail.

{
    "data": {
        "type": "map",
        "mod": "AW1",
        "auth": "Nintendo",
        "tags": [
            "Small",
            "Pre-Deployed",
            "Base Light",
            "Ground War"
        ],
        "folders": [
            "Versus/Casual"
        ],
        "mpw": 22,
        "mph": 13,
        "player": 2,
        "rules": {
            "tile": { "type": "C" }
        },
        "typeMap": [
            {"type": "SEAS"},
            {"type": "REEF"},
            {"type": "SHOA"},
            {"type": "PLIN"},
            {"type": "FRST"},
            {"type": "MNTN"}
        ],

        "map": [
            [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
            [0,1,0,0,0,0,0,0,1,0,0,1,0,0,0,1,0,0,0,0,0,1],
            [0,0,2,3,3,2,0,0,0,0,0,0,0,0,0,0,2,3,3,2,0,0],
            [0,2,3,3,3,3,2,0,0,0,0,0,1,0,0,2,3,3,3,3,2,0],
            [0,3,3,4,3,3,3,2,2,2,2,2,2,2,2,3,3,3,4,3,3,0],
            [0,0,0,0,3,3,4,5,4,4,4,4,4,4,5,4,3,3,0,0,0,0],
            [0,0,1,0,3,3,3,5,4,3,4,4,3,4,5,3,3,3,0,1,0,0],
            [0,0,0,0,4,3,3,5,4,4,4,4,4,4,5,3,3,4,0,0,0,0],
            [0,3,3,4,3,3,3,2,2,2,2,2,2,2,2,3,3,3,4,3,3,0],
            [0,2,3,3,3,3,2,0,0,0,0,0,0,0,0,2,3,3,3,3,2,0],
            [0,0,2,3,3,2,0,0,0,0,0,0,1,0,0,0,2,3,3,2,0,0],
            [0,1,0,0,0,0,1,0,0,1,0,1,0,0,0,1,0,0,0,0,0,0],
            [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
        ],

        "props": [
            {"id": 0, "type": "CITY", "x": 1, "y": 4, "owner": 0},
            {"id": 1, "type": "CITY", "x": 20, "y": 4, "owner": 1},
            {"id": 2, "type": "CITY", "x": 4, "y": 5, "owner": 0},
            {"id": 3, "type": "CITY", "x": 17, "y": 5, "owner": 1},
            {"id": 4, "type": "CITY", "x": 5, "y": 6, "owner": 0},
            {"id": 5, "type": "HQTR", "x": 9, "y": 6, "owner": 0},
            {"id": 6, "type": "HQTR", "x": 12, "y": 6, "owner": 1},
            {"id": 7, "type": "CITY", "x": 16, "y": 6, "owner": 1},
            {"id": 8, "type": "CITY", "x": 6, "y": 7, "owner": 0},
            {"id": 9, "type": "CITY", "x": 15, "y": 7, "owner": 1},
            {"id": 10, "type": "CITY", "x": 1, "y": 8, "owner": 0},
            {"id": 11, "type": "CITY", "x": 20, "y": 8, "owner": 1}
        ],

        "units": [
            {"id": 0, "type": "LNDR", "x": 2, "y": 2, "owner": 0},
            {"id": 1, "type": "TANK", "x": 3, "y": 2, "owner": 0},
            {"id": 2, "type": "TANK", "x": 17, "y": 2, "owner": 1},
            {"id": 3, "type": "MDTK", "x": 18, "y": 2, "owner": 1},
            {"id": 4, "type": "LNDR", "x": 19, "y": 2, "owner": 1},
            {"id": 5, "type": "INFT", "x": 1, "y": 3, "owner": 0},
            {"id": 6, "type": "RCKT", "x": 4, "y": 3, "owner": 0},
            {"id": 7, "type": "RCKT", "x": 17, "y": 3, "owner": 1},
            {"id": 8, "type": "INFT", "x": 20, "y": 3, "owner": 1},
            {"id": 9, "type": "INFT", "x": 1, "y": 4, "owner": 0},
            {"id": 10, "type": "INFT", "x": 20, "y": 4, "owner": 1},
            {"id": 11, "type": "BSHP", "x": 0, "y": 5, "owner": 0},
            {"id": 12, "type": "BSHP", "x": 21, "y": 5, "owner": 1},
            {"id": 13, "type": "SUBM", "x": 0, "y": 6, "owner": 0},
            {"id": 14, "type": "SUBM", "x": 21, "y": 6, "owner": 1},
            {"id": 15, "type": "CRUS", "x": 0, "y": 7, "owner": 0},
            {"id": 16, "type": "CRUS", "x": 21, "y": 7, "owner": 1},
            {"id": 17, "type": "MECH", "x": 1, "y": 8, "owner": 0},
            {"id": 18, "type": "RECN", "x": 3, "y": 8, "owner": 0},
            {"id": 19, "type": "RECN", "x": 18, "y": 8, "owner": 1},
            {"id": 20, "type": "MECH", "x": 20, "y": 8, "owner": 1},
            {"id": 21, "type": "MECH", "x": 1, "y": 9, "owner": 0},
            {"id": 22, "type": "ARTY", "x": 4, "y": 9, "owner": 0},
            {"id": 23, "type": "ARTY", "x": 17, "y": 9, "owner": 1},
            {"id": 24, "type": "MECH", "x": 20, "y": 9, "owner": 1},
            {"id": 25, "type": "LNDR", "x": 2, "y": 10, "owner": 0},
            {"id": 26, "type": "MDTK", "x": 3, "y": 10, "owner": 0},
            {"id": 27, "type": "TANK", "x": 4, "y": 10, "owner": 0},
            {"id": 28, "type": "TANK", "x": 18, "y": 10, "owner": 1},
            {"id": 29, "type": "LNDR", "x": 19, "y": 10, "owner": 1}
        ]
    },

    "text": {
        "en": {
            "name": "Wrench Island",
            "description": "An original map from Advance Wars' Predeployed case. The units you get will depend on your CO. The ones here are from an Andy vs Andy battle."
        },

        "de": {
            "name": "Inselwinden",
            "description": "Eine Originalkarte aus dem Fall Predeployed von Advance Wars. Die Einheiten, die Sie erhalten, hängen von Ihrem CO ab. Die hier sind aus einem Kampf zwischen Andy und Andy."
        }
    }
}

This block of data contains most of the information defining the map itself. Listed below will be the elements present in this block.

The following elements are required to provide metadata about the map.

• "type": "map" - Contains the type of file this is to distinguish it from the scenario and campaign files defined elsewhere in this document. All map files should contain this key-value pair set to "map".
• "mod": "AW1" - Contains the game this map belongs to. One of ["AW1", "AW2", "AW3", "AW4", "AWBW", "CW", "CWT"]
• "mpw": 22 - The width of the map.
• "mph": 13 - The height of the map.
• "player": 2 - The number of players present in the map.

The following elements actually define the map itself.

• "typeMap": [ {"type": "SEAS"}, <...> ] - An array of objects, each of which defines a terrain present in the map. See the Type Map section below for details.
• "map": [ [0,0,0, <...>], [0,1,0, <...>], <...>] - A 2-dimensional array of integers representing the map data itself. The integers refer to the index of the tile in the "typeMap" array, so in this case 0 would be a SEAS tile, 1 would be a SHOA tile, etc.

• "auth": "Nintendo" - Contains the name of the map's author.
• "tags": ["Small", <...>] - An array that contains the categories and sub-categories where this map will appear, based on map features automatically detected by the map editor software.
• "folders": ["Versus/Casual", <...>] - An array that contains the categories and sub-categories where this map will appear, based on choices made by the map author.
  • For further details on the "tags" and "folders" keys, see the Map Category Documentation.
• "rules": { "tile": { "type": "C" }, <...> } - The default rules with which the map is to be played. See the Rules section for details.
• "props": [ {"id": 0, "type": "CITY", "x": 1, "y": 4, "owner": 0}, <...> ] - An array of properties and inventions present on the map. Most maps will include this element, but it is technically optional. (The first two maps in AW1's Field Training have no properties, for example). See the Properties section for details.
• "units": [ {"id": 0, "type": "LNDR", "x": 2, "y": 2, "owner": 0}, <...> ] - An array of units present on the map. See the Units section for details.
• "skinMap": [ { "type": "C", "skin": "retro" }, { "type": "S" } ] - An array of strings, each of which defines a tileset (and optionally also skin) present in the map. Used in conjunction with "skin".
• "skin": [ [0,0,0, <...>], [0,1,0, <...>], <...>] - A 2-dimensional array of integers similar to the "map" array. The integers refer to the index of the tileset in the "skinMap" array, so in this case 0 would be Clear, 1 would be Snow, etc. This is only necessary in maps where multiple tilesets are present, if the whole map is one tileset this can be specified in the Rules.
• "seed": 41546971 - The seed value for the pseudorandom number generator, used to determine the layout of tile variants based on randomness (eg. AW4 PLIN tile variants).

"typeMap": [
    {"type": "SEAS"},
    {"type": "REEF"},
    {"type": "SHOA"}
]

Each of the terrain objects in the array contains at least one element:

• "type": "SEAS" - The terrain type, as found in the list of terrain types.

It may also optionally contain one or more of the following:

• "type_variant": 2 - A numerical ID representing which variant of the tile is represented.
  • This allows specifying non-standard tile variants if, for example, the map author wants a road to connect to a mountain tile.
• "underlay_type": "SEAS" - In the case of AW4, some terrain can be above more than one other type. The obvious examples are BRDG (over SEAS or RIVR) and PLSM/METR (over PLIN or SEAS). This keyword allows specifying which terrain type is used underneath.
• "underlay_variant": 2 - Used in conjunction with "underlay_type" to specify which tile variant is used for the underlay.
• A keyword to specify any terrain attributes or statuses. These will vary by mod, but will be defined in the mod's object-options.json file. The default values for these attributes will be defined elsewhere. In the case of the CWT mod, the following attributes are present.
  • "burning": true - Whether or not the tile is on fire.
  • "blocked": true - Whether or not the tile is blocked (eg. move cost of X).

"props": [
    {"id": 0, "type": "CITY", "x": 1, "y": 4, "owner": 0},
    {"id": 1, "type": "CITY", "x": 20, "y": 4, "owner": 1},
    {"id": 2, "type": "CITY", "x": 4, "y": 5, "owner": 0}
],

Each of the property objects in the array contains at least these five elements:

• "id": 0 - A numerical ID used to identify the property. This can be used to specify a property in scenario files (to create objectives in missions, for example). If more than one property in the array has the same ID, the game will operate on a last-in-first-out approach
• "type": "CITY" - The property type, as found in the list of property types.
• "x": 1 - The x-axis position of the property.
• "y": 4 - The y-axis position of the property.
• "owner": 0 - The faction that owns the property, where -1 is Neutral.

It may also optionally contain one or more of the following:

• "variant": 2 - A numerical ID representing which variant of the tile is represented.
  • This allows specifying non-standard sprite variants if, for example, the map author wants Blue Moon's HQTR to use the Orange Star HQTR sprite.
• "co": ["ANDY", "SAMI"] - A list of COs for whom this property will be present. If not specified, the unit will default to being available for all COs.
• A keyword to specify any property attributes or statuses. These will vary by mod, but will be defined in the mod's object-options.json file. The default values for these attributes will be defined elsewhere. In the case of the CWT mod, the following attributes are present.
  • "cp": 20 - The number of capture points the property has.
  • "hp": 99 - The number of hit points the property has (eg. for Black Hole inventions).
  • "disabled": false - Whether or not the property is active (eg. for production properties, whether building units from this property is allowed).

"units": [
    {"id": 0, "type": "LNDR", "x": 2, "y": 2, "owner": 0},
    {"id": 1, "type": "TANK", "x": 3, "y": 2, "owner": 0},
    {"id": 2, "type": "TANK", "x": 17, "y": 2, "owner": 1}
]

Similarly to properties, each unit object in the array contains at least these five elements:

• "id": 0 - A numerical ID used to identify the unit. This can be used to specify a unit in scenario files (to create objectives in missions, for example). This is also used to specify units loaded into transports. If more than one unit in the array has the same ID, the game will operate on a last-in-first-out approach
• "type": "LNDR" - The unit type, as found in the list of unit types.
• "x": 1 - The x-axis position of the unit.
• "y": 4 - The y-axis position of the unit.
• "owner": 0 - The faction that owns the unit, where -1 is Neutral.

It may also optionally contain one or more of the following:

• "variant": 2 - A numerical ID representing which variant of the unit is represented.
  • This allows specifying non-standard sprite variants if, for example, the map author wants Blue Moon's INFT to use the Orange Star INFT sprite.
• "co": ["ANDY", "SAMI"] - A list of COs for whom this unit will be present.
  • This allows for situations like the AW1 pre-deployed maps where each CO had a unique set of units. If not specified, the unit will default to being available for all COs.
• A keyword to specify any unit attributes or statuses. These will vary by mod, but will be defined in the mod's object-options.json file. The default values for these attributes will be defined elsewhere. In the case of the CWT mod, the following attributes are present.
  • "hp": 100 - The number of hit points the unit has.
  • "ammo": -1 - The amount of ammunition the unit has. -1 for infinite.
  • "fuel": 99 - The amount of fuel the unit has. -1 for infinite.
  • "rank": 0 - The unit's rank (I, II, V, A).
  • "material": -1 - The number of materials a unit has for building. -1 for infinite.
  • "loaded": -1 - The ID of the unit in which this unit is loaded. Note this attribute is set on the loaded unit, not the transport (eg. an INFT might have this set to the ID of an APCR). -1 for not loaded.
  • "wait": false - Whether or not the unit will start the game in the "wait" state.
  • "hidden": false - Whether or not a SUBM or STLH are dived/hidden respectively.
  • "commander": false - Whether or not the unit is a CO unit.
  • "disabled": false - Whether or not the unit starts the game disabled (eg. inflicted with Von Bolt's SCOP effect)

These are the optional rules of the game that structure how the game play will play out. These can be defined in the map file and/or the scenario file. If defined in the map file, these rules are merely suggested defaults, if defined in the scenario file, they are enforced. If defined in both, any conflicting rules from the scenario file will take precedence.

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:

• "tileset": { "type": "C", "skin": "retro" } - Contains the tileset type ([C]lear, [R]ain, [S]now, [D]esert, [A]pocalypse) and optionally also a skin.
• "fow": 1 Which Fog of War style to use (None, AWDS, AWDoR).
• "weather": { "C": 80, "S": 20 } - The weighted chance of each weather type happening at the start of each day.
  • In the case where the sum is 100, these are percentages, but if for example "S" was 40 instead of 20, the chance of snow would be 40/(80+40) = 33%.
• "team": [[['A', 0, 1], ['B', 2, 3, 4]], <...> ] - Contains the team composition. In this example, OS+BM vs GE+YC+BH.
  • Note that multiple different team setups can be specified (eg. a map could specify both OS+BM vs GE+YC and OS+GE vs BM+YC as suggested setups).
• "time": [600, 0, 0] - Time allowed per player in seconds. First no. is total time, second no. is time added per turn, third no. is time added per unit.
• "turn": 20 - Max. no. of days.
• "prop": 10 - No. of captured properties needed to win.
• "unit": 50 - Sets the unit limit for the game.
• "start": 0 - The amount of Gold (G.) you start with.
• "income": 1000 - The amount of Gold (G.) you get per owned property at the start of each turn.
• "powers": true - Whether or not CO Powers are enabled.
• "rank": true - Whether or not units can rank up.
• "ai": "" - "" - Which AI variant to use, if multiple variants are available.
• "face": ["L", <...>] - "[L]eft or [R]ight, which way each army should face.

This block contains text that may be present in multiple languages. Each language present in the file is in a separate block, specified by its ISO 639-1 code.

"text": {
    "en": {
        "name": "Wrench Island",
        "description": "An original map from Advance Wars' Predeployed case. The units you get will depend on your CO. The ones here are from an Andy vs Andy battle."
    },

    "de": {
        "name": "Inselwinden",
        "description": "Eine Originalkarte aus dem Fall Predeployed von Advance Wars. Die Einheiten, die Sie erhalten, hängen von Ihrem CO ab. Die hier sind aus einem Kampf zwischen Andy und Andy."
    }
}

Each of these individual language blocks contain at the very least one element:

• "name": "Wrench Island" - The name of the map, for organisational purposes.

There are also the following elements that may be present.

• "display_name": "Wrench Island (AW1)" - The map's name as it will be displayed in game, in this case used to distinguish that this is the AW1 version of the map.
• "description": "An original map from Advance Wars' Predeployed..." - A description of the map.

At the time of writing these are the only elements that are present in the "text" block, but in future, should properties or units have attributes that are strings (if someone creates a mod in which individual units can be assigned names, for example), this can be handled as shown in the example below:

"en": {
    "unit": [
        { "id": 0, "name": "Alpha Team Leader" },
    ]
},

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 - "[W]ait/Active"; H - "[H]idden/Visible"; T - "De[t]ected/Visible") it will cause the unit to wait and be hidden the first day, with T omitted, the units will not have a detected icon when the day starts.

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. Things to remember in this file for the future:

• Units need to be able to be spawned in the scenario maps
• New players need to be able to be spawned in the scenario maps (unsure about this, might be confusing for players)

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.

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).