Map format

From VCMI Project Wiki
Revision as of 19:55, 23 February 2016 by AVS (talk | contribs) (→‎Player information format)
Jump to: navigation, search

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, file extension .vmap
  • 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

Extensions

  • Possible future major verions of map format are out of scope in this document
  • All minor versions shall be backward and forward compatible
  • Allowed modifications:
    1. adding new attributes of any type
    2. deprecating old attributes
  • New attributes get version suffix (f.e. "field_3" where 3 is minor version introduced this field)
    • "_x" suffix indicates draft for next format revision
  • Engine discards attributes with higher version
  • Map editor preserve attributes with higher version disallowing modification
    1. [Todo] handle situation with deprecated (actually replaced) attribute edit

Map header

Root entry

  • engine [WiP]
  • editor [WiP]
//version of format itself. This field will be always present.
"versionMajor" : 1,

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


//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, //or enum EASY, NORMAL, HARD, EXPERT, IMPOSSIBLE

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

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

"teams":[<team settings 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>},

"allowedArtifacts" : {<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> },

"rumors":[
{
"name": "rumor name",
"text": "rumor text",
}
//...
],

"predefinedHeroes":{
"hero_id":{<Hero definition format>}
//...
}

Level header format

  • engine [Done] only 2 level max, same size
  • editor [Done]
"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

  • engine [WiP]
  • editor [WiP]

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

"red" :
{
	//
	"allowedFactions":{<Logical id condition>},

	"canPlay": "PlayerOnly", //PlayerOrAI(default), PlayerOnly, AIOnly

	//all heroes owned by player
	"heroes":{//todo
		"hero_1":{
			"type":"knight", 
			"name":"King Arthur"
		},
		"hero_7":{
			"type":"" //empty type(default) means random town
		}
		//...
	},
	"mainHero": "hero_1",

	"mainTown":{
		"type": "rampart", //default random
		"x":123,
		"y":31,
		"l":0,
		"generateHero": false
	}
}

Team settings format

  • engine [Done]
  • editor [Done]
[
["red", "tan"],
["blue", "purple", "green"]
]

Triggered events format

  • editor [Done]
  • engine [Done]


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

  • engine [WiP]
  • editor [Done]
"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

  • engine [WiP]
  • editor [Todo]

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
    [ "have", { "type" : "resource", "subType" : "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"
      //by map position and (optional) object type/suptype
      [ "control", { "position" : [ 1, 4, 0], "type" : "object", "subtype": "town" } ],
      //by instance id
      [ "control", { "object": "town_9" } ]
    ],

    [ "control", { "object" : "hero_42"}]
]

Hero definition format

  • editor [WiP]
  • engine [Todo]
{

	"artifacts" : {
		"backpack" : [
		],
		"feet" : "",
		"head" : "",
		"leftHand" : "",
		"leftRing" : "",
		"mach1" : "",
		"mach2" : "",
		"mach3" : "",
		"mach4" : "",
		"misc1" : "",
		"misc2" : "",
		"misc3" : "",
		"misc4" : "",
		"misc5" : "",
		"neck" : "",
		"rightHand" : "",
		"rightRing" : "",
		"shoulders" : "",
		"spellbook" : "",
		"torso" : ""
	},
	"biography" : "",
	"experience" : 0,
	
	"name" : "My hero",

		
	//optional hero id
	"portrait" : "",
			
	//optional default inherited from configuration
	"primarySkills" : {
		"attack" : 0,
		"defence" : 2,
		"knowledge" : 0,
		"spellpower" : 3
	},
			
	"secondarySkills" : {
		"leadership" : "basic"//"advanced", "expert"
		//...
	},

	//optional, default if not set
	"female" : true,//false
	"spellBook" : [
		"fortune"
		//...
	],
	//default all players
	"availableFor":["red","tan"]
}

Terrain

  • engine [Done]
  • editor [Done]

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. Terrain of each map level is stored in %levelId%_terrain.json 

[
  [ "dt37_pc14|", "sn50_pc9|", "dt12_" ],
  [ "wt26_", "wt03_pc3_", "dt12_" ],
  [ "wt64_", "wt34_pc3_", "dt12_rw4+" ]
]

Format of each individual tile is: 

[terrain code][terrain index][flip]
[P][path type][path index][flip]
[R][river type][river index][flip]

flip codes: 

_ no rotation
- left-right flip
| top-bottom flip
+ both directions

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

  • engine [Done]
  • editor [Done]

See also: Object instance format "objects.json" 

{
"town_375":{

	//appearance selected by engine if not present

	"template":{<object template format>}
	"type":"town",
	"subtype":"hota.cove:cove",

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

	"pos_x" : [x,y,l], //TODO: alternate coordinates
	"x" : 10,"y" : 6, "l": 0 //coordinates

	//future extension for scripts
	"mod_myMod_x":
	{
		//<myMod specific options>
	},
	"mod_anotherMod_x":
	{
		//<myMod specific options>
	},
	//future extension for object mixins
	"mix_identifier1_x":
	{
	//mixin type specific
	},
	"mix_identifier2_x":
	{
	//mixin type specific
	}
},
//...
}
  • instance identifier has format <object type w\o mod id> "_" <unique number>.

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
Retrieved from "https://wiki.vcmi.eu/index.php?title=Map_format&oldid=2153"