Difference between revisions of "Map format"

From VCMI Project Wiki
Jump to: navigation, search
(Root entry)
(Root entry)
Line 33: Line 33:
  
 
// Information on players placed on map, see below
 
// Information on players placed on map, see below
"players" : { <player information format> },
+
"players" : {
 +
  "color":{<player information format>}
 +
  //...
 +
},
  
 
// Either list allowed heroes or only banned heroes.
 
// Either list allowed heroes or only banned heroes.

Revision as of 14:33, 27 December 2014

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

// Lists map levels and their size
"mapLevels" : {
    "surface" : [ 72, 72, 0],
    "underground" : [ 72, 72, 1]
},

// 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" : { 
  "color":{<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" ],


"allowedAbilities" : [<list of ids>],

//TODO: also banned versions?

"allowedSpells" : [<list of ids>],


// 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 3d vector (map level, 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

"templates" : [

{
   <mostly identical to Object Format>
  //but only one "base" type in group , unnamed, no RMG or editor specific fields.
  //build-in object types are used for random objects and ignored for all other objects.
  //build-in object types are default values for map editor
}
]

"objects": [
{
	"l" : 0, //map level index
	"options" : {
		//object type specific
	},
	"templateID" : 2, //index of template in "templates"
	"x" : 10,"y" : 6 //coordinates
},


Modding related articles

Main articles
Modding changelog Modding guidelines 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