This page details the .json file at the core of every mod. Being JSON, the order of the Information here is subject to change, but is accurate as of 2020/06/19.

Basic Mod Info

The start of each mod file contains the following JSON elements:

• "mod_name": String. The name of the mod, stored in any maps saved when this mod is in use by the editor.
• "tilesize": Integer. The size in pixels of the tiles in this mod, either 16 or 24.
• "tilesets": Object. Contains one entry for each tileset in the mod.
  • "<tileset name>": Array [String, String, String]. <tileset name> is the display name of the tileset, then the tileset array is as follows.
    • Single character for the type of tileset: (C)lear, (R)ain, (D)esert, (S)now, (A)pocalypse. This character is stored in saved maps as the default tileset to use for the map.
    • The folder containing the terrain images for this tileset.
    • The folder containing the unit images for this tileset. Note that multiple tilesets can (and in most cases will) point to the same units folder, this is mostly here to allow people the option to be creative with unit sprites.

Faction Colours

The colour palettes are defined here.

• "default_palettes": Object. The default colours used in the images stored in the gfx folder.
  • "property_palette": Array [String, ...]. An array of strings which store the colours used in the image as ARGB hex values (eg. "FFBD5A4A"). The alpha channel will almost always be "FF".
  • "unit_palette": Array [String, ...]. See above.
  • "minimap_palette": Array [String, ...]. See above.

After the default palette is defined, the factions themselves are listed. The array index of each faction is used when loading and saving maps.

• "factions": Array. An array of objects, one for each faction present in the mod. Each of these faction objects contains the following elements:
  • "name": The name of the faction, used later in this file to determine terrain variants for owned properties (eg. HQTR). Also used in the editor's faction dropdown for properties and units.
  • "property_palette": Array [String, ...]. Same format as the default palettes mentioned above. The colours in the default palette map to the corresponding array entry for each faction, so these arrays should always be the same length as the defaults.
  • "unit_palette": Array [String, ...]. See above. Note that any army with no unit palette cannot have units, eg. Neutral armies in the base games.
  • "minimap_palette": Array [String, ...]. See above.

Minimap Graphics

• "minimap": Object. An object containing information about the minimap graphics.
  • "terrain_gfx": String. The path to the minimap terrain graphics spritesheet.
  • "property_gfx": String. The path to the minimap property graphics spritesheet.
  • "unit_gfx": String. The path to the minimap unit graphics spritesheet.
  • "tilesize": Integer. The size in pixels of the minimap graphics in this mod. In the base games, this is 4.

Animators

This is where the animation timings are defined. Note that AW runs at 60fps and thus one "tick" is defined as 1/60th of a second.

• "animators": Array. An array of arrays, where each array represents one "animator". The index of an animator is used later when defining terrain, units and properties.
  • Array [Integer, ...]. Each array element is an array of integers representing the number of ticks each frame of animation lasts before moving on to the next frame. For example, AW2 units are [17, 8, 17, 8], so using the infantry sprite as an example, the first and third frames last 17 ticks, the second and fourth frames last 8 ticks.

Terrain

Here we get into the meat of the mod.

"terrain": Array [Object, ...]. An array of objects, one for each natural terrain present in the mod.

Each of these terrain objects should contain the following three elements:

• "name": String. The name of the terrain. This is used in the typeMap section of saved map files, and also referred to elsewhere in the <mod>.json file.

• "gfx": Array. An array containing the path(s) to the image file(s) for this terrain. Where multiple variants exist (eg. tiles with connections such as roads), each variant has its own entry in this array. These paths can take one of the following three forms, and different variants of the same terrain can use different forms:

  • String. A basic string pointing to the image file within the selected tileset's terrain folder (as defined in the tileset section above).
  • Array [String, Integer]. An array of two elements, the first being a string as above, the second being an integer containing the array index of the animator to use for this particular image.
    • Note that different variants of the same terrain can use different animators. In addition, this second form can be used with -1 as the animator to produce a static sprite, should the mod creator prefer consistency. This is equivalent to using the first form where no animator is specified.
  • Null. When null is specified for an image, that image will be fully transparent. This is used to "draw" SKYS tiles, showing the clouds in the background. It can also be used with an "underlay" as explained below to draw just the underlay terrain (eg. in AW4 SEAS variant 46, the SEAS tile with no cliffs, can be drawn as just SEAS_base by specifying null for that variant)

• "minimap": Integer. The offset of the graphic to use for this tile in the "terrain_gfx" image specified in the Minimap Graphics section above.

  • Note that this is the offset in tiles, not the offset in pixels. Offset in pixels = this value * minimap tilesize.

The above are the only three elements that should be present for every terrain. In addition, terrain can have the following elements:

• "panel_variant": Integer. The index of the variant in the "gfx" array to use in the terrain choice panel in the editor.

• "underlay": String. The name of the terrain to draw underneath this terrain. This is rarely used in AW1-3, but used extensively in AW4. For example, most of the AW4 land terrain has "PLIN" as an underlay because of the way PLIN tiles have random variants in AW4.

  • Note that this is in some cases can be a chain, BRDG(S) has an underlay of "SEAS", which in turn has an underlay of "SEAS_base". This is due to the cliffs in SEAS tiles having different animation timings to the water itself.

• "panel_underlay": Array. The tile(s) to draw underneath this tile in the terrain choice panel. Each array element is either:

  • String. The name of the terrain to draw.
  • Array [String, Integer]. An array containing the name of the terrain to draw and the index of the specific variant to draw.

• "hide": Boolean. Whether or not to display this terrain in the terrain choice panel, thus allowing this terrain to be placed. This allows for the aforementioned SEAS_base tile in AW4 to exist without it being placeable, and is also used to allow the SKYS tile to have a panel icon.

In addition to the above, there are two more elements that are used to define the connection information:

• "connections": Object. An object that specifies what tiles to look for when determining what tile variant to draw.

  • "<char>": Array [String, ...]. <char> is a character that represents some terrain type (or types). The array contains the names of the terrain which are represented by this character. For example, "S": ["SEAS", "REEF"] means that in the section described below, "S" represents either a SEAS tile or a REEF tile.
    • Note that in the terrain array, "MAP_BORDER" can be used if the tile should connect to the edge of the map. This is primarily used for SEAS tiles.

• "connection_variants": Array. Here, the connections that create specific variants of this terrain are specified. This section can be quite complex, particularly for the water tiles. Each element of the "connection_variants" array consists of an integer followed by one or more connections.

  • Integer. The index of the variant in the "gfx" array for this tile.
    • Note that multiple entries pointing to the same variant can exist, if for example a tile should use a specific variant if there is terrain X to the north OR terrain Y to the south.
  • One or more connections are then specified. Each connection is represented by an Array [Integer, Integer, String].
    • The two integers are the X-offset and Y-offset of the tile to test.
    • The string is one of the <char>s specified above in the "connections" section above.
      • Note that "!" can be used as a prefix for negation if the variant should be used if the tile specified is not in the array specified by \<char\>

As an example to illustrate this:

"gfx": [
    "MNTN/MNTN1.png",
    "MNTN/MNTN2.png"
],
"connections": {
    "L": ["PLIN", "MNTN"]
},
"connection_variants": [
    [1, [0, -1, "!L"]]
]

In the above example, if the tile at X=0 and Y=-1 relative to the current tile (in other words, the tile to the North) is a MNTN, then the connection is false (note the negation). As a result, the "MNTN/MNTN2.png" variant is used. If the negation was not present, then "MNTN/MNTN2.png" would be used only if the tile to the North was a PLIN or a MNTN tile.

Additional notes:

• In cases where multiple connections are present in a single "connection_variants" entry, all connection tests must pass for the variant to be used.
• In cases where multiple "connection_variants" entries would be valid, whichever one appears last in the array is used.
• Offsets other than +-1 can be used. For example, in AW2, PIPE tiles connect to the top of a BHFT tile. Since the BHFT tile uses the bottom right corner as its "anchor point", the offset to test in this case is (1, 4)

Properties and Inventions

"properties": Array [Object, ...]. An array of objects, one for each property and invention present in the mod.

Properties are very similar to terrain, with some minor differences. As with terrain, the following three elements are required.

• "name": String. Same as terrain.
• "gfx": Array. Same as terrain.
• "minimap": In the case of properties, the minimap can take two forms:
  • Integer. Same as terrain.
  • Array [Integer, ...]. An array containing w*h elements, where w*h are the width and height of the property. This is used in the case of inventions, as different parts of the invention might have different minimap graphics (eg. weak point on BHCN-S etc.)

The following elements behave the same way for properties as they do for terrain:

• "panel_variant": Integer.
• "underlay": String.
• "panel_underlay": Array.
• "hide": Boolean.
• "connections": Object.
• "connection_variants": Array.

In addition, properties can also have the following elements:

• "width": Integer. The width of the property, in tiles. Used for inventions.
• "height": Integer. The height of the property, in tiles. Used for inventions.
• "force_owner": String. Used to specify when a property should always be owned by a particular faction. For example, PIPS, SILO and PLTF are always neutral. This is not required if a property is marked as...
• "extra": String. The faction which should be selected to display this property in the "Extra" tab of the terrain choice panel.
• "production": Array [String, ...]. Array containing "LAND", "SEA" and/or "AIR" depending on what type(s) of units this property can produce
• "owner_variants": Array. Allows for variants to be specified for when the property is owned by a particular faction.
  • Similar to how "connection_variants" works, each element of "owner_variants" consists of an array containing an integer and another array.
    • Integer. The index of the variant in the "gfx" array for this tile.
    • Array [String]. An array containing a single string, the faction which matches the specified property variant.
      • Note that this is a string in an array, this is because at some point I intend to merge "faction_variants" and "connection_variants" into a single "variants" element allowing for both an owner and connections to be specified.

Units

"units": Array [Object, ...]. An array of objects, one for each unit present in the mod.

Similar in format to terrain and properties, but with only a few of the elements.

• "name": String. Same as terrain.
• "gfx": Array. Same as terrain.
• "owner_variants": Array. Same as properties.