One more documentation update iteration

config/commanders.json

@@ -29,7 +29,7 @@
 		{"ability": ["BLOCKS_RETALIATION", 0, 1, 0 ], "skills": [0,5]},
 		{"ability": ["UNLIMITED_RETALIATIONS", 0, 0, 0 ], "skills": [1, 2]},
 		{"ability": ["ATTACKS_ALL_ADJACENT", 0, 0, 0 ], "skills": [1, 3]},
-		{"ability": ["BLOCK", 30, 0, 0 ], "skills": [1, 4]},
+		{"ability": ["NONE", 30, 0, 0 ], "skills": [1, 4]}, // TODO: Implement bonus that gives chance to completely block one enemy attack per turn
 		{"ability": ["FIRE_SHIELD", 1, 1, 0 ], "skills": [1, 5]},
 		{"ability": ["ADDITIONAL_ATTACK", 1, 0, 0 ], "skills": [2, 3]},
 		{"ability": ["HP_REGENERATION", 50, 0, 0 ], "skills": [2, 4]},

config/schemas/battlefield.json

@@ -8,7 +8,7 @@
 	"properties" : {
 		"name" : {
 			"type" : "string",
-			"description" : "Name of the battleground"
+			"description" : "Human-readable name of the battlefield"
 		},
 		"isSpecial" : {
 			"type" : "boolean",
@@ -16,17 +16,17 @@
 		},
 		"bonuses": {
 			"type":"array",
-			"description": "Bonuses provided by this battleground using bonus system",
+			"description": "List of bonuses that will affect all battles on this battlefield",
 			"items": { "$ref" : "bonus.json" }
 		},
 		"graphics" : {
 			"type" : "string",
 			"format" : "imageFile",
-			"description" : "BMP battleground resource"
+			"description" : "Background image for this battlefield"
 		},
 		"impassableHexes" : {
 			"type" : "array",
-			"description" : "Battle hexes always impassable for this type of battlefield (ship to ship for instance)",
+			"description" : "List of battle hexes that will be always blocked on this battlefield (e.g. ship to ship battles)",
 			"items" : {
 				"type" : "number"
 			}

config/schemas/hero.json

@@ -114,16 +114,17 @@
 			"properties" : { 
 				"base" : {
 					"type" : "object",
-					"description" : "Will be merged with all bonuses."
+					"additionalProperties" : true,
+					"description" : "Section that will be added into every bonus instance, for use in specialties with multiple similar bonuses."
 				},
 				"bonuses" : {
 					"type" : "object",
-					"description" : "Set of bonuses",
+					"description" : "List of bonuses added by this specialty. See bonus format for more details",
 					"additionalProperties" : { "$ref" : "bonus.json" }
 				},
 				"creature" : {
 					"type" : "string",
-					"description" : "Name of base creature to grant standard specialty to."
+					"description" : "Shortcut for defining creature specialty, using standard H3 rules."
 				}
 			}
 		},

config/schemas/heroClass.json

@@ -54,10 +54,15 @@
 			}
 		},
 		"mapObject" : {
+			// TODO: this entry should be merged with corresponding base entry in hero object type and validated as objectType
+			// "$ref" : "objectType.json",
+			"type" : "object",
 			"properties" : {
 				"filters" : {
 					"type" : "object",
-					"additionalProperties" : { "type" : "array" }
+					"additionalProperties" : { 
+						"type" : "array" 
+					}
 				}
 			}
 		},

config/schemas/obstacle.json

@@ -16,12 +16,12 @@
 	"properties" : {
 		"allowedTerrains" : {
 			"type" : "array",
-			"description" : "Obstacles can be place on specified terrains only",
+			"description" : "List of terrains on which this obstacle can be used",
 			"items" : { "type" : "string" }
 		},
 		"specialBattlefields" : {
 			"type" : "array",
-			"description" : "Obstacles can be placed on specified specified battlefields",
+			"description" : "List of special battlefields on which this obstacle can be used",
 			"items" : { "type" : "string" }
 		},
 		"absolute" : {

docs/modders/Animation_Format.md

@@ -53,6 +53,33 @@ VCMI allows overriding HoMM3 .def files with .json replacement. Compared to .def
 }
 ```
 
+# Examples
+
+## Replacing a button
+
+This json file will allow replacing .def file for a button with png images. Buttons require following images:
+0. Active state. Button is active and can be pressed by player
+1. Pressed state. Player pressed button but have not released it yet
+2. Blocked state. Button is blocked and can not be interacted with. Note that some buttons are never blocked and can be used without this image
+3. Highlighted state. This state is used by only some buttons and only in some cases. For example, in main menu buttons will appear highlighted when mouse cursor is on top of the image. Another example is buttons that can be selected, such as settings that can be toggled on or off
+
+```javascript
+	"basepath" : "interface/MyButton", // all images are located in this directory
+
+	"images" :
+	[
+		{"frame" : 0, "file" : "active.png" },
+		{"frame" : 1, "file" : "pressed.png" },
+		{"frame" : 2, "file" : "blocked.png" },
+		{"frame" : 3, "file" : "highlighted.png" },
+	]
+}
+```
+
+## Replacing creature animation
+
+TODO
+
 # Creature animation groups
 
 Animation for creatures consist from multiple groups, with each group

docs/modders/Bonus/Bonus_Updaters.md

@@ -1,5 +1,7 @@
 < [Documentation](../../Readme.md) / [Modding](../Readme.md) / [Bonus Format](../Bonus_Format.md) / Bonus Updaters
 
+TODO: this page may be incorrect or outdated
+
 # List of Bonus Updaters
 
 Updaters come in two forms: simple and complex. Simple updaters take no

docs/modders/Entities_Format/Battle_Obstacle_Format.md

@@ -1,3 +1,27 @@
 < [Documentation](../../Readme.md) / [Modding](../Readme.md) / Entities Format / Battle Obstacle Format
 
-TODO
+```jsonc
+	// List of terrains on which this obstacle can be used
+	"allowedTerrains" : []
+	
+	// List of special battlefields on which this obstacle can be used
+	"specialBattlefields" : []
+	
+	// If set to true, this obstacle will use absolute coordinates. Only one such obstacle can appear on the battlefield
+	"absolute" : false
+	
+	// Width of an obstacle, in hexes
+	"width" : 1
+	
+	// Height of an obstacle, in hexes
+	"height" : 1
+	
+	// List of tiles blocked by an obstacles. For non-absolute obstacles uses relative hex indices
+	"blockedTiles" : [ 0, 20, 50 ]
+	
+	// For absolute obstacle - image with static obstacle. For non-absolute - animation with an obstacle
+	"animation" : "",
+	
+	// If set to true, obstacle will appear in front of units or other battlefield objects
+	"foreground" : false
+```

docs/modders/Entities_Format/Battlefield_Format.md

@@ -1,3 +1,19 @@
 < [Documentation](../../Readme.md) / [Modding](../Readme.md) / Entities Format / Battlefield Format
 
-TODO
+```jsonc
+	// Human-readable name of the battlefield
+	"name" : ""
+	
+	// If set to true, obstacles will be taken from "specialBattlefields" property of an obstacle
+	// If set to false, obstacles will be taken from "allowedTerrains" instead
+	"isSpecial" : false
+	
+	// List of bonuses that will affect all battles on this battlefield
+	"bonuses" : { BONUS_FORMAT }
+	
+	// Background image for this battlefield
+	"graphics" : ""
+	
+	// List of battle hexes that will be always blocked on this battlefield (e.g. ship to ship battles)
+	"impassableHexes" : [ 10, 20, 50 ]
+```

docs/modders/Entities_Format/Hero_Class_Format.md

@@ -26,14 +26,14 @@ In order to make functional hero class you also need:
 		}
 	},
 
-	// Description of map object representing this hero class. See map template format for details
+	// Description of map object representing this hero class.
 	"mapObject" : {
 		// Optional, hero ID-base filter, using same rules as building requirements
 		"filters" : {
 			"mutare" : [ "anyOf", [ "mutare" ], [ "mutareDrake" ]]
 		},
 
-		// List of templates used for this object, normally - only one is needed
+		// List of templates used for this object, normally - only one is needed. See map template format for details
 		"templates" : {
 			"normal" : { "animation" : "AH00_.def" }
 		}

docs/modders/Entities_Format/Hero_Type_Format.md

@@ -119,14 +119,17 @@ In order to make functional hero you also need:
 
 	// Description of specialty mechanics using bonuses (with updaters)
 	"specialty" : {
-		// to be merged with all bonuses, use for specialties with multiple similar bonuses (optional)
+	
+		// Optional. Section that will be added into every bonus instance, for use in specialties with multiple similar bonuses
 		"base" : {common bonus properties},
+		
+		// List of bonuses added by this specialty. See bonus format for more details
 		"bonuses" : {
 			// use updaters for bonuses that grow with level
 			"someBonus" : {Bonus Format},
 			"anotherOne" : {Bonus Format}
 		},
-		// adds creature specialty following the HMM3 default formula
+		// Optional. Shortcut for defining creature specialty, using standard H3 rules
 		"creature" : "griffin"
 	}
 }

docs/modders/Map_Objects/Boat.md

@@ -1 +1,30 @@
-TODO
+< [Documentation](../../Readme.md) / [Modding](../Readme.md) / [Map Object Format](../Map_Object_Format.md) / Boat
+
+``` javascript
+{
+	// Layer on which this boat moves. Possible values:
+	// "land" - same rules as movement of hero on land
+	// "sail" - object can move on water and interact with objects on water
+	// "water" - object can walk on water but can not interact with objects
+	// "air" - object can fly across any terrain but can not interact with objects
+	"layer" : "",
+	
+	// If set to true, it is possible to attack wandering monsters from boat
+	"onboardAssaultAllowed" : true;
+	
+	// If set to true, it is possible to visit object (e.g. pick up resources) from boat
+	"onboardVisitAllowed" : true;
+	
+	// Path to file that contains animated boat movement
+	"actualAnimation" : "",
+	
+	// Path to file that contains animated overlay animation, such as waves around boat
+	"overlayAnimation" : "",
+	
+	// Path to 8 files that contain animated flag of the boat. 8 files, one per each player
+	"flagAnimations" : ["", "" ],
+	
+	// List of bonuses that will be granted to hero located in the boat
+	"bonuses" : { BONUS_FORMAT }
+}
+```

lib/mapObjectConstructors/CommonConstructors.cpp

@@ -180,6 +180,9 @@ void BoatInstanceConstructor::initTypeData(const JsonNode & input)
 	int pos = vstd::find_pos(NPathfindingLayer::names, input["layer"].String());
 	if(pos != -1)
 		layer = EPathfindingLayer(pos);
+	else
+		logMod->error("Unknown layer %s found in boat!", input["layer"].String());
+
 	onboardAssaultAllowed = input["onboardAssaultAllowed"].Bool();
 	onboardVisitAllowed = input["onboardVisitAllowed"].Bool();
 	actualAnimation = AnimationPath::fromJson(input["actualAnimation"]);