Difference between revisions of "Map format"

From VCMI Project Wiki
Jump to: navigation, search
(Logical id conditions)
(Root entry)
Line 51: Line 51:
 
  },
 
  },
  
// Either list allowed heroes or only banned heroes.
+
//  
// TODO: use only one list? Which one?
+
"allowedHeroes" : {<Logical id condition>},
"bannedHeroes" : [ "a", "b", "c" ],
 
"allowedHeroes" : [ "d", "e", "f" ],
 
  
  
"allowedAbilities" : [<list of ids>],
+
"allowedAbilities" : {<Logical id condition>},
  
//TODO: also banned versions?
 
  
"allowedSpells" : [<list of ids>],
+
"allowedSpells" : {<Logical id condition>},
  
  

Revision as of 13:54, 19 January 2015

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,

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

// Lists map levels and their size and depth
"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>} 
  //...
 },

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

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

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