Map format

This article is a proposal of new map format editor / random map genrator of modded VCMI.

Basic ideas

• Map uses Json format
• Complete map is a zip archive.
• Archive contains map split in several sections with predefined names
  • Header, corresponds to H3M header structure. Separate file is needed mostly to allow fast loading of map headers in pregame map selection
  • Terrain, each level in separate file
  • Map objects, possibly split by level as well

Base format

• zip archive
• contains header.json
• header.json contains Json object
• header object contains formatVersion field
• everything else may be changed in future
• this page describes format version 1

Map header

Root entry

//version of format itself. This field will be always present.
"formatVersion" : 1,

//maps with same version and different revisions are backward compatible (todo: forward compatibility)
"formatRevison": 0,

// vcmi version that was used to create the map.
"engineVersion" : "0.95",

//list of mods required to run this map
//todo: use mod versions
//all "required" mods must be loaded to play this map (f.e. mod with faction used in map)
//if any of "banned" mods are enabled map cant be loaded (f.e. known conflict with map`s scrpited mechanics)
//"allowed" mods are not required, just information that these mods are tested with this map

//map objects can only include/use objects from "required" mods.
//map scripts may also use "allowed" mods (assumed that they check presence of particular mod)

"mods" : {<Logical id condition>},

// Lists map levels and their size and depth
"mapLevels" : {
    "surface" : {<Level header format>},
    "underground" : {<Level header format>}
},

// Human-readable name of the map
"name" : "Test map",

// Human-readable description of the map
"description" : "Long description of completely useless testing map",

// Map difficulty. Represented as percentage?
"difficulty" : 100,

// Maximum level that hero can reach on this map. Optional, default is 199 (internal engine limitation)
"levelLimit" : 20,

// Information on players placed on map, see below
"players" : { 
  "color":{<player information format>} 
  //...
 },

// list of allowed/banned heroes, abilities, spells.  "allOf" aka "required" part of condition as treated as "allowed" and not recommended to use
"allowedHeroes" : {<Logical id condition>},


"allowedAbilities" : {<Logical id condition>},


"allowedSpells" : {<Logical id condition>},


// Text for victory conditions on map selection screen.
"victoryString" : "Defeat all enemies or find artifact",
// Icon, indicates index of frame in SCNRVICT.DEF file
"victoryIconIndex" : 12,

// Text for defeat conditions on map selection screen.
"defeatString" : "Lose your capital Steadwick or your hero Roland",
// Icon, indicates index of frame in SCNRLOSS.DEF file
"defeatIconIndex" : 1,

// list of triggered events that denote computer-readable victory/defeat conditions
"triggeredEvents" : { <list of triggered events, see below> }

Level header format

"surface" :
{

	//mandatory; level height in tiles
	"height": 72,

	//mandatory; level width in tiles
	"width": 72,

	//mandatory, unique; coordinate of this level
	"index": 0, //0=surface, 1 underground.
}

Player information format

Player color names red, blue, tan, green, orange, purple, teal, pink

"red" :
{
	//TODO
}

Triggered events format

// Unique identifier of an event
"findTheBlade" :
{
	// Logical condition for this event to trigger, see below
	"condition" : [ "logical expression code" ],

	// TODO: Long description of this event/quest, will be displayed in quest window
	"description" : "Find ancient artifact, Armageddon's Blade to claim victory!",

	// Message that will be displayed to player that have triggered this event
	"message" : "You have found Armageddon's Blade. You won!",

	// Effect caused by this event, right now only win/loss effects are supported
	"effect" :
	{
		// Type of effect, can be either "victory" or "defeat"
		"type" : "victory",

		// Message that will be send to the rest of players to explain what happened
		"messageToSend" : "Enemy found AB. All is lost!"
	}
}

Logical id conditions

"condition"
{
    //these ids are allowed, default defined by handler
    "anyOf":
    [ "id1", "id2" ],

    //these ids are required, default none. automatically added to allowed
    "allOf":
    [ "id3", "id4" ],

    //these ids are banned, default none, has priority over allowed and required.
    "noneOf":
    [ "id4", "id5" ],
}

Logical event conditions

Logical conditions for map events use same base system as buidings but with different base element. See List of all event conditions for possible elements for these expressions.

"condition"
[
    // To fulfill, all of below must be true
    "allOf",
    // 1) Have 100'000 gold
    [ "haveResources", { "type" : "resource.gold", "value" : 100000 }],
    // 2) 60 days have not passed since game start (aka time expires loss condition)
    [
      "noneOf",
      [ "daysPassed", { "value" : 60 } ]
    ],
    // 3) Player must control at least one of towns at positions specified below
    [
      "anyOf"
      [ "control", { "position" : [ 1, 4,0], "type" : "object.town" } ],
      [ "control", { "position" : [10,25,0], "type" : "object.town" } ]
    ]
]

Terrain

Represented as Json 2d vector (row, column), each tile is encoded string in order to keep map as small as possible. Encoding map using full Json format is not an option due to loading speed.

[
  [ "dt10", "dt13pc3", "dt12" ],
  [ "wt26", "wt03pc3", "dt12" ],
  [ "wt64", "wt34pc3", "dt12rw4" ]
]

Format of each individual tile is:

[terrain code][terrain index]
[P][path type][path index]
[R][river type][river index]
[F][flags as uint8]

First part is obligatory 2-letter code of terrain (e.g. dt for Dirt) and index of frame in animation file for this tile. Second part is optional description of path present on tile (e.g. cobblestone road will be encoded as "pc" - path cobblestone) with frame index similar to terrain. Third optional part describes rivers on this tile (e.g. normal river will be encoded as "rw" - river water), following frame index. "Flags" used if not 0 contains rotation for terrain, path & river.

Terrain codes

• DIRT - dt
• SAND - sa
• GRASS - gr
• SNOW - sn
• SWAMP - sw
• ROUGH - rg
• SUBTER. - sb
• LAVA - lv
• WATER - wt
• ROCK - rc

Road codes

• dirt - pd
• grazvel - pg
• cobblestone - pc

River codes

• water - rw
• icy - ri
• moddy - rm
• lava - rl

Objects

"objects.json"

[
{
	//appearance selected by engine if not present

	"template":{<object template format>}
	"type":"objecttype",
	"subtype":"someMod:objectSubtype",

	"options" : {
		//object type specific
	},

	"x" : 10,"y" : 6 //coordinates
},
[...]
],

Technical details

Object identification

• Regardless of mod from which map came from, map considered to be part of "core" mod. So all string ids except ones from core are namespaced with mod name.

Modding related articles

Main articles
Modding changelog	Modding guidelines	How to create a town mod	Mod Handler

Formats
	Mod file Format
Town Format	Creature Format	Hero Classes Format
Artifact Format	Animation Format	Hero Format
Bonus Format	Object Format	Spell Format

Work-in-progress formats
Building bonuses		Map format
	Bonus Type Format	Random map template

Outdated pages
	Mod system proposal