Updated schemas & docs for several game entities

config/factions/neutral.json

@@ -5,6 +5,7 @@
 		"index" : 9,
 		"nativeTerrain" : "none",
 		"alignment" : "neutral",
+		"boat" : "boatFortress",
 		"creatureBackground" :
 		{
 			"120px" : "TPCASNEU",

config/schemas/artifact.json

@@ -123,7 +123,7 @@
 		},
 		"onlyOnWaterMap" : {
 			"type" : "boolean",
-			"description" : "It true, artifact won't spawn on a map without water"
+			"description" : "If set to true, artifact won't spawn on a map without water"
 		}
 	}
 }

config/schemas/creature.json

@@ -23,7 +23,7 @@
 		},
 		"disabled" : {
 			"type" : "boolean",
-			"description" : "Object is competely disabled and may not be even loaded in-game"
+			"description" : "Internal. Object is competely disabled and may not be even loaded in-game"
 		},
 		"name" : {
 			"type" : "object",
@@ -122,26 +122,22 @@
 				"$ref" : "bonus.json"
 			}
 		},
-		"abilityText" : {
-			"type" : "string",
-			"description" : "Text version of creature abilities. Used only with original creature window"
-		},
 		"graphics" : {
 			"type" : "object",
 			"additionalProperties" : false,
-			"description" : "Describes how this creature looks like during battles",
+			"description" : "Describes how this creature looks like",
 			"required" : [
 				"animation", "animationTime", "timeBetweenFidgets"
 			],
 			"properties" : {
 				"animation" : {
 					"type" : "string",
-					"description" : ".def file with animation of this creature in battles",
+					"description" : "File with animation of this creature in battles",
 					"format" : "defFile"
 				},
 				"map" : {
 					"type" : "string",
-					"description" : ".def file with animation of this creature on adventure map",
+					"description" : "File with animation of this creature on adventure map",
 					"format" : "defFile"
 				},
 				"mapMask" : {
@@ -247,7 +243,7 @@
 						},
 						"attackClimaxFrame" : {
 							"type" : "number",
-							"description" : "Frame from attack animation during which creature deals damage"
+							"description" : "Frame at which shooter shoots his projectile (e.g. releases arrow)"
 						}
 					}
 				},
@@ -264,7 +260,7 @@
 		"sound" : {
 			"type" : "object",
 			"additionalProperties" : false,
-			"description" : "Various sound files associated with this creature",
+			"description" : "Sound files associated with this creature",
 			"properties" : {
 				"attack" :      { "type" : "string", "format" : "soundFile" },
 				"defend" :      { "type" : "string", "format" : "soundFile" },

config/schemas/faction.json

@@ -30,20 +30,20 @@
 	"$schema" : "http://json-schema.org/draft-04/schema",
 	"title" : "VCMI faction format",
 	"description" : "Json format for defining new faction (aka towns) in VCMI",
-	"required" : [ "name", "alignment", "nativeTerrain", "creatureBackground" ],
+	"required" : [ "name", "boat", "alignment", "nativeTerrain", "creatureBackground" ],
 	"dependencies" : {
-		"town" : [ "puzzleMap", "boat" ]
+		"town" : [ "puzzleMap" ]
 	},
 	"additionalProperties" : false,
 	"properties" : {
 		"name" : {
 			"type" : "string",
-			"description" : "Translatable name of town"
+			"description" : "Localizable faction name, e.g. Rampart"
 		},
 		"alignment" : {
 			"type" : "string",
 			"enum" : [ "good", "neutral", "evil" ],
-			"description" : "Town alignment, good, neutral or evil"
+			"description" : "Faction alignment, good, neutral or evil"
 		},
 		"nativeTerrain" : {
 			"type" : "string",
@@ -51,12 +51,12 @@
 		},
 		"boat" : {
 			"type" : "string",
-			"description" : "Identifier of boat type that is produced by shipyard in town, if any"
+			"description" : "Identifier of boat type that is produced by shipyard and used by heroes in water taverns or prisons"
 		},
 
 		"preferUndergroundPlacement" : {
 			"type" : "boolean",
-			"description" : "Random map generator places player/cpu-owned towns underground if true is specified and on the ground otherwise. Parameter is unused for maps without underground. False by default."
+			"description" : "Random map generator places player/cpu-owned towns underground if true is specified and on the ground otherwise. Parameter is unused for maps without underground."
 		},
 		"creatureBackground" : {
 			"type" : "object",
@@ -173,7 +173,7 @@
 				},
 				"buildingsIcons" : {
 					"type" : "string",
-					"description" : "Path to .def file with building icons",
+					"description" : "Path to building icons for town hall",
 					"format" : "animationFile"
 				},
 				"mapObject" : {

config/schemas/hero.json

@@ -16,19 +16,19 @@
 	"properties" : {
 		"special" : {
 			"type" : "boolean",
-			"description" : "Marks this object as special and not available by default"
+			"description" : "If set to true hero will be unavailable on start and won't appear in taverns (campaign heroes)"
 		},
 		"class" : {
 			"type" : "string",
-			"description" : "Hero class, e.g. knight or battleMage"
+			"description" : "Identifier of class this hero belongs to. Such as knight or battleMage"
 		},
 		"female" : {
 			"type" : "boolean",
-			"description" : "This hero is female (changeable via editor)"
+			"description" : "Set to true if the hero is female by default (can be changed in map editor)"
 		},
 		"battleImage" : {
 			"type" : "string",
-			"description" : "Custom def used on battle",
+			"description" : "Custom animation to be used on battle, overrides hero class property",
 			"format" : "defFile"
 		},
 		"images" : {
@@ -174,11 +174,11 @@
 		},
 		"onlyOnWaterMap" : {
 			"type" : "boolean",
-			"description" : "It true, hero won't show up on a map with water"
+			"description" : "If set to true, hero won't show up on a map with water"
 		},
 		"onlyOnMapWithoutWater" : {
 			"type" : "boolean",
-			"description" : "It true, hero will show up only if the map contains no water"
+			"description" : "If set to true, hero will show up only if the map contains no water"
 		}
 	}
 }

config/schemas/heroClass.json

@@ -16,7 +16,7 @@
 		},
 		"faction" : {
 			"type" : "string",
-			"description" : "Faction this hero class belongs to"
+			"description" : "Identifier of faction this class belongs to"
 		},
 		"affinity" : {
 			"type" : "string",

config/schemas/skill.json

@@ -15,7 +15,7 @@
 				},
 				"images" : {
 					"type" : "object",
-					"description" : "skill icons of varying size",
+					"description" : "Skill icons of varying size",
 					"properties" : {
 						"small" : {
 							"type" : "string",
@@ -47,11 +47,11 @@
 	"properties" : {
 		"name" : {
 			"type" : "string",
-			"description" : "localizable skill name"
+			"description" : "Mandatory, localizable skill name"
 		},
 		"index" : {
 			"type" : "number",
-			"description" : "numeric id of skill, required for existing skills"
+			"description" : "Internal, numeric id of skill, required for existing skills"
 		},
 		"obligatoryMajor" : {
 			"type" : "boolean",
@@ -63,22 +63,16 @@
 		},
 		"gainChance" : {
 			"description" : "Chance for the skill to be offered on level-up (heroClass may override)",
-			"anyOf" : [
-				{
-					"type" : "number"
-				},
-				{
-					"type" : "object",
-					"required" : ["might", "magic"],
-					"properties" : {
-						"might" : {
-							"type" : "number",
-							"description" : "Chance for hero classes with might affinity"
-						},
-						"magic" : {
-							"type" : "number",
-							"description" : "Chance for hero classes with magic affinity"
-						}
+				"type" : "object",
+				"required" : ["might", "magic"],
+				"properties" : {
+					"might" : {
+						"type" : "number",
+						"description" : "Chance for hero classes with might affinity"
+					},
+					"magic" : {
+						"type" : "number",
+						"description" : "Chance for hero classes with magic affinity"
 					}
 				}
 			]

config/schemas/townBuilding.json

@@ -27,11 +27,11 @@
 			"description" : "Numeric identifier of this building"
 		},
 		"name" : {
-			"description" : "Name of this building",
+			"description" : "Localizable name of this building",
 			"type" : "string"
 		},
 		"description" : {
-			"description" : "Full decsription of this building",
+			"description" : "Localizable decsription of this building",
 			"type" : "string"
 		},
 		"type" : {
@@ -53,13 +53,13 @@
 			"description" : "List of town buildings that must be built before this one"
 		},
 		"upgrades" : {
-			"description" : "If this building is upgrade, identifier of base building",
+			"description" : "Optional, indicates that this building upgrades another base building",
 			"type" : "string"
 		},
 		"cost" : {
 			"type" : "object",
 			"additionalProperties" : false,
-			"description" : "Cost to build this building",
+			"description" : "Resources needed to build building",
 			"properties" : {
 				"gold" :    { "type" : "number"},
 				"wood" :    { "type" : "number"},
@@ -69,11 +69,11 @@
 				"crystal" : { "type" : "number"},
 				"gems" :    { "type" : "number"}
 			}
-	    },		
+		},
 		"produce" : {
 			"type" : "object",
 			"additionalProperties" : false,
-			"description" : "Resources this building produce each day",
+			"description" : "Resources produced each day by this building",
 			"properties" : {
 				"gold" :    { "type" : "number"},
 				"wood" :    { "type" : "number"},

config/schemas/townStructure.json

@@ -21,7 +21,7 @@
 		},
 		"area" : {
 			"type" : "string",
-			"description" : "Area that indicate when building is selected. Must be 8-bit image",
+			"description" : "Area that indicate when building is selected.",
 			"format" : "imageFile"
 		},
 		"border" : {

docs/modders/Entities_Format/Artifact_Format.md

@@ -2,10 +2,6 @@
 
 Artifact bonuses use [Bonus Format](../Bonus_Format.md)
 
-TODO:
-
--   Artifacts growing with Commander level
-
 ## Required data
 
 In order to make functional artifact you also need:
@@ -16,50 +12,72 @@ In order to make functional artifact you also need:
 
 ## Format
 
-``` javascript
+``` jsonc
 {
-	//what kind of bearer can use this artifact
+	// Type of this artifact - creature, hero or commander
 	"type": ["HERO", "CREATURE", "COMMANDER"] 
 	
-	//TREASURE, MINOR, MAJOR, RELIC, SPECIAL
+	// TREASURE, MINOR, MAJOR, RELIC, SPECIAL
 	"class": "TREASURE",
 	
-	//SHOULDERS, NECK, RIGHT_HAND, LEFT_HAND, TORSO, RIGHT_RING, LEFT_RING, FEET, MISC1, MISC2, MISC3, MISC4,
-	//MACH1, MACH2, MACH3, MACH4, SPELLBOOK, MISC5
-	//also possible MISC, RING 
+	// Slot(s) to which this artifact can be put, if applicable
+	// SHOULDERS, NECK, RIGHT_HAND, LEFT_HAND, TORSO, RIGHT_RING, LEFT_RING, FEET, MISC1, MISC2, MISC3, MISC4,
+	// MACH1, MACH2, MACH3, MACH4, SPELLBOOK, MISC5
+	// MISC, RING 
 	"slot":	"HEAD", 
+	"slot":	[ "LEFT_HAND", "RIGHT_HAND ],
 
-	//based on ARTRAITS.txt		
+	// Cost of this artifact, in gold
 	"value": 12000, 
 
 	"text":
 	{
+		// Name of the artifact
 		"name": "Big Sword",
+		
+		// Long description of this artifact
 		"description": "Big sword gived +10 attack to hero",
+		
+		// Text that visible on picking this artifact on map
 		"event": "On your travel, you stumble upon big sword. You dust it off and stick in your backpack"
 	},
 	"graphics":
 	{
+		// Base image for this artifact, used for example in hero screen
 		"image": "BigSword.png",
+
+		// Large image, used for drag-and-drop and popup messages
 		"large": "BigSword_large.png",
+
 		//def file for adventure map
 		"map": "BigSword.def"
 	},
+
+	// Bonuses provided by this artifact using bonus system
 	"bonuses":
 	{
 		Bonus_1,
 		Bonus_2
 	},
-	
-	//optional, for combined artifacts only
+
+	// Optional, list of components for combinational artifacts
 	"components": 
 	[
 		"artifact1",
 		"artifact2",
 		"artifact3"
 	],
-	
-	//if set with artifact works like war machine
+
+	// Creature id to use on battle field. If set, this artifact is war machine
 	"warMachine" : "some.creature" 
+
+	// If set to true, artifact won't spawn on a map without water
+	"onlyOnWaterMap" : false,
+
+	// TODO: document
+	"growing" : {
+		"bonusesPerLevel" : {},
+		"thresholdBonuses" : {},
+	}
 }
-```
+```

docs/modders/Entities_Format/Creature_Format.md

@@ -25,7 +25,7 @@ In order to make functional creature you also need:
 // camelCase unique creature identifier
 "creatureName" : 
 {
-	// translatable names
+	// Translatable names for this creature
 	"name" :
 	{
 		"singular" : "Creature",
@@ -33,12 +33,13 @@ In order to make functional creature you also need:
 	},
 	"level" : 0,
 
-	// if set to true creature will not appear in-game randomly (e.g. as neutral creature)
+	// Marks this object as special and not available by default
 	"special" : true, 
-	
-	// config name of faction. Examples: castle, rampart
+
+	// Faction this creature belongs to. Examples: castle, rampart
 	"faction" : "", 
-	// cost to recruit, zero values can be omitted.
+
+	// Cost to recruit this creature, zero values can be omitted.
 	"cost" : 
 	{
 		"wood" : 0,
@@ -52,75 +53,80 @@ In order to make functional creature you also need:
 	// "value" of creature, used to determine for example army strength
 	"fightValue" : 0,
 
-	// "ai value" - how valuable this creature should be for AI
+	// Describes how valuable this creature is to AI. Usually similar to fightValue
 	"aiValue" : 0,
 	
-	// normal growth in town or external dwellings
+	// Basic growth of this creature in town or in external dwellings
 	"growth" : 0,
 	
-	// growth bonus from horde building
-	// TODO: reconsider need of this field after configurable buildings support
+	// Bonus growth of this creature from built horde
 	"hordeGrowth" : 0,
 	
 	// Creature stats in battle
 	"attack" : 0,
 	"defense" : 0,
 	"hitPoints" : 0,
-	"shots" : 0,
 	"speed" : 0,
 	"damage" :
 	{
 		"min" : 0,
 		"max" : 0
 	},
-	// spellpoints this creature has, how many times creature may cast its spells
+
+	// Number of shots this creature has, required only for ranged units
+	"shots" : 0,
+
+	// Spell points this creature has (usually equal to number of casts)
 	"spellPoints" : 0,
-	// initial size of creature army on adventure map
+
+	// Initial size of random stacks on adventure map
 	"advMapAmount" :
 	{
 		"min" : 0,
 		"max" : 0
 	},
 	
-	// Creature to which this creature can be upgraded
-	// Note that only one upgrade can be available from UI
+	// List of creatures to which this one can be upgraded
 	"upgrades" :
 	[
 		"anotherCreature"
 	],
 
-	// Creature is 2-tiles in size on the battlefield
+	// If set, creature will be two tiles wide on battlefield
 	"doubleWide" : false,
 
-	// All creature abilities, using bonus format
+	// Creature abilities described using Bonus system
 	"abilities" :
 	[
 		"someName1" : Bonus Format,
 		"someName2" : Bonus Format
 	],
 
+	// creature may receive "week of" events
 	"hasDoubleWeek": true,
 	
 	"graphics" :
 	{
-		// name of file with creature battle animation
+		// File with animation of this creature in battles
 		"animation" : "",
-		// adventure map animation def
+		// File with animation of this creature on adventure map
 		"map" : "",
-		// path to small icon for tooltips & hero exchange window
+		// Optional. Object mask that describes on which tiles object is visible/blocked/activatable
+		"mapMask" : [ "VV", "VA" ],
+
+		// Small icon for this creature, used for example in exchange screen
 		"iconSmall" : "",
-		// path to large icon, used on town screen and in hero screen
+		// Large icon for this creature, used for example in town screen
 		"iconLarge" : "",
 		
 		// animation parameters
 
 		// how often creature should play idle animation
 		"timeBetweenFidgets" : 1.00,
-		// unused H3 property
-		"troopCountLocationOffset" : 0,
+
 		"animationTime" :
 		{
-			// movement animation time.
+			// movement animation time factor
 			"walk" : 1.00,
 
 			// idle animation time. For H3 creatures this value is always 10
@@ -128,19 +134,15 @@ In order to make functional creature you also need:
 
 			// ranged attack animation time. Applicable to shooting and casting animation
 			// NOTE: does NOT affects melee attacks
-			// This is H3 behaviour, for proper synchronization of attack/defense animations
+			// This is H3 behaviour, likely for proper synchronization of attack/defense animations
 			"attack" : 1.00,
-
-			// How far flying creature should move during one "round" of movement animation
-			// This is multiplier to base value (200 pixels)
-			"flight" : 1.00
 		},
 		"missile" :
 		{
 			// name of file for missile
 			"animation" : "", 
 
-			// (VCMI 1.1 or later only) indicates that creature uses ray animation for ranged attacks instead of missile image (e.g. Evil Eye)
+			// indicates that creature uses ray animation for ranged attacks instead of missile image (e.g. Evil Eye)
 			"ray" : 
 			[
 				{ // definition of first (top-most) line in the ray
@@ -153,7 +155,7 @@ In order to make functional creature you also need:
 			// Frame at which shooter shoots his projectile (e.g. releases arrow)
 			"attackClimaxFrame" : 0,
 
-			// offsets between position of shooter and position where projectile should appear
+			// Position where projectile image appears during shooting in specific direction
 			"offset" :
 			{
 				"upperX" : 0,
@@ -190,6 +192,19 @@ In order to make functional creature you also need:
 		// Creature start/end movement or teleports
 		"startMoving" : "",
 		"endMoving" : ""
-	}
+	},
+	
+	// Stack experience, using bonus system
+	"stackExperience" : [
+		{
+			// Bonus description
+			"bonus" : { BONUS_FORMAT },
+			// Per-level value of bonus. Must have 10 elements
+			"values" : [
+				0, 0, 1, 1, 2, 2, 3, 3, 4, 4
+			]
+		},
+		...
+	]
 }
 ```

docs/modders/Entities_Format/Faction_Format.md

@@ -12,16 +12,12 @@ In order to make functional town you also need:
 -   Mage guild window view (1 image)
 -   Town hall background (1 image)
 
-<!-- -->
-
 -   Set of town icons, consists from all possible combinations of: (8
     images total)
     -   small and big icons
     -   village and fort icons
     -   built and normal icons
 
-<!-- -->
-
 -   Set for castle siege screen, consists from:
     -   Background (1 image)
     -   Destructible towers (3 parts, 3 images each)
@@ -49,18 +45,18 @@ Each town requires a set of buildings (Around 30-45 buildings)
 
 ## Faction node (root entry for town configuration)
 
-``` javascript
-// Unique faction identifier. Should be unique.
-"myTown" :
+```jsonc
+// Unique faction identifier.
+"myFaction" :
 {
 	// Main part of town description, see below
 	// Optional but it should be present for playable faction
 	"town" : { ... },
 
-	// Native terrain for this town. See config/terrains.json for identifiers
+	// Native terrain for creatures. Creatures fighting on native terrain receive several bonuses
 	"nativeTerrain" : "grass",
 
-	// Localizable town name, e.g. "Rampart"
+	// Localizable faction name, e.g. "Rampart"
 	"name" : "", 
 
 	// Faction alignment. Can be good, neutral (default) or evil.
@@ -72,7 +68,13 @@ Each town requires a set of buildings (Around 30-45 buildings)
 		// Paths to background images
 		"120px" : "",
 		"130px" : ""
-	}
+	},
+	
+	// Identifier of boat type that is produced by shipyard and used by heroes in water taverns or prisons
+	"boat" : "boatFortress",
+	
+	// Random map generator places player/cpu-owned towns underground if true is specified and on the ground otherwise. Parameter is unused for maps without underground.
+	"preferUndergroundPlacement" : false
 
 	// Town puzzle map
 	"puzzleMap" :
@@ -98,17 +100,9 @@ Each town requires a set of buildings (Around 30-45 buildings)
 
 ## Town node
 
-``` javascript
+```jsonc
 {
-	// DEPRECATED, see "mapObject" field below | Path to images of object on adventure map
-	"adventureMap" : 
-	{
-		"village": "", // village without built fort
-		"castle" : "", // town with built fort
-		"capitol": ""  // town with capitol (usually have some additional flags)
-	},
-
-	// field that describes behavior of map object part of town. Town-specific part of object format
+	// Field that describes behavior of map object part of town. Town-specific part of object format
 	"mapObject" : 
 	{
 		// Optional, controls what template will be used to display this object.
@@ -174,21 +168,20 @@ Each town requires a set of buildings (Around 30-45 buildings)
 	// Small scenery for window in mage guild screen
 	"guildWindow": "",
 
-	// Background image for window in mage guild screen - since 0.95b
+	// Background image for window in mage guild screen
 	"guildBackground" : "",
 
-	// Video for tavern window - since 0.95b
+	// Video for tavern window
 	"tavernVideo" : "",
 	
-	// Building icons for town hall
+	// Path to building icons for town hall
 	"buildingsIcons": "HALLCSTL.DEF", 
 
 	// Background image for town hall window
 	"hallBackground": "",
 
 	// List of buildings available in each slot of town hall window
-	// As in most cases there is no hard limit on number of columns, rows
-	// or items in any of them, but size of gui is limited to 5 rows and 4 columns
+	// Note that size of gui is limited to 5 rows and 4 columns
 	"hallSlots": 
 	[
 		[ [ "buildingID1" ], [ "buildingID2", "buildingID3" ] ],
@@ -232,19 +225,16 @@ Each town requires a set of buildings (Around 30-45 buildings)
 	// Chance of specific spell to appear in mages guild of this town
 	// If spell is missing or set to 0 it will not appear unless set as "always present" in editor
 	// Spells from unavailable levels are not required to be in this list
-	// TODO: Mirrored version of field "guildSpells" from spell format
 	"guildSpells" :
 	{
 		"magicArrow" : 30,
 		"bless"  : 10
 	},
 
-	// TODO: Entries below should be replaced with autodetection
-
 	// Which tiers in this town have creature hordes. Set to -1 to disable horde(s)
 	"horde" : [ 2, -1 ], 
 
-	// Resource given by starting bonus, if not set silo will produce wood + ore
+	// Resource given by starting bonus. If not set silo will produce wood + ore
 	"primaryResource" : "gems", 
 
 	// maximum level of mage guild
@@ -252,12 +242,15 @@ Each town requires a set of buildings (Around 30-45 buildings)
 
 	// war machine produced in town
 	"warMachine" : "ballista"
+	
+	// Identifier of spell that will create effects for town moat during siege
+	"moatAbility" : "castleMoat"
 }
 ```
 
 ## Siege node
 
-``` javascript
+```jsonc
 // Describes town siege screen
 // Comments in the end of each graphic position indicate specify required suffix for image
 // Note: one not included image is battlefield background with suffix "BACK"
@@ -265,13 +258,13 @@ Each town requires a set of buildings (Around 30-45 buildings)
 	// shooter creature name
 	"shooter" : "archer",
 
-	// (VCMI 1.1 or later) Large icon of towers, for use in battle queue
+	// Large icon of towers, for use in battle queue
 	"towerIconLarge" : "",
 
-	// (VCMI 1.1 or later) Small icon of towers, for use in battle queue
+	// (Small icon of towers, for use in battle queue
 	"towerIconSmall" : "",
 
-	// prefix for all siege images. Final name will be composed as <prefix><suffix>
+	// Prefix for all siege images. Final name will be composed as <prefix><suffix>
 	"imagePrefix" : "SGCS",
 
 	// Descriptions for towers. Each tower consist from 3 parts:
@@ -302,7 +295,7 @@ Each town requires a set of buildings (Around 30-45 buildings)
 			"creature" :   { "x": 0, "y": 0}
 		},
 	},
-	//Two parts of gate: gate itself and arch above it
+	// Two parts of gate: gate itself and arch above it
 	"gate" :
 	{
 		"gate" : { "x": 0, "y": 0}, // "DRW1" ... "DRW3" and "DRWC" (rope)
@@ -317,8 +310,13 @@ Each town requires a set of buildings (Around 30-45 buildings)
 		"bottomMid" : { "x": 0, "y": 0}, // "WA31" ... "WA33"
 		"bottom"    : { "x": 0, "y": 0}  // "WA11" ... "WA13"
 	},
-	// Two pieces for moat: moat itself and shore
-	"moat" : { "x": 0, "y": 0}, // moat: "MOAT", shore: "MLIP"
+
+	// Two pieces for moat: moat itself and moat bank
+	"moat" :
+	{
+		"bank" : { "x" : 0, "y" : 0 }, // "MOAT"
+		"moat" : { "x" : 0, "y" : 0 }  // "MLIP"
+	},
 
 	// Static non-destructible walls. All of them have only one piece
 	"static" : 
@@ -337,28 +335,56 @@ Each town requires a set of buildings (Around 30-45 buildings)
 
 ## Building node
 
-``` javascript
+```jsonc
 {
+	// Numeric identifier of this building
 	"id" : 0,
+	
+	// Localizable name of this building
 	"name" : "",
+	
+	// Localizable decsription of this building
 	"description" : "",
-	"upgrades" : "baseBuilding", // optional, which building can be upgraded by this one
-	"requires" : [ "allOf", [ "mageGuild1" ], [ "tavern" ] ], // building requirements, H3-style. See below for full format.
-	"cost" : { ... }, //resources needed to buy building
-	"produce" : { ... }, //resources produced each day by building - since 0.95b
+	
+	// Optional, indicates that this building upgrades another base building
+	"upgrades" : "baseBuilding",
+	
+	// List of town buildings that must be built before this one. See below for full format
+	"requires" : [ "allOf", [ "mageGuild1" ], [ "tavern" ] ],
+	
+	// Resources needed to build building
+	"cost" : { ... }, 
+	
+	// TODO: Document me: Subtype for some special buildings
+	"type" : "",
+	
+	// TODO: Document me: Height for lookout towers and some grails
+	"height" : "average"
+	
+	// Resources produced each day by this building
+	"produce" : { ... }, 
 
 	//determine how this building can be built. Possible values are:
 	// normal  - default value. Fulfill requirements, use resources, spend one day
 	// auto    - building appears when all requirements are built
 	// special - building can not be built manually
 	// grail   - building reqires grail to be built
-	"mode" : "auto"
+	"mode" : "auto",
+	
+	// Buildings which bonuses should be overridden with bonuses of the current building
+	"overrides" : [ "anotherBuilding ]
+	
+	// Bonuses, provided by this special building on build using bonus system
+	"bonuses" : BONUS_FORMAT
+	
+	// Bonuses, provided by this special building on hero visit and applied to the visiting hero
+	"onVisitBonuses" : BONUS_FORMAT
 }
 ```
 
 Building requirements can be described using logical expressions:
 
-``` javascript
+```jsonc
 "requires" :
 [
     "allOf", // Normal H3 "build all" mode
@@ -378,13 +404,30 @@ Building requirements can be described using logical expressions:
 
 ## Structure node
 
-``` javascript
+```jsonc
 {
-	"animation" : "", // def file with animation
+	// Main animation file for this building
+	"animation" : "", 
+	
+	// Horizontal position on town screen
 	"x" : 0,
+	
+	// Vertical  position on town screen
 	"y" : 0,
-	"z" : 0, // used for blit order. Higher value places structure close to screen
-	"border" : "", // selection highlight
-	"area" : "" // used to detect building selection
+	
+	// used for blit order. Higher value places structure close to screen and drawn on top of buildings with lower values
+	"z" : 0, 
+	
+	// Path to image with golden border around building, displayed when building is selected
+	"border" : "", 
+	
+	// Path to image with area that indicate when building is selected
+	"area" : "",
+	
+	//TODO: describe me
+	"builds": "",
+	
+	// If upgrade, this building will replace parent animation but will not alter its behaviour
+	"hidden" : false 
 }
 ```

docs/modders/Entities_Format/Hero_Class_Format.md

@@ -61,8 +61,7 @@ In order to make functional hero class you also need:
 		"knowledge"  : 2
 	},
 
-	// Chance to get specific primary skill on level-up
-	// This set specifies chances for levels 2-9
+	// Chance to get specific primary skill on level-up, applicable for levels less than 10
 	"lowLevelChance" :
 	{
 		"attack"     : 15,
@@ -71,8 +70,7 @@ In order to make functional hero class you also need:
 		"knowledge"  : 25
 	},
 
-	// Chance to get specific primary skill on level-up
-	// This set specifies chances for levels starting from 10
+	// Chance to get specific primary skill on level-up, applicable for levels starting from 10
 	"highLevelChance" :
 	{
 		"attack"     : 25,
@@ -82,7 +80,7 @@ In order to make functional hero class you also need:
 	},
 
 	// Chance to get specific secondary skill on level-up
-	// Skills not listed here will be considered as unavailable, including universities
+	// All missing skills are considered to be banned, including universities
 	"secondarySkills" :
 	{
 		"pathfinding"  : 3.

docs/modders/Entities_Format/Hero_Type_Format.md

@@ -12,10 +12,10 @@ In order to make functional hero you also need:
 ``` javascript
 "myHeroName" :
 {
-	// Identifier of class. Usually camelCase version of human-readable name
+	// Identifier of class this hero belongs to. Such as knight or battleMage
 	"class" : "wizard",
 
-	// List of starting spells, if available. Will also grant spellbook
+	// List of starting spells, if available. This entry (even empty) will also grant spellbook
 	"spellbook" :
 	[
 		"magicArrow"
@@ -26,6 +26,12 @@ In order to make functional hero you also need:
 
 	// If set to true hero will be unavailable on start and won't appear in taverns (campaign heroes)
 	"special" : true,
+	
+	// If set to true, hero won't show up on a map with water
+	"onlyOnWaterMap" : false,
+	
+	// If set to true, hero will show up only if the map contains no water
+	"onlyOnMapWithoutWater" : false,
 
 	// All translatable texts related to hero
 	"texts" :
@@ -61,11 +67,10 @@ In order to make functional hero you also need:
 
 		// Small 48x32px portrait
 		"small" : "myMod/myHero/small.png"
-
-		// Class-independent animation in battle
-		"small" : "myMod/myHero/battle.def"
-
 	},
+	
+	// Custom animation to be used on battle, overrides hero class property
+	"battleImage" : "heroInBattle.def"
 
 	// Initial hero army when recruited in tavern
 	// Must have 1-3 elements
@@ -95,7 +100,7 @@ In order to make functional hero you also need:
 		}
 	],
 
-	// List of skills received by hero
+	// List of skills initially known by hero
 	// Not limited by size - you can add as many skills as you wish
 	"skills" :
 	[

docs/modders/Entities_Format/Secondary_Skill_Format.md

@@ -2,21 +2,39 @@
 
 ## Main format
 
-``` javascript
+```jsonc
 {
-    "skillName":
-    {
-        //numeric id of skill required only for original skills, prohibited for new skills
-        "index":    0,
-        //Mandatory
-        "name":     "Localizable name",
-        //optional base format, will be merged with basic/advanced/expert
-        "base":     {Skill level base format},
-        //configuration for different skill levels
-        "basic":    {Skill level format},
-        "advanced": {Skill level format},
-        "expert":   {Skill level format}
-    }
+	"skillName":
+	{
+		//Mandatory, localizable skill name
+		"name":     "Localizable name",
+
+		// Optional base format, will be merged with basic/advanced/expert
+		"base":     {Skill level base format},
+
+		// Configuration for different skill levels
+		"basic":    {Skill level format},
+		"advanced": {Skill level format},
+		"expert":   {Skill level format},
+		
+		// Chance for the skill to be offered on level-up (heroClass may override)
+		"gainChance" : {
+			// Chance for hero classes with might affinity
+			"might" : 4,
+			// Chance for hero classes with magic affinity
+			"magic" : 6,
+			// Chance for specific classes
+			"knight" : 2,
+			"cleric" : 8,
+			...
+		},
+		
+		// This skill is major obligatory (like H3 Wisdom) and is guaranteed to be offered once per specific number of levels
+		"obligatoryMajor" : false,
+		
+		// This skill is minor obligatory (like H3 Magic school) and is guaranteed to be offered once per specific number of levels
+		"obligatoryMinor" : false,
+	}
 }
 ```
 
@@ -28,19 +46,30 @@ level fields become optional if they equal "base" configuration.
 
 ## Skill level format
 
-``` javascript
+```jsonc
 {
-    //Optional, localizable description
-    //Use {xxx} for formatting
-    "description": "",
-    //Bonuses provided by skill at given level
-    //If different levels provide same bonus with different val, only the highest applies
-    "effects":
-    {
-        "firstEffect":  {bonus format},
-        "secondEffect": {bonus format}
-        //...
-    }
+	// Localizable description
+	// Use {xxx} for formatting
+	"description": "",
+
+	// Bonuses provided by skill at given level
+	// If different levels provide same bonus with different val, only the highest applies
+	"effects":
+	{
+		"firstEffect":  {bonus format},
+		"secondEffect": {bonus format}
+		//...
+	},
+	
+	// Skill icons of varying size
+	"images" : {
+		// 32x32 skill icon
+		"small" : "",
+		// 44x44 skill icon
+		"medium" : "",
+		// 82x93 skill icon
+		"large" : "",
+	}
 }
 ```
 
@@ -49,40 +78,40 @@ level fields become optional if they equal "base" configuration.
 The following modifies the tactics skill to grant an additional speed
 boost at advanced and expert levels.
 
-``` javascript
+```jsonc
 "core:tactics" : {
-    "base" : {
-        "effects" : {
-            "main" : {
-                "subtype" : "skill.tactics",
-                "type" : "SECONDARY_SKILL_PREMY",
-                "valueType" : "BASE_NUMBER"
-            },
-            "xtra" : {
-                "type" : "STACKS_SPEED",
-                "valueType" : "BASE_NUMBER"
-            }
-        }
-    },
-    "basic" : {
-        "effects" : {
-            "main" : { "val" : 3 },
-            "xtra" : { "val" : 0 }
-        }
-    },
-    "advanced" : {
-        "description" : "{Advanced Tactics}\n\nAllows you to rearrange troups within 5 hex rows, and increases their speed by 1.",
-        "effects" : {
-            "main" : { "val" : 5 },
-            "xtra" : { "val" : 1 }
-        }
-    },
-    "expert" : {
-        "description" : "{Expert Tactics}\n\nAllows you to rearrange troups within 7 hex rows, and increases their speed by 2.",
-        "effects" : {
-            "main" : { "val" : 7 },
-            "xtra" : { "val" : 2 }
-        }
-    }
+	"base" : {
+		"effects" : {
+			"main" : {
+				"subtype" : "skill.tactics",
+				"type" : "SECONDARY_SKILL_PREMY",
+				"valueType" : "BASE_NUMBER"
+			},
+			"xtra" : {
+				"type" : "STACKS_SPEED",
+				"valueType" : "BASE_NUMBER"
+			}
+		}
+	},
+	"basic" : {
+		"effects" : {
+			"main" : { "val" : 3 },
+			"xtra" : { "val" : 0 }
+		}
+	},
+	"advanced" : {
+		"description" : "{Advanced Tactics}\n\nAllows you to rearrange troups within 5 hex rows, and increases their speed by 1.",
+		"effects" : {
+			"main" : { "val" : 5 },
+			"xtra" : { "val" : 1 }
+		}
+	},
+	"expert" : {
+		"description" : "{Expert Tactics}\n\nAllows you to rearrange troups within 7 hex rows, and increases their speed by 2.",
+		"effects" : {
+			"main" : { "val" : 7 },
+			"xtra" : { "val" : 2 }
+		}
+	}
 }
 ```

lib/CCreatureHandler.cpp

@@ -566,7 +566,8 @@ std::vector<JsonNode> CCreatureHandler::loadLegacyData()
 		data["advMapAmount"]["min"].Float() = parser.readNumber();
 		data["advMapAmount"]["max"].Float() = parser.readNumber();
 
-		data["abilityText"].String() = parser.readString();
+		// unused - ability text, not used since we no longer have original creature window
+		parser.readString();
 		loadBonuses(data, parser.readString()); //Attributes
 
 		h3Data.push_back(data);