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

Map header

Root entry

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

// Size of the map, must match size of terrain
// TODO: allow more than two levels?
// TODO: allow varying size of levels?
"mapSize" : [ 72, 72, 2],

// 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 0
"levelLimit" : 20,

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

// Either list allowed heroes or only banned heroes.
// TODO: use only one list? Which one?
"bannedHeroes" : [ "a", "b", "c" ],
"allowedHeroes" : [ "d", "e", "f" ],

// 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> }

Player information format

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 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, 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]

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.

Objects

May have something in common with Object Format

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