Update & expand docs on bonus limiters & updaters

docs/modders/Bonus/Bonus_Limiters.md

@@ -23,20 +23,27 @@ Example:
 
 ### HAS_ANOTHER_BONUS_LIMITER
 
+Bonus is only active if affected entity has another bonus that meets conditions
+
 Parameters:
 
 - Bonus type
-- (optional) bonus subtype
-- (optional) bonus sourceType and sourceId in struct
-- example: (from Adele's bless):
+- bonus subtype
+- bonus sourceType and sourceId in struct
+
+All parameters are optional. Values that don't need checking can be replaces with `null`
+
+Examples:
+
+- Adele specialty: active if unit has any bonus from Bless spell
 
 ```json
 	"limiters" : [
 		{
 			"type" : "HAS_ANOTHER_BONUS_LIMITER",
 			"parameters" : [
-				"GENERAL_DAMAGE_PREMY",
-				1,
+				null,
+				null,
 				{
 					"type" : "SPELL_EFFECT",
 					"id" : "spell.bless"
@@ -46,18 +53,42 @@ Parameters:
 	],
 ```
 
+- Mutare specialty: active if unit has `DRAGON_NATURE` bonus
+
+```json
+	"limiters" : [
+		{
+			"parameters" : [ "DRAGON_NATURE" ],
+			"type" : "HAS_ANOTHER_BONUS_LIMITER"
+		}
+	],
+```
+
 ### CREATURE_TYPE_LIMITER
 
+Bonus is only active on creatures of specified type
+
 Parameters:
 
 - Creature id (string)
-- (optional) include upgrades - default is false
+- (optional) include upgrades - default is false. If creature has multiple upgrades, or upgrades have their own upgrades, all such creatures will be affected. Special upgrades such as upgrades via specialties (Dragon, Gelu) are not affected
+
+Example:
+
+```json
+"limiters": [ {
+	"type":"CREATURE_TYPE_LIMITER",
+	"parameters": [ "angel", true ]
+} ],
+```
 
 ### CREATURE_ALIGNMENT_LIMITER
 
+Bonus is only active on creatures of factions of specified alignment
+
 Parameters:
 
-- Alignment identifier
+- Alignment identifier, `good`, `evil`, or `neutral`
 
 ### CREATURE_LEVEL_LIMITER
 
@@ -82,13 +113,6 @@ Parameters:
 
 Example:
 
-```json
-"limiters": [ {
-	"type":"CREATURE_TYPE_LIMITER",
-	"parameters": [ "angel", true ]
-} ],
-```
-
 ```json
 "limiters" : [ {
 	"type" : "CREATURE_TERRAIN_LIMITER",
@@ -102,6 +126,10 @@ Parameters:
 
 - List of affected battlefield hexes
 
+For reference on tiles indexes see image below:
+
+![Battlefield Hexes Layout](../../images/Battle_Field_Hexes.svg)
+
 ## Aggregate Limiters
 
 The following limiters must be specified as the first element of a list,

docs/modders/Bonus/Bonus_Updaters.md

@@ -1,12 +1,10 @@
 # Bonus Updaters
 
-TODO: this page may be incorrect or outdated
-
 Updaters come in two forms: simple and complex. Simple updaters take no
 parameters and are specified as strings. Complex updaters do take
 parameters (sometimes optional), and are specified as structs.
 
-Check the files in *config/heroes/* for additional usage examples.
+Check the files in `config/heroes/` for additional usage examples.
 
 ## GROWS_WITH_LEVEL
 
@@ -14,8 +12,7 @@ Check the files in *config/heroes/* for additional usage examples.
 - Parameters: valPer20, stepSize=1
 - Effect: Updates val to `ceil(valPer20 * floor(heroLevel / stepSize) / 20)`
 
-Example: The following updater will cause a bonus to grow by 6 for every
-40 levels. At first level, rounding will cause the bonus to be 0.
+Example: The following updater will cause a bonus to grow by 6 for every 40 levels. At first level, rounding will cause the bonus to be 0.
 
 ```json
 "updater" : {
@@ -24,8 +21,7 @@ Example: The following updater will cause a bonus to grow by 6 for every
 }
 ```
 
-Example: The following updater will cause a bonus to grow by 3 for every
-20 levels. At first level, rounding will cause the bonus to be 1.
+Example: The following updater will cause a bonus to grow by 3 for every 20 levels. At first level, rounding will cause the bonus to be 1.
 
 ```json
 "updater" : {
@@ -36,10 +32,8 @@ Example: The following updater will cause a bonus to grow by 3 for every
 
 Remarks:
 
-- The rounding rules are designed to match the attack/defense bonus
-    progression for heroes with creature specialties in HMM3.
-- There is no point in specifying val for a bonus with a
-    GROWS_WITH_LEVEL updater.
+- The rounding rules are designed to match the attack/defense bonus progression for heroes with creature specialties in HMM3.
+- There is no point in specifying val for a bonus with a GROWS_WITH_LEVEL updater.
 
 ## TIMES_HERO_LEVEL
 
@@ -48,14 +42,10 @@ Remarks:
 
 Usage: `"updater" : "TIMES_HERO_LEVEL"`
 
-Remark: This updater is redundant, in the sense that GROWS_WITH_LEVEL
-can also express the desired scaling by setting valPer20 to 20\*val. It
-has been added for convenience.
-
 ## TIMES_STACK_LEVEL
 
 - Type: Simple
-- Effect: Updates val to `val * stackLevel`
+- Effect: Updates val to `val * stackLevel`, where `stackLevel` is level of stack (Pikeman is level 1, Angel is level 7)
 
 Usage:
 
@@ -66,7 +56,7 @@ Remark: The stack level for war machines is 0.
 ## DIVIDE_STACK_LEVEL
 
 - Type: Simple
-- Effect: Updates val to `val / stackLevel`
+- Effect: Updates val to `val / stackLevel`, where `stackLevel` is level of stack (Pikeman is level 1, Angel is level 7)
 
 Usage:
 
@@ -87,4 +77,4 @@ Usage:
 
 ## BONUS_OWNER_UPDATER
 
-TODO: document me
+Helper updater for proper functionality of `OPPOSITE_SIDE` limiter

docs/modders/Entities_Format/Battle_Obstacle_Format.md

@@ -38,10 +38,10 @@ Non-absolute obstacles specify their coordinates relative to bottom-left corner
 
 For example, obstacle that blocks tiles `[1, 2, 3, -15, -16, -31]` would result in following layout on the battlefield:
 
-![Battlefield Relative Obstacle Example](../Battle_Field_Relative_Obstacle.svg)
+![Battlefield Relative Obstacle Example](../../images/Battle_Field_Relative_Obstacle.svg)
 
 ### Absolute obstacles
 
 Absolute obstacles operate in absolute coordinates. Because of that, blocked tiles contains list of indexes of blocked tiles. For reference on tiles indexes see image below:
 
-![Battlefield Hexes Layout](../Battle_Field_Hexes.svg)
+![Battlefield Hexes Layout](../../images/Battle_Field_Hexes.svg)

docs/modders/Entities_Format/Battlefield_Format.md

@@ -28,5 +28,5 @@
 
 Impassable hexes operate in absolute coordinates. For reference on tiles indexes see image below:
 
-![Battlefield Hexes Layout](../images/Battle_Field_Hexes.svg)
+![Battlefield Hexes Layout](../../images/Battle_Field_Hexes.svg)