Updated map object and bonuses documentations

config/schemas/bonus.json

@@ -158,10 +158,10 @@
 			"description" : "addInfo"
 		},
 		"duration" : {
-                        "anyOf" : [
-                                { "type" : "string"},
-                                { "type" : "array", "items" : {"type" : "string"} }
-                        ],
+			"anyOf" : [
+				{ "type" : "string"},
+				{ "type" : "array", "items" : {"type" : "string"} }
+			],
 			"description" : "duration"
 		},
 		"turns" : {

config/schemas/objectTemplate.json

@@ -14,11 +14,11 @@
 		"editorAnimation" : {
 			"type" : "string",
 			"description" : "Optional path to def file with animation of this object to use in map editor",
-			"format" : "defFile"			
+			"format" : "defFile"
 		},
 		"visitableFrom" : {
 			"type" : "array",
-			"description" : "Directions from which this object is visible",
+			"description" : "Directions from which hero can visit this object",
 			"minItems" : 3,
 			"maxItems" : 3,
 			"items" : {

docs/modders/Animation_Format.md

@@ -1,13 +1,10 @@
 < [Documentation](../Readme.md) / [Modding](Readme.md) / Animation Format
 
-VCMI allows overriding HoMM3 .def files with .json replacement. Compared
-to .def this format allows:
+VCMI allows overriding HoMM3 .def files with .json replacement. Compared to .def this format allows:
 
 -   Overriding individual frames from json file (e.g. icons)
--   Modern graphics formats (targa, png - all formats supported by VCMI
-    image loader)
--   Does not requires any special tools - all you need is text editor
-    and images.
+-   Modern graphics formats (targa, png - all formats supported by VCMI image loader)
+-   Does not requires any special tools - all you need is text editor and images.
 
 # Format description
 
@@ -59,150 +56,62 @@ to .def this format allows:
 # Creature animation groups
 
 Animation for creatures consist from multiple groups, with each group
-representing specific one animation. VCMI uses groups as follows:
+representing one specific animation. VCMI uses groups as follows:
 
 **Basic animations**
 
--   \[0\] Movement: Used for creature movement
--   \[1\] Mouse over: Used for random idle movements and when mouse is
-    moved on the creature
--   \[2\] Idle: Basic animation that plays continuously when stack is
-    not acting
--   \[3\] Hitted: Animation that plays whenever stack is hit
--   \[4\] Defence: Alternative animation that plays when stack is
-    defending and was hit in melee
--   \[5\] Death: Animation that plays when stack dies
--   \[6\] Death (ranged): Alternative animation, plays when stack is
-    killed by ranged attack
+- [0] Movement: Used for creature movement
+- [1] Mouse over: Used for random idle movements and when mouse is moved on the creature
+- [2] Idle: Basic animation that plays continuously when stack is not acting
+- [3] Hitted: Animation that plays whenever stack is hit
+- [4] Defence: Alternative animation that plays when stack is defending and was hit in melee
+- [5] Death: Animation that plays when stack dies
+- [6] Death (ranged): Alternative animation, plays when stack is killed by ranged attack
 
 **Rotation animations**
 
--   \[7\] Turn left: Animation for rotating stack, only contains first
-    part of animation, with stack turning towards viewer
--   \[8\] Turn right: Second part of animation for rotating stack
--   \[9\] (unused in vcmi, present in H3 files)
--   \[10\] (unused in vcmi, present in H3 files)
+- [7] Turn left: Animation for rotating stack, only contains first part of animation, with stack turning towards viewer
+- [8] Turn right: Second part of animation for rotating stack
+- [9] (unused in vcmi, present in H3 files)
+- [10] (unused in vcmi, present in H3 files)
 
 **Melee attack animations**
 
--   \[11\] Attack (up): Attacking animation, stack facing upwards
--   \[12\] Attack (front): Attacking animation, stack facing front
--   \[13\] Attack (down): Attacking animation, stack facing downwards
+- [11] Attack (up): Attacking animation, stack facing upwards
+- [12] Attack (front): Attacking animation, stack facing front
+- [13] Attack (down): Attacking animation, stack facing downwards
 
 **Ranged attack animations**
 
--   \[14\] Shooting (up): Ranged attack animation, stack facing upwards
--   \[15\] Shooting (front): Ranged attack animation, stack facing front
--   \[16\] Shooting (down): Ranged attack animation, stack facing
-    downwards
+- [14] Shooting (up): Ranged attack animation, stack facing upwards
+- [15] Shooting (front): Ranged attack animation, stack facing front
+- [16] Shooting (down): Ranged attack animation, stack facing downwards
 
 **Special animations**
 
--   \[17\] Special (up): Special animation, used if dedicated cast or
-    group attack animations were not found
--   \[18\] Special (front): Special animation, used if dedicated cast or
-    group attack animations were not found
--   \[19\] Special (down): Special animation, used if dedicated cast or
-    group attack animations were not found
+- [17] Special (up): Special animation, used if dedicated cast or group attack animations were not found
+- [18] Special (front): Special animation, used if dedicated cast or group attack animations were not found
+- [19] Special (down): Special animation, used if dedicated cast or group attack animations were not found
 
 **Additional H3 animations**
 
--   \[20\] Movement start: Animation that plays before movement
-    animation starts.
--   \[21\] Movement end: Animation that plays after movement animation
-    ends.
+- [20] Movement start: Animation that plays before movement animation starts.
+- [21] Movement end: Animation that plays after movement animation ends.
 
 **Additional VCMI animations**
 
--   \[22\] \[VCMI 1.0\] Dead: Animation that plays when creature is
-    dead. If not present, will consist from last frame from "Death"
-    group
--   \[23\] \[VCMI 1.0\] Dead (ranged): Animation that plays when
-    creature is dead after ranged attack. If not present, will consist
-    from last frame from "Death (ranged)" group
--   \[24\] \[VCMI 1.2\] Resurrection: Animation that plays when creature
-    is resurrected. If not present, will consist from reversed version
-    of "Death" animation
+- [22] Dead: Animation that plays when creature is dead. If not present, will consist from last frame from "Death" group
+- [23] Dead (ranged): Animation that plays when creature is dead after ranged attack. If not present, will consist from last frame from "Death (ranged)" group
+- [24] Resurrection: Animation that plays when creature is resurrected. If not present, will consist from reversed version of "Death" animation
 
 **Spellcasting animations**
 
--   \[30\] \[VCMI 1.2\] Cast (up): Used when creature casts spell facing
-    upwards
--   \[31\] \[VCMI 1.2\] Cast (front): Used when creature casts spell
-    facing front
--   \[32\] \[VCMI 1.2\] Cast (down): Used when creature casts spell
-    facing downwards
+- [30] Cast (up): Used when creature casts spell facing upwards
+- [31] Cast (front): Used when creature casts spell facing front
+- [32] Cast (down): Used when creature casts spell facing downwards
 
 **Group attack animations**
 
--   \[40\] \[VCMI 1.2\] Group Attack (up): Used when creature attacks
-    multiple target, with primary target facing up (Dragon Breath
-    attack, or creatures like Hydra)
--   \[41\] \[VCMI 1.2\] Group Attack (front): Used when creature attacks
-    multiple target, with primary target facing front (Dragon Breath
-    attack, or creatures like Hydra)
--   \[42\] \[VCMI 1.2\] Group Attack (down): Used when creature attacks
-    multiple target, with primary target facing downwards (Dragon Breath
-    attack, or creatures like Hydra)
-
-# Proposed format extensions
-
-## Texture atlas format
-
-**TODO**
-
--   arbitrary texture coordinates
--   margins
--   grid-like layout
-
-### Texture atlas format
-
-``` javascript
-{
-    // Base path of all images in animation. Optional.
-    // Can be used to avoid using long path to images 
-    // If a path is a filename is is treated as single texture atlas
-    "basepath" : "path/to/images/atlas/bitmap.png",
-
-    // List of sequences / groups in animation
-    "sequences" :
-    [
-        {
-            // Index of group, zero-based
-            "group" : 1,
-
-            // List of files in this group
-            "frames" :
-            [
-                {"x":0, "y":0, "w": 64, "h": 64},
-                {"x":64, "y":0, "w": 64, "h": 64}
-                    ...
-            ]
-        },
-        ...
-    ]
-}
-```
-
-### Texture atlas grid format
-
-``` javascript
-{
-    // filename is is treated as single texture atlas
-    "basepath" : "path/to/images/atlas/bitmap.png",
-    
-    //optional, atlas is a grid with same size images
-    //located left to right, top to bottom
-    //[columns, rows]
-    //default [1,1]
-    "gridCols":3,
-    "gridRows":3,
-
-    // List of sequences / groups in animation
-    // sequence index -> images count in sequence
-    "sequences" :
-    [
-        1,3,5
-    ]
-}
-```
+- [40] Group Attack (up): Used when creature attacks multiple target, with primary target facing up (Dragon Breath attack, or creatures like Hydra)
+- [41]  Group Attack (front): Used when creature attacks multiple target, with primary target facing front (Dragon Breath attack, or creatures like Hydra)
+- [42] Group Attack (down): Used when creature attacks multiple target, with primary target facing downwards (Dragon Breath attack, or creatures like Hydra)

docs/modders/Bonus/Bonus_Duration_Types.md

@@ -1,19 +1,16 @@
 < [Documentation](../../Readme.md) / [Modding](../Readme.md) / [Bonus Format](../Bonus_Format.md) / Bonus Duration Types
 
-
 Bonus may have any of these durations. They acts in disjunction.
 
 ## List of all bonus duration types
 
 -   PERMANENT
--   ONE_BATTLE //at the end of battle
--   ONE_DAY //at the end of day
--   ONE_WEEK //at the end of week (bonus lasts till the end of week,
-    thats NOT 7 days
--   N_TURNS //used during battles, after battle bonus is always removed
+-   ONE_BATTLE: at the end of battle
+-   ONE_DAY: at the end of day
+-   ONE_WEEK: at the end of week (bonus lasts till the end of week, NOT 7 days)
+-   N_TURNS: used during battles, after battle bonus is always removed
 -   N_DAYS
--   UNTIL_BEING_ATTACKED //removed after any damage-inflicting attack
--   UNTIL_ATTACK //removed after attack and counterattacks are performed
--   STACK_GETS_TURN //removed when stack gets its turn - used for
-    defensive stance
+-   UNTIL_BEING_ATTACKED: removed after any damage-inflicting attack
+-   UNTIL_ATTACK: removed after attack and counterattacks are performed
+-   STACK_GETS_TURN: removed when stack gets its turn - used for defensive stance
 -   COMMANDER_KILLED

docs/modders/Bonus/Bonus_Limiters.md

@@ -4,11 +4,14 @@
 
 The limiters take no parameters:
 
--   SHOOTER_ONLY
--   DRAGON_NATURE
--   IS_UNDEAD
--   CREATURE_NATIVE_TERRAIN
--   OPPOSITE_SIDE
+- SHOOTER_ONLY
+- DRAGON_NATURE
+- IS_UNDEAD
+- CREATURE_NATIVE_TERRAIN
+- CREATURE_FACTION
+- SAME_FACTION
+- CREATURES_ONLY
+- OPPOSITE_SIDE
 
 Example:
 
@@ -56,7 +59,15 @@ Parameters:
 
 -   Alignment identifier
 
-### CREATURE_FACTION_LIMITER
+### CREATURE_LEVEL_LIMITER
+
+If parameters is empty, level limiter works as CREATURES_ONLY limiter
+
+Parameters:
+- Minimal level
+- Maximal level
+
+### FACTION_LIMITER
 
 Parameters:
 
@@ -84,6 +95,12 @@ Example:
 } ]
 ```
 
+### UNIT_ON_HEXES
+
+Parameters:
+
+- List of affected battlefield hexes
+
 ## Aggregate Limiters
 
 The following limiters must be specified as the first element of a list,

docs/modders/Bonus/Bonus_Propagators.md

@@ -2,26 +2,9 @@
 
 ## Available propagators
 
--   BATTLE_WIDE
-
-Affects both sides during battle
-
--   VISITED_TOWN_AND_VISITOR
-
-Used with Legion artifacts (town visited by hero)
-
--   PLAYER_PROPAGATOR
-
-Bonus will affect all objects owned by player. Used by Statue of Legion.
-
--   TEAM_PROPAGATOR
-
-Bonus will affect all objects owned by player and his allies.
-
--   HERO
-
-Bonus will be transferred to hero (for example from stacks in his army).
-
--   GLOBAL_EFFECT
-
-This effect will influence all creatures, heroes and towns on the map.
+-   BATTLE_WIDE: Affects both sides during battle
+-   VISITED_TOWN_AND_VISITOR: Used with Legion artifacts (town visited by hero)
+-   PLAYER_PROPAGATOR: Bonus will affect all objects owned by player. Used by Statue of Legion.
+-   HERO: Bonus will be transferred to hero (for example from stacks in his army).
+-   TEAM_PROPAGATOR: Bonus will affect all objects owned by player and his allies.
+-   GLOBAL_EFFECT: This effect will influence all creatures, heroes and towns on the map.

docs/modders/Bonus/Bonus_Range_Types.md

@@ -2,21 +2,18 @@
 
 # List of all Bonus range types
 
--   NO_LIMIT
--   ONLY_DISTANCE_FIGHT
--   ONLY_MELEE_FIGHT
--   ONLY_ENEMY_ARMY (before 1.2)
+- NO_LIMIT
+- ONLY_DISTANCE_FIGHT
+- ONLY_MELEE_FIGHT
 
-TODO: in 0.91 ONLY_MELEE_FIGHT / ONLY_DISTANCE_FIGHT range types work
-ONLY with creature attack, should be extended to all battle abilities.
+TODO: ONLY_MELEE_FIGHT / ONLY_DISTANCE_FIGHT range types work ONLY with creature attack, should be extended to all battle abilities.
 
-(1.2+) For replacing ONLY_ENEMY_ARMY alias, you should use the following
-parameters of bonus:
+For replacing ONLY_ENEMY_ARMY alias, you should use the following parameters of bonus:
 
-    	"propagator": "BATTLE_WIDE",
-    	"propagationUpdater" : "BONUS_OWNER_UPDATER",
-    	"limiters" : [ "OPPOSITE_SIDE" ]
+```
+	"propagator": "BATTLE_WIDE",
+	"propagationUpdater" : "BONUS_OWNER_UPDATER",
+	"limiters" : [ "OPPOSITE_SIDE" ]
+```
 
-If some propagators was set before, it was actually ignored and should
-be replaced to code above. And OPPOSITE_SIDE limiter should be first, if
-any other limiters exists.
+If some propagators was set before, it was actually ignored and should be replaced to code above. And OPPOSITE_SIDE limiter should be first, if any other limiters exists.

docs/modders/Bonus/Bonus_Sources.md

@@ -2,22 +2,21 @@
 
 # List of all possible bonus sources
 
--   ARTIFACT
--   ARTIFACT_INSTANCE
--   OBJECT
--   CREATURE_ABILITY
--   TERRAIN_NATIVE
--   TERRAIN_OVERLAY
--   SPELL_EFFECT
--   TOWN_STRUCTURE
--   HERO_BASE_SKILL
--   SECONDARY_SKILL
--   HERO_SPECIAL
--   ARMY
--   CAMPAIGN_BONUS
--   SPECIAL_WEEK
--   STACK_EXPERIENCE
--   COMMANDER
--   GLOBAL_EFFECT (before 1.2)
--   GLOBAL (after 1.2)
--   OTHER
+- ARTIFACT
+- ARTIFACT_INSTANCE
+- OBJECT
+- CREATURE_ABILITY
+- TERRAIN_NATIVE
+- TERRAIN_OVERLAY
+- SPELL_EFFECT
+- TOWN_STRUCTURE
+- HERO_BASE_SKILL
+- SECONDARY_SKILL
+- HERO_SPECIAL
+- ARMY
+- CAMPAIGN_BONUS
+- SPECIAL_WEEK
+- STACK_EXPERIENCE
+- COMMANDER
+- GLOBAL
+- OTHER

docs/modders/Bonus/Bonus_Types.md

@@ -1,14 +1,18 @@
 < [Documentation](../../Readme.md) / [Modding](../Readme.md) / [Bonus Format](../Bonus_Format.md) / Bonus Types
 
-The bonuses were grouped according to their original purpose. The bonus
-system allows them to propagate freely betwen the nodes, however they
-may not be recognized properly beyond the scope of original use.
+The bonuses were grouped according to their original purpose. The bonus system allows them to propagate freely betwen the nodes, however they may not be recognized properly beyond the scope of original use.
 
 # General-purpose bonuses
 
 ### NONE
 
-### MORALE, LUCK
+Special bonus that gives no effect
+
+### MORALE
+
+-   val = value
+
+### LUCK
 
 -   val = value
 
@@ -20,8 +24,6 @@ eg. for magic plains terrain and for magic school secondary skills
     earth)
 -   val - level
 
-### NO_TYPE
-
 ### DARKNESS
 
 -   val = radius
@@ -35,10 +37,6 @@ land
 
 -   val = number of movement points (100 points for a tile)
 
-### LAND_MOVEMENT, SEA_MOVEMENT (before 1.2)
-
--   val = number of movement points (100 points for a tile)
-
 ### WATER_WALKING
 
 -   subtype: 1 - without penalty, 2 - with penalty
@@ -47,7 +45,7 @@ land
 
 -   subtype: 1 - without penalty, 2 - with penalty
 
-### NO_TERRAIN_PENALTY (since 0.98f)
+### NO_TERRAIN_PENALTY
 
 Hero does not get movement penalty on certain terrain type (Nomads
 ability).
@@ -59,13 +57,7 @@ ability).
 -   uses subtype to pick skill
 -   additional info if set: 1 - only melee, 2 - only distance
 
-### SIGHT_RADIOUS (before 1.2)
-
-Additional bonus to range of sight (Used for Scouting secondary skill)
-
--   val = distance in tiles
-
-### SIGHT_RADIUS (after 1.2)
+### SIGHT_RADIUS
 
 Sight radius of a hero. Used for base radius + Scouting secondary skill
 
@@ -85,19 +77,13 @@ all mana points are replenished every day
 
 good and neutral creatures can be mixed without morale penalty
 
-### SECONDARY_SKILL_PREMY (before 1.2)
-
-%
-
 ### SURRENDER_DISCOUNT
 
 %
 
 ### IMPROVED_NECROMANCY
 
-Before 1.2: allows Necropolis units other than skeletons to be raised by
-necromancy After 1.2: determine units which is raised by necromancy
-skill.
+Determine units which is raised by necromancy skill.
 
 -   subtype: creature raised
 -   val: Necromancer power
@@ -110,7 +96,7 @@ skill.
 `  "addInfo" : 0`  
 ` }`
 
-### LEARN_BATTLE_SPELL_CHANCE (since 1.2)
+### LEARN_BATTLE_SPELL_CHANCE
 
 -   subtype: 0 - from enemy hero, 1 - from entire battlefield (not
     implemented now).
@@ -118,14 +104,14 @@ skill.
 
 Note: used for Eagle Eye skill
 
-### LEARN_BATTLE_SPELL_LEVEL_LIMIT (since 1.2)
+### LEARN_BATTLE_SPELL_LEVEL_LIMIT
 
 -   subtype: school (-1 for all), others TODO
 -   val: maximum learning level
 
 Note: used for Eagle Eye skill
 
-### LEARN_MEETING_SPELL_LIMIT (since 1.2)
+### LEARN_MEETING_SPELL_LIMIT
 
 -   subtype: school (-1 for all), others TODO
 -   val: maximum learning level for learning a spell during hero
@@ -133,35 +119,34 @@ Note: used for Eagle Eye skill
 
 Note: used for Scholar skill
 
-### ROUGH_TERRAIN_DISCOUNT (since 1.2)
+### ROUGH_TERRAIN_DISCOUNT
 
 -   val: Non-road terrain discount in movement points
 
 Note: used for Pathfinding skill
 
-### WANDERING_CREATURES_JOIN_BONUS (since 1.2)
+### WANDERING_CREATURES_JOIN_BONUS
 
 -   val: value than used as level of diplomacy inside joining
     probability calculating
 
-### BEFORE_BATTLE_REPOSITION (since 1.2)
+### BEFORE_BATTLE_REPOSITION
 
--   val: number of hexes - 1 than should be used as repositionable hexes
-    before battle (like H3 tactics skill)
+-   val: number of hexes - 1 than should be used as repositionable hexes before battle (like H3 tactics skill)
 
-### BEFORE_BATTLE_REPOSITION_BLOCK (since 1.2)
+Note that Tactics phase for both sides simultaneously is not supported
 
--   val: value than block opposite tactics, if value of opposite tactics
-    is less than this value of your hero (for 1.2, double-side tactics
-    is not working).
+### BEFORE_BATTLE_REPOSITION_BLOCK
 
-### HERO_EXPERIENCE_GAIN_PERCENT (since 1.2)
+-   val: value than block opposite tactics, if value of opposite tactics is less than this value of your hero.
+
+### HERO_EXPERIENCE_GAIN_PERCENT
 
 -   val: how many experience hero gains from any source. There is a
     global effect which set it by 100 (global value) and it is used as
     learning skill
 
-### UNDEAD_RAISE_PERCENTAGE (since 1.2)
+### UNDEAD_RAISE_PERCENTAGE
 
 -   val: Percentage of killed enemy creatures to be raised after battle
     as undead.
@@ -169,32 +154,32 @@ Note: used for Pathfinding skill
 Note: used for Necromancy secondary skill, Necromancy artifacts and town
 buildings.
 
-### MANA_PER_KNOWLEDGE (since 1.2)
+### MANA_PER_KNOWLEDGE
 
 -   val: Percentage rate of translating 10 hero knowledge to mana, used
     for intelligence and global bonus
 
-### HERO_GRANTS_ATTACKS (since 1.2)
+### HERO_GRANTS_ATTACKS
 
 -   subtype: creature to have additional attacks
 -   val: Number of attacks
 
 Note: used for Artillery secondary skill
 
-### BONUS_DAMAGE_PERCENTAGE (since 1.2)
+### BONUS_DAMAGE_PERCENTAGE
 
 -   subtype: creature to have additional damage percentage
 -   val: percentage to be granted
 
 Note: used for Artillery secondary skill
 
-### BONUS_DAMAGE_CHANCE (since 1.2)
+### BONUS_DAMAGE_CHANCE
 
 -   subtype: creature to have additional damage chance (will have
     BONUS_DAMAGE_PERCENTAGE applied before attack concluded)
 -   val: chance in percent
 
-### MAX_LEARNABLE_SPELL_LEVEL (since 1.2)
+### MAX_LEARNABLE_SPELL_LEVEL
 
 -   val: maximum level of spells than hero can learn from any source.
     This bonus have priority above any other LEARN\_\*SPELL_LEVEL
@@ -211,26 +196,14 @@ Note: used as global effect and as wisdom secondary skill.
 
 ### SPELL_DAMAGE
 
-Since 1.2: used for Sorcery secondary skill
-
--   val = value in percent
+- val = value in percent
+- subtype - spell school
 
 ### SPECIFIC_SPELL_DAMAGE
 
 -   subtype = id of spell
 -   val = value in percent (Luna, Ciele)
 
-### SPECIAL_BLESS_DAMAGE (before 1.2)
-
--   subtype = spell (bless by default)
--   val = value per level in percent
-
-### MAXED_SPELL (before 1.2)
-
-Spell always has expert effects but not expert range
-
--   subtype = id
-
 ### SPECIAL_PECULIAR_ENCHANT
 
 blesses and curses with id = val dependent on unit's level
@@ -246,18 +219,9 @@ blesses and curses with id = val dependent on unit's level
 
 ### SPELL_DURATION
 
-### AIR_SPELL_DMG_PREMY, EARTH_SPELL_DMG_PREMY, FIRE_SPELL_DMG_PREMY, WATER_SPELL_DMG_PREMY
-
-Effect of original Orb artifacts.
-
--   val - **percent** bonus to air / earth / fire / water spell damage.
-
-### BLOCK_MORALE, BLOCK_LUCK (removed in 1.2)
-
 ### SPELL
 
-Hero knows spell, even if this spell is banned in map options or set to
-"special".
+Hero knows spell, even if this spell is banned in map options or set to "special".
 
 -   subtype - spell id
 -   val - skill level (0 - 3)
@@ -271,10 +235,11 @@ hero knows all spells of given level
 
 Does not grant spells banned in map options.
 
-### FIRE_SPELLS, AIR_SPELLS, WATER_SPELLS, EARTH_SPELLS
+### SPELLS_OF_SCHOOL
 
-All spells of this school are granted to hero, eg. by Tomes of Magic.
-Does not grant spells banned in map options.
+-   subtype = spell school
+
+All spells of this school are granted to hero, eg. by Tomes of Magic. Does not grant spells banned in map options.
 
 ### GENERATE_RESOURCE
 
@@ -358,11 +323,7 @@ and don't move.
 
 ### DRAGON_NATURE
 
-### KING1, KING2, KING3 (before 1.2)
-
-Creatures take more damage from basic, advanced or expert Slayer effect.
-
-### KING (after 1.2)
+### KING
 
 Creatures take more damage from Slayer effect than have greater or equal
 value than KING bonus.
@@ -377,14 +338,6 @@ eg. when fighting on cursed ground
 
 eg. when fighting on cursed ground
 
-### SELF_MORALE (before 1.2)
-
-eg. minotaur
-
-### SELF_LUCK (before 1.2)
-
-halfling
-
 ## Combat abilities
 
 ### FLYING
@@ -446,7 +399,7 @@ in % (value) eg. behemots
 -   subtype - 0 - shield (melee) , 1 - air shield effect (ranged), -1 -
     armorer secondary skill (all, since 1.2)
 
-### PERCENTAGE_DAMAGE_BOOST (since 1.2)
+### PERCENTAGE_DAMAGE_BOOST
 
 -   subtype: -1 - any damage (not used), 0 - melee damage (offence), 1 -
     ranged damage (archery)
@@ -541,7 +494,7 @@ Kills extra units after hit
 -   val: chance in percent to trigger
 -   addInfo: amount/percentage to kill
 
-### LIMITED_SHOOTING_RANGE (since VCMI 1.2)
+### LIMITED_SHOOTING_RANGE
 
 Limits shooting range and/or changes long range penalty
 
@@ -553,19 +506,12 @@ Limits shooting range and/or changes long range penalty
 
 ### CATAPULT
 
--   subtype: (since 1.2) ability to use when catapulting (usually it
-    contains ballistics parameters, ability for standard catapult and
-    affected by ballistics is core:spell.catapultShot)
+-   subtype: ability to use when catapulting (usually it contains ballistics parameters, ability for standard catapult and affected by ballistics is core:spell.catapultShot)
 
 ### CATAPULT_EXTRA_SHOTS
 
--   subtype: (since 1.2) ability to be affected. Ability of CATAPULT
-    bonus should match. Used for ballistics secondary skill with subtype
-    of core:spell.catapultShot.
--   val: (since 1.2) ability level to be used with catapult. Additional
-    shots configured in ability level, not here.
--   val: (before 1.2) number of additional shots, requires CATAPULT
-    bonus to work
+-   subtype: ability to be affected. Ability of CATAPULT bonus should match. Used for ballistics secondary skill with subtype of core:spell.catapultShot.
+-   val: ability level to be used with catapult. Additional shots configured in ability level, not here.
 
 ### MANUAL_CONTROL
 
@@ -623,7 +569,7 @@ eg. dread knight
 
 First aid tent
 
--   subtype: (since 1.2) ability used for healing.
+-   subtype: ability used for healing.
 
 ### FIRE_SHIELD
 
@@ -721,16 +667,13 @@ total duration of spells casted by creature
 
 ### ENCHANTED
 
-Stack is permanently enchanted with spell subID of skill level = val, if
-val \> 3 then spell is mass and has level of val-3. Enchantment is
-refreshed every turn.
+Stack is permanently enchanted with spell subID of skill level = val, if val > 3 then spell is mass and has level of val-3. Enchantment is refreshed every turn.
 
 ## Spell immunities
 
 ### LEVEL_SPELL_IMMUNITY
 
-creature is immune to all spell with level below or equal to value of
-this bonus
+creature is immune to all spell with level below or equal to value of this bonus
 
 ### MAGIC_RESISTANCE
 
@@ -762,24 +705,11 @@ Creature is immune to all mind spells.
 -   subtype - spell id
 -   ainfo - 0 - normal, 1 - absolute
 
-### DIRECT_DAMAGE_IMMUNITY
-
-WoG ability. Creature is completely immune to damage spells.
-
 ### RECEPTIVE
 
 WoG ability. Creature accepts all friendly spells even though it would
 be normally immune to it.
 
-## Deprecated creature abilities
-
-### DAEMON_SUMMONING
-
-pit lord - removed in VCMI 1.2 as part of major battles refactoring
-
--   subtype - type of creatures
--   val - hp per unit
-
 # Spell effects
 
 ### POISON
@@ -831,4 +761,49 @@ while in berserk
 
 ### NO_RETALIATION
 
-Eg. when blinded or paralyzed.
+Eg. when blinded or paralyzed.
+
+# Undocumented
+
+### LEVEL_COUNTER
+for commander artifacts
+
+### BLOCK_MAGIC_ABOVE
+blocks casting spells of the level > value 
+
+### BLOCK_ALL_MAGIC
+blocks casting spells
+
+### SPELL_IMMUNITY
+subid - spell id
+
+### GENERAL_DAMAGE_PREMY
+
+### ADDITIONAL_UNITS
+val of units with id = subtype will be added to hero's army at the beginning of battle
+
+### SPOILS_OF_WAR
+val * 10^-6 * gained exp resources of subtype will be given to hero after battle
+
+### BLOCK
+
+### DISGUISED
+subtype - spell level
+
+### VISIONS
+subtype - spell level
+
+### SYNERGY_TARGET
+dummy skill for alternative upgrades mod
+
+### BLOCK_MAGIC_BELOW
+blocks casting spells of the level < value 
+
+### SPECIAL_ADD_VALUE_ENCHANT
+specialty spell like Aenin has, increased effect of spell, additionalInfo = value to add
+
+### SPECIAL_FIXED_VALUE_ENCHANT
+specialty spell like Melody has, constant spell effect (i.e. 3 luck), additionalInfo = value to fix.
+
+### TOWN_MAGIC_WELL
+one-time pseudo-bonus to implement Magic Well in the town

docs/modders/Bonus/Bonus_Updaters.md

@@ -83,3 +83,7 @@ Remark: The stack level for war machines is 0.
 `       "parameters" : [ 20, 3, 10, 700 ],`  
 `       "type" : "ARMY_MOVEMENT"`  
 `   }`
+
+## BONUS_OWNER_UPDATER
+
+TODO: document me

docs/modders/Bonus/Bonus_Value_Types.md

@@ -2,24 +2,16 @@
 
 Total value of Bonus is calculated using the following:
 
--   For each bonus source type we calculate new source value (for all
-    bonus value types except PERCENT_TO_SOURCE and
-    PERCENT_TO_TARGET_TYPE) using the following:
-
+-   For each bonus source type we calculate new source value (for all bonus value types except PERCENT_TO_SOURCE and PERCENT_TO_TARGET_TYPE) using the following:
 ` newVal = (val * (100 + PERCENT_TO_SOURCE) / 100))`
 
-PERCENT_TO_TARGET_TYPE applies as PERCENT_TO_SOURCE to targetSourceType
-of bonus.
+- PERCENT_TO_TARGET_TYPE applies as PERCENT_TO_SOURCE to targetSourceType of bonus.
 
--   All bonus value types summarized and then used as subject of the
-    following formula:
+-   All bonus value types summarized and then used as subject of the following formula:
 
 ` clamp(((BASE_NUMBER * (100 + PERCENT_TO_BASE) / 100) + ADDITIVE_VALUE) * (100 + PERCENT_TO_ALL) / 100), INDEPENDENT_MAX, INDEPENDENT_MIN)`
 
-As for 1.2, semantics of INDEPENDENT_MAX and INDEPENDENT_MIN are
-wrapped, and first means than bonus total value will be at least
-INDEPENDENT_MAX, and second means than bonus value will be at most
-INDEPENDENT_MIN.
+Semantics of INDEPENDENT_MAX and INDEPENDENT_MIN are wrapped, and first means than bonus total value will be at least INDEPENDENT_MAX, and second means than bonus value will be at most INDEPENDENT_MIN.
 
 # List of all bonus value types
 
@@ -29,5 +21,5 @@ INDEPENDENT_MIN.
 -   PERCENT_TO_BASE
 -   INDEPENDENT_MAX
 -   INDEPENDENT_MIN
--   PERCENT_TO_SOURCE (since 1.2)
--   PERCENT_TO_TARGET_TYPE (since 1.2)
+-   PERCENT_TO_SOURCE
+-   PERCENT_TO_TARGET_TYPE

docs/modders/Bonus_Format.md

@@ -15,6 +15,7 @@ All parameters but type are optional.
 	"duration" :    "BONUS_DURATION", //or ["BONUS_DURATION1", "BONUS_DURATION2", ...]"
 	"turns" :       0,
 
+	"targetSourceType" : "SOURCE_TYPE",
 	"sourceType" :  "SOURCE_TYPE",
 	"sourceID" :    0,
 	"effectRange" : "EFFECT_RANGE",
@@ -45,9 +46,7 @@ All parameters but type are optional.
 
 ## Subtype resolution
 
-All string identifiers of items can be used in "subtype" field. This
-allows cross-referencing between the mods and make config file more
-readable.
+All string identifiers of items can be used in "subtype" field. This allows cross-referencing between the mods and make config file more readable.
 
 ### Available prefixes
 

docs/modders/Map_Object_Format.md

@@ -14,7 +14,7 @@ Full object consists from 3 parts:
     generated by the game. When new object is created its starting
     appearance will be copied from template
 
-### Object types
+## Object types
 
 - [Rewardable](Map_Objects/Rewardable.md) - Visitable object which grants all kinds of rewards (gold, experience, Bonuses etc...)
 - [Creature Bank](Map_Objects/Creature_Bank.md) - Object that grants award on defeating guardians
@@ -29,13 +29,8 @@ Full object consists from 3 parts:
 {
 	"myCoolObjectGroup":
 	{
-		//numeric ID, mandatory for h3/wog objects, shall be unique if not defined
-		//used only for H3 objects, mods can not be used by mods
-		"index":123,
-
-		//Mandatory for new objects,
+		// Mandatory for new objects,
 		// human readable name, localized 
-		//default for original objects from "OBJNAMES.TXT" 
 		"name": "My cool object",
 
 		//defines C++/script class name that handles behavior of this object
@@ -54,22 +49,26 @@ Full object consists from 3 parts:
 ## Object type format
 
 ``` javascript
-
 {
 	"myCoolObject":
 	{
-		//numeric sub ID, mandatory for h3/wog objects, shall be unique if set
-		//used only for H3 objects, can not be used by mods
-		"index":123,
-
-		// parameters that will be passed over to class that controls behavior of the object
-		"producedResources" : "gold",
-		"producedValue" : 1000
-
-		// TODO: allow better selection of template for object, instead of just terrain
-		// field describes how object template will be selected if there are multiple possiblities
-		// exact behavior and format depends on object type
-		"filter" : { ... },
+		// Additonal parameters that will be passed over to class that controls behavior of the object
+		// See object-specific properties of different object types
+		"propertyA" : "value",
+		"propertyB" : 12345
+
+		// How valuable this object is to AI
+		"aiValue" : 1000,
+		
+		// Sounds assigned to this object
+		"sounds" : {
+			// Ambient sounds that plays when current hero is near this object
+			"ambient" : [ "" ],
+			// Sounds that plays when hero visits this object
+			"visit" : [ "" ],
+			// Sounds that play when this object is removed from the map
+			"removal" : [ "" ],
+		},
 
 		// Data for random map generator that describes how object should be placed.
 		// If this entry is missing object will not be placed by RMG
@@ -104,14 +103,13 @@ Full object consists from 3 parts:
 {
 	"myCoolObjectTemplate" : 
 	{
-		// resource ID  of animation, relative to SPRITES directory (def file or json file)
+		// Path to def file with animation of this object
 		"animation":"DEFNAME.def",
 
-		// resource ID  of animation for mapeditor, relative to SPRITES directory (def file or json file)
-		//0.98c+
+		// Optional path to def file with animation of this object to use in map editor
 		"editorAnimation":"DEFNAME.def",
 
-		// directions from which hero can visit this object.
+		// Directions from which hero can visit this object.
 		// "+" means that object can be visited from that direction, or "-" othervice
 		// default not visitable
 		"visitableFrom" : [
@@ -139,17 +137,12 @@ Full object consists from 3 parts:
 			"0000HHAT"
 		],
 
-		// optional; default or if explicitly set to null: all terrains except rock
-		// allowed terrain types to place object too. Affects also RMG.
+		// optional; default or if explicitly set to null: all "land" terrains (e.g. not rock and not water)
+		// allowed terrain types to place object to. Affects also RMG.
 		// Note that map editor will still allow to place object on other terrains
-                // allowed terrain types: "dirt", "sand", "grass", "snow", "swamp", "rough", "subterra", "lava", "water", "rock"
+		// allowed terrain types: "dirt", "sand", "grass", "snow", "swamp", "rough", "subterra", "lava", "water", "rock"
 		"allowedTerrains":["dirt", "sand"],
 
-		// TODO, default - empty
-		// tags from object type are always present (???)
-		// List of tags that can be used to locate object in map editor
-		"tags":["dirt", "sand", "mine"],
-
 		//zindex, defines order in which objects on same tile will be blit. optional, default is 0 
 		//NOTE: legacy overlay objects has zindex = 100
 		"zIndex": 0

docs/modders/Map_Objects/Creature_Bank.md

@@ -1,5 +1,8 @@
 < [Documentation](../../Readme.md) / [Modding](../Readme.md) / [Map Object Format](../Map_Object_Format.md) / Creature Bank
 
+Reward types for clearing creature bank are limited to resources, creatures, artifacts and spell.
+Format of rewards is same as in [Rewardable Objects](Rewardable.md)
+
 ``` javascript
 {
 	/// List of levels of this bank. On map loading, one of them will be randomly assigned to bank.
@@ -27,15 +30,9 @@
 				{ "amount": 4, "type": "cyclop" }
 			],
 
-			// How hard are guards of this level. Unused?
-			"combat_value": 506,
-
 			/// Description of rewards granted for clearing bank
 			"reward" : {
 
-				/// Approximate value of reward, known to AI. Unused?
-				"value": 10000,
-
 				/// Granted resources
 				"resources": {
 					"wood" : 4,

docs/modders/Map_Objects/Dwelling.md

@@ -14,6 +14,7 @@
 	/// Boolean true/false - If set to "true", guards will be generated using H3 formula:
 	/// 3 week growth of first available creatures
 	/// List of objects - custom guards, each entry represent one stack in defender army
+	"guards" : true,
 	"guards" : [
 		{ "amount" : 12, "type" : "earthElemental" }
 	]

docs/modders/Map_Objects/Market.md

@@ -77,8 +77,7 @@ Game logic prohibits using modes unavailable for faction
 
 # Offer
 
-This field allows to configure specific items available in the market.
-In VCMI-1.3 it can be used only for `resource-skill` mode
+This field allows to configure specific items available in the market. It can be used only for `resource-skill` mode
 
 See [Secondary skills](Rewardable.md#secondary-skills) description for more details
 

docs/modders/Map_Objects/Rewardable.md

@@ -26,7 +26,7 @@
 
 ## Base object definition
 Rewardable object is defined similarly to other objects, with key difference being `handler`. This field must be set to `"handler" : "configurable"` in order for vcmi to use this mode.
-```js
+```jsonc
 {
   "baseObjectName" : {
     "name" : "Object name",
@@ -58,7 +58,7 @@ Rewardable object is defined similarly to other objects, with key difference bei
 ```
 
 ## Configurable object definition
-```js
+```jsonc
 // List of potential rewards
 "rewards" : [
   {
@@ -92,7 +92,7 @@ Rewardable object is defined similarly to other objects, with key difference bei
     // message that will be shown if this is the only available award
     "message": "{Warehouse of Crystal}"
 
-    // (VCMI 1.2) object will be disappeared after taking reward is set to true
+    // object will be disappeared after taking reward is set to true
     "removeObject": false
 
     // See "Configurable Properties" section for additiona parameters
@@ -100,7 +100,7 @@ Rewardable object is defined similarly to other objects, with key difference bei
   }
 ],
 
-// (VCMI 1.2) If true, hero can not move to visitable tile of the object and will access this object from adjacent tile (e.g. Treasure Chest)
+// If true, hero can not move to visitable tile of the object and will access this object from adjacent tile (e.g. Treasure Chest)
 "blockedVisitable" : true,
 
 // Message that will be shown if there are no applicable awards
@@ -126,13 +126,7 @@ Rewardable object is defined similarly to other objects, with key difference bei
 // Note that in this case object will not become "visited" and can still be revisited later
 "canRefuse": true,
 
-// object reset period. Note that period is counted from game start and not from hero visit
-// reset duration of 7 will always reset object on new week & duration of 28 will reset on new month
-// if field is not present or set to 0 object will never reset
-// (VCMI 1.2) This property has been removed in favor of more detailed "resetParameters" property
-"resetDuration" : 7, 
-
-// (VCMI 1.2) see Reset Parameters definition section
+// Controls when object state will be reset, allowing potential revisits. See Reset Parameters definition section
 "resetParameters" : {
 }
 
@@ -153,14 +147,12 @@ Rewardable object is defined similarly to other objects, with key difference bei
 ```
 
 ## Reset Parameters definition
-(VCMI 1.2 only) 
-
 This property describes how object state should be reset. Objects without this field will never reset its state.
 - Period describes interval between object resets in day. Periods are counted from game start and not from hero visit, so reset duration of 7 will always reset object on new week & duration of 28 will always reset on new month.
 - If `visitors` is set to true, game will reset list of visitors (heroes and players) on start of new period, allowing revisits of objects with `visitMode` set to `once`, `hero`, or `player`. Objects with visit mode set to `bonus` are not affected. In order to allow revisit such objects use appropriate bonus duration (e.g. `ONE_DAY` or `ONE_WEEK`) instead.
 - If `rewards` is set to true, object will re-randomize its provided rewards, similar to such H3 objects as "Fountain of Fortune" or "Windmill"
 
-```js
+```jsonc
 "resetParameters" : {
     "period" : 7,
     "visitors" : true,
@@ -172,7 +164,7 @@ This property describes how object state should be reset. Objects without this f
 This property describes chance for reward to be selected.
 When object is initialized on map load, game will roll a "dice" - random number in range 0-99, and pick all awards that have appear chance within selected number
 
-```js
+```jsonc
     "appearChance": 
     {
       // (Advanced) rewards with different dice number will get different dice number
@@ -190,24 +182,24 @@ When object is initialized on map load, game will roll a "dice" - random number
 
 ## Configurable Properties
 Unless stated othervice, all numbers in this section can be replaced with random values, e.g.
-```js
+```jsonc
 "minLevel" : { "min" : 5, "max" : 10 } // select random number between 5-10, including both 5 & 10
 "minLevel" : [ 2, 4, 6, 8, 10] // (VCMI 1.2) select random number out of provided list, with equal chance for each
 ```
 
 In this case, actual value for minLevel will be picked randomly. 
-(VCMI 1.2) Keep in mind, that all randomization is performed on map load and on reset (only if `rewards` field in `resetParameter` was set).
+Keep in mind, that all randomization is performed on map load and on object reset (if `rewards` field in `resetParameter` was set).
 
 ### Current Day
 - Can only be used as limiter. To pass, current day of week should be equal to this value. 1 = first day of the week, 7 = last day
 
-```js
+```jsonc
 "dayOfWeek" : 0 
 ```
 
-- (VCMI 1.2) Can only be used as limiter. To pass, number of days since game started must be at equal or greater than this value
+- Can only be used as limiter. To pass, number of days since game started must be at equal or greater than this value
 
-```js
+```jsonc
 "daysPassed" : 8
 ```
 
@@ -216,15 +208,15 @@ In this case, actual value for minLevel will be picked randomly.
 - Can be used as reward to grant resources to player
 - If negative value is used as reward, it will be used as cost and take resources from player
 
-```js
+```jsonc
 "resources": {
     "crystal" : 6,
     "gold" : -1000,
 }, 
 ```
-- (VCMI 1.2) Alternative format that allows random selection of a resource type
+- Alternative format that allows random selection of a resource type
 
-```js
+```jsonc
 "resources": [
     {
         "list" : [ "wood", "ore" ],
@@ -238,41 +230,41 @@ In this case, actual value for minLevel will be picked randomly.
 ```
 
 ### Experience
-- (VCMI 1.2) Can be used as limiter
+- Can be used as limiter
 - Can be used as reward to grant experience to hero
 
-```js
+```jsonc
 "heroExperience" : 1000, 
 ```
 
 ### Hero Level
 - Can be used as limiter. Hero requires to have at least specified level
-- (VCMI 1.2) Can be used as reward, will grant hero experience amount equal to the difference between the hero's next level and current level (Tree of Knowledge)
+- Can be used as reward, will grant hero experience amount equal to the difference between the hero's next level and current level (Tree of Knowledge)
 
-```js
+```jsonc
 "heroLevel" : 1,
 ```
 
 ### Mana Points
-- (VCMI 1.2) Can be used as limiter. Hero must have at least specific mana amount
+- Can be used as limiter. Hero must have at least specific mana amount
 - Can be used as reward, to give mana points to hero. Mana points may go above mana pool limit.
 - If negative value is used as reward, it will be used as cost and take mana from player
 
-```js
+```jsonc
 "manaPoints": -10, 
 ```
 
-- (VCMI 1.2) if giving mana points puts hero above mana pool limit, any overflow will be multiplied by specified percentage. If set to 0, mana will not go above mana pool limit.
+- If giving mana points puts hero above mana pool limit, any overflow will be multiplied by specified percentage. If set to 0, mana will not go above mana pool limit.
 
-```js
+```jsonc
 "manaOverflowFactor" : 50,
 ```
 
 ### Mana Percentage
-- (VCMI 1.2) Can be used as limiter. Hero must have at least specific mana percentage
+- Can be used as limiter. Hero must have at least specific mana percentage
 - Can be used to set hero mana level to specified percentage value, not restricted to mana pool limit (Magic Well, Mana Spring)
 
-```js
+```jsonc
 "manaPercentage": 200, 
 ```
 
@@ -280,7 +272,7 @@ In this case, actual value for minLevel will be picked randomly.
 - Can NOT be used as limiter
 - Can be used as reward, to give movement points to hero. Movement points may go above mana pool limit.
 
-```js
+```jsonc
 "movePoints": 200,
 ```
     
@@ -288,7 +280,7 @@ In this case, actual value for minLevel will be picked randomly.
 - Can NOT be used as limiter
 - Can be used to set hero movement points level to specified percentage value. Value of 0 will take away any remaining movement points
 
-```js
+```jsonc
 "movePercentage": 50,
 ```
 
@@ -296,8 +288,10 @@ In this case, actual value for minLevel will be picked randomly.
 - Can be used as limiter, hero must have primary skill at least at specified level
 - Can be used as reward, to increase hero primary skills by selected value
 - If reward value is negative, value will be used as cost, decreasing primary skill
-- (VCMI 1.3) Each primary skill can be explicitly specified or randomly selected
-```js
+- Each primary skill can be explicitly specified or randomly selected
+- Possible values: `"attack", "defence", "spellpower", "knowledge"`
+
+```jsonc
 "primary": [
     {
         // Specific primary skill
@@ -321,14 +315,6 @@ In this case, actual value for minLevel will be picked randomly.
     }
 ]
 ```
-- Possible values: `"attack", "defence", "spellpower", "knowledge"`
-- (VCMI 1.2) Deprecated format
-```js
-"primary": {
-    "attack" : 1,
-    "spellpower": -1
-},
-```
 
 ### Secondary Skills
 - Can be used as limiter, hero must have secondary skill at least at specified level
@@ -336,8 +322,8 @@ In this case, actual value for minLevel will be picked randomly.
 - If hero already has specified skill, the skills will be leveled up specified number of times
 - If hero does not have selected skill and have free skill slots, he will receive skill at specified level
 - Possible values: 1 (basic), 2 (advanced), 3 (expert)
-- (VCMI 1.3) Each secondary skill can be explicitly specified or randomly selected
-```js
+- Each secondary skill can be explicitly specified or randomly selected
+```jsonc
 "secondary": [
     {
         // Specific skill
@@ -361,20 +347,14 @@ In this case, actual value for minLevel will be picked randomly.
     }
 ]
 ```
-- (VCMI 1.2) deprecated format
-```js
-"secondary": {
-    "wisdom" : 1
-},
-```
 
 ### Bonus System
-- (VCMI 1.2) Can be used as reward, to grant bonus to player
-- (VCMI 1.2) if present, MORALE and LUCK bonus will add corresponding image component to UI.
-- (VCMI 1.2) Note that unlike most values, parameter of bonuses can NOT be randomized
-- (VCMI 1.X) Description can be string or number of corresponding string from `arraytxt.txt`
+- Can be used as reward, to grant bonus to player
+- if present, MORALE and LUCK bonus will add corresponding image component to UI.
+- Note that unlike most values, parameter of bonuses can NOT be randomized
+- Description can be string or number of corresponding string from `arraytxt.txt`
 
-```js
+```jsonc
 "bonuses" : [
     {
         "type" : "MORALE", 
@@ -388,9 +368,9 @@ In this case, actual value for minLevel will be picked randomly.
 ### Artifacts
 - Can be used as limiter, hero must have artifact either equipped or in backpack
 - Can be used as reward, to give new artifact to a hero
-- (VCMI 1.2) Artifacts added as reward will be used for text substitution. First `%s` in text string will be replaced with name of an artifact
+- Artifacts added as reward will be used for text substitution. First `%s` in text string will be replaced with name of an artifact
 
-```js
+```jsonc
 "artifacts": [
     "ribCage"
 ],
@@ -400,7 +380,7 @@ In this case, actual value for minLevel will be picked randomly.
 - For artifact class possible values are "TREASURE", "MINOR", "MAJOR", "RELIC"
 - Artifact value range can be specified with min value and max value
 
-```js
+```jsonc
 "artifacts": [
     {
         "class" : "TREASURE",
@@ -409,22 +389,22 @@ In this case, actual value for minLevel will be picked randomly.
     }
 ],
 ```
-    
+
 ### Spells
-- (VCMI 1.2) Can be used as limiter
+- Can be used as limiter
 - Can be used as reward, to give new spell to a hero
-- (VCMI 1.2) Spells added as reward will be used for text substitution. First `%s` in text string will be replaced with spell name
+- Spells added as reward will be used for text substitution. First `%s` in text string will be replaced with spell name
 
-```js
+```jsonc
 "spells": [
     "magicArrow"
 ],
 ```
 
 - Alternative format, random spell selection
-- (VCMI 1.X) Spell can be selected from specifically selected school
+- Spell can be selected from specifically selected school
 
-```js
+```jsonc
 "spells": [
     {
         "level" : 1,
@@ -432,13 +412,13 @@ In this case, actual value for minLevel will be picked randomly.
     }
 ],
 ```
-    
+
 ### Creatures
 - Can be used as limiter
 - Can be used as reward, to give new creatures to a hero
 - If hero does not have enough free slots, game will show selection dialog to pick troops to keep
 - It is possible to specify probabilty to receive upgraded creature
-```js
+```jsonc
 "creatures" : [
     {
         "creature" : "archer",
@@ -449,22 +429,22 @@ In this case, actual value for minLevel will be picked randomly.
 ```
 
 ### Creatures Change
-- (VCMI 1.2) Can NOT be used as limiter
-- (VCMI 1.2) Can be used as reward, to replace creatures in hero army. It is possible to use this parameter both for upgrades of creatures as well as for changing them into completely unrelated creature, e.g. similar to Skeleton Transformer
-- (VCMI 1.2) This parameter will not change creatures given by `creatures` parameter on the same visit
+- Can NOT be used as limiter
+- Can be used as reward, to replace creatures in hero army. It is possible to use this parameter both for upgrades of creatures as well as for changing them into completely unrelated creature, e.g. similar to Skeleton Transformer
+- This parameter will not change creatures given by `creatures` parameter on the same visit
 
-```js
+```jsonc
 "changeCreatures" : {
     "cavalier" : "champion"
 }
 ```
 
 ### Spell cast
-- (VCMI 1.3) Can NOT be used as limiter
-- (VCMI 1.3) As reward, instantly casts adventure map spell for visiting hero. All checks for spell book, wisdom or presence of mana will be ignored. It's possible to specify school level at which spell will be casted. If it's necessary to reduce player's mana or do some checks, they shall be introduced as limiters and other rewards
+- Can NOT be used as limiter
+- As reward, instantly casts adventure map spell for visiting hero. All checks for spell book, wisdom or presence of mana will be ignored. It's possible to specify school level at which spell will be casted. If it's necessary to reduce player's mana or do some checks, they shall be introduced as limiters and other rewards
 - School level possible values: 1 (basic), 2 (advanced), 3 (expert)
 
-```js
+```jsonc
 "spellCast" : {
     "spell" : "townPortal",
     "schoolLevel": 3

docs/modders/Mod_File_Format.md

@@ -3,57 +3,76 @@
 ## Fields with description of mod
 
 ``` javascript
- 
 {
-    // Name of your mod. While it does not have hard length limit
-    // it should not be longer than ~30 symbols to fit into allowed space
-    "name" : "My test mod",
-
-    // More lengthy description of mod. No hard limit. This text will be visible in launcher.
-    // This field can use small subset of HTML, see link at the bottom of this page.
-    "description" : "My test mod that add a lot of useless stuff into the game",
-
-    // Author of mod. Can be nickname, real name or name of team
-    "author" : "Anonymous",
-
-    // Full name of license used by mod. Should be set only if you're author of mod
-    // or received permission to use such license from original author
-    "licenseName" : "Creative Commons Attribution-ShareAlike",
-
-    // URL which user can use to see license terms and text
-    "licenseURL" : "https://creativecommons.org/licenses/by-sa/4.0/",
-
-    
-    // Home page of mod or link to forum thread to contact the author
-    "contact" : "http://example.com",
-
-    // Type of mod, list of all possible values:
-    // "Translation", "Town", "Test", "Templates", "Spells", "Music", "Sounds", "Skills", "Other", "Objects", 
-    // "Mechanics", "Interface", "Heroes", "Graphical", "Expansion", "Creatures", "Artifacts", "AI"
-    "modType" : "Graphical",
-
-    // List of mods that are required to run this one
-    "depends" :
-    [
-        "baseMod"
-    ],
+	// Name of your mod. While it does not have hard length limit
+	// it should not be longer than ~30 symbols to fit into allowed space
+	"name" : "My test mod",
+
+	// More lengthy description of mod. No hard limit. This text will be visible in launcher.
+	// This field can use small subset of HTML, see link at the bottom of this page.
+	"description" : "My test mod that add a lot of useless stuff into the game",
+
+	// Author of mod. Can be nickname, real name or name of team
+	"author" : "Anonymous",
+
+	// Full name of license used by mod. Should be set only if you're author of mod
+	// or received permission to use such license from original author
+	"licenseName" : "Creative Commons Attribution-ShareAlike",
+
+	// URL which user can use to see license terms and text
+	"licenseURL" : "https://creativecommons.org/licenses/by-sa/4.0/",
+
+	
+	// Home page of mod or link to forum thread to contact the author
+	"contact" : "http://example.com",
+	
+	// Current mod version, up to 3 numbers, dot-separated. Format: A.B.C
+	"version" : "1.2.3"
+
+	// Type of mod, list of all possible values:
+	// "Translation", "Town", "Test", "Templates", "Spells", "Music", "Sounds", "Skills", "Other", "Objects", 
+	// "Mechanics", "Interface", "Heroes", "Graphical", "Expansion", "Creatures", "Artifacts", "AI"
+	"modType" : "Graphical",
+	
+	// Base language of the mod, before applying localizations. By default vcmi assumes English
+	// This property is mostly needed for translation mods only
+	"language" : "english"
+
+	// List of mods that are required to run this one
+	"depends" :
+	[
+		"baseMod"
+	],
  
-    // List of mods that can't be enabled in the same time as this one
-    "conflicts" :
-    [
-        "badMod"
-    ],
-
-    //List of changes/new features in each version
-    "changelog" :
-    {
-        "1.0"   : [ "initial release" ],
-        "1.0.1" : [ "change 1", "change 2" ],
-        "1.1"   : [ "change 3", "change 4" ]
-    },
-
-    // If set to true, mod will not be enabled automatically on install
-    "keepDisabled" : false
+	// List of mods that can't be enabled in the same time as this one
+	"conflicts" :
+	[
+		"badMod"
+	],
+	
+	// Supported versions of vcmi engine
+	"compatibility" : {
+		"min" : "1.2.0"
+		"max" : "1.3.0"
+	}
+
+	//List of changes/new features in each version
+	"changelog" :
+	{
+		"1.0"   : [ "initial release" ],
+		"1.0.1" : [ "change 1", "change 2" ],
+		"1.1"   : [ "change 3", "change 4" ]
+	},
+
+	// If set to true, mod will not be enabled automatically on install
+	"keepDisabled" : false
+	
+	// List of game settings changed by a mod. See <VCMI Install>/config/gameConfig.json for reference
+	"settings" : {
+		"combat" : {
+			"goodLuckDice" : [] // disable luck
+		}
+	}
 }
 ```
 
@@ -64,71 +83,98 @@ These are fields that are present only in local mod.json file
 ``` javascript
  
 {
-    // Following section describes configuration files with content added by mod
-    // It can be split into several files in any way you want but recommended organization is
-    // to keep one file per object (creature/hero/etc) and, if applicable, add separate file
-    // with translatable strings for each type of content
-    // See "additional links" at the bottom of page for descriptions of each of these formats
-
-    // list of factions/towns configuration files
-    "factions" :
-    [
-        "config/myMod/faction.json"
-    ]
-
-    // List of hero classes configuration files
-    "heroClasses" :
-    [
-        "config/myMod/heroClasses.json"
-    ],
-
-    // List of heroes configuration files
-    "heroes" :
-    [
-        "config/myMod/heroes.json"
-    ],
-
-    // list of creature configuration files
-    "creatures" :
-    [
-        "config/myMod/creatures.json"
-    ],
-
-    // List of artifacts configuration files
-    "artifacts" :
-    [
-        "config/myMod/artifacts.json"
-    ],
-
-    // List of objects defined in this mod
-    "objects" :
-    [
-        "config/myMod/objects.json"
-    ],
-
-    // List of spells defined in this mod
-    "spells" :
-    [
-        "config/myMod/spells.json"
-    ],
-
-    // List of RMG templates defined in this mod
-    "templates" :
-    [
-        "config/myMod/templates.json"
-    ],
-
-    // Optional, description on how files are organized in your mod
-    // In most cases you do not need to use this field
-    // Needed mostly to port any existing mods to vcmi (e.g. WoG distributed with Era)
-    // Example below is default value, which is "Content" directory that acts as H3 root directory
-    "filesystem":
-    {
-        "":
-            [
-                {"type" : "dir",  "path" : "/Content"}
-            ]
-    }
+	// Following section describes configuration files with content added by mod
+	// It can be split into several files in any way you want but recommended organization is
+	// to keep one file per object (creature/hero/etc) and, if applicable, add separate file
+	// with translatable strings for each type of content
+
+	// list of factions/towns configuration files
+	"factions" :
+	[
+		"config/myMod/faction.json"
+	]
+
+	// List of hero classes configuration files
+	"heroClasses" :
+	[
+		"config/myMod/heroClasses.json"
+	],
+
+	// List of heroes configuration files
+	"heroes" :
+	[
+		"config/myMod/heroes.json"
+	],
+	
+	// List of configuration files for skills
+	skills
+
+	// list of creature configuration files
+	"creatures" :
+	[
+		"config/myMod/creatures.json"
+	],
+
+	// List of artifacts configuration files
+	"artifacts" :
+	[
+		"config/myMod/artifacts.json"
+	],
+
+	// List of objects defined in this mod
+	"objects" :
+	[
+		"config/myMod/objects.json"
+	],
+
+	// List of spells defined in this mod
+	"spells" :
+	[
+		"config/myMod/spells.json"
+	],
+	
+	// List of configuration files for terrains
+	"terrains" :
+	[
+		"config/myMod/terrains.json"
+	],
+	
+	// List of configuration files for roads
+	"roads" :
+	[
+		"config/myMod/roads.json"
+	],
+	
+	// List of configuration files for rivers
+	"rivers" :
+	[
+		"config/myMod/rivers.json"
+	],
+	
+	// List of configuration files for battlefields
+	"battlefields" :
+	[
+		"config/myMod/battlefields.json"
+	],
+	
+	// List of configuration files for obstacles
+	"obstacles" :
+	[
+		"config/myMod/obstacles.json"
+	],
+
+	// List of RMG templates defined in this mod
+	"templates" :
+	[
+		"config/myMod/templates.json"
+	],
+	
+	// Optional, primaly used by translation mods
+	// Defines strings that are translated by mod into base language specified in "language" field
+	"translations" :
+	[
+		"config/myMod/englishStrings.json
+	]
 }
 ```