Merge pull request #5844 from IvanSavenko/bonus_fixes

Fixes to bonus system functionality

docs/modders/Bonus/Bonus_Propagators.md

@@ -1,10 +1,22 @@
 # Bonus Propagators
 
+Propagators allow to propagate bonus effect "upwards". For example, they can be used to make unit ability battle-wide, or to provide some bonuses to hero. See [Bonus System Guide](../Guides/Bonus_System.md) for more information.
+
 ## 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.
-- 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.
+- `ARMY`: Propagators that allow bonuses to be transferred to an army. It is typically used by creature abilities to affect the army that the creature is part of.
+- `HERO`: Similar to `ARMY`, but works only with armies led by heroes.
+- `TOWN`: Similar to `ARMY`, but only affects units that are part of the town garrison.
+- `TOWN_AND_VISITOR`: Propagator that allows the town and the visiting hero to interact. It can be used to propagate the effects of town buildings to the visiting hero outside of combat or the effects of the hero to the town (e.g. Legion artifacts)
+- `BATTLE_WIDE` - Propagator that allows bonuses to affect all entities in battles. It is typically used for creature abilities or artifacts that need to affect either both sides or only the enemy side in combat.
+- `PLAYER`: The bonus affects all objects owned by the player. Used by the Statue of Legion.
+- `TEAM`: The bonus affects all objects owned by the player and their allies.
+- `GLOBAL_EFFECT`: This effect influences all creatures, towns and recruited heroes on the map.
+
+## Deprecated propagators
+
+These propagators are still supported, but in future they may be removed.
+
+- `VISITED_TOWN_AND_VISITOR`: Replaced by `TOWN_AND_VISITOR`
+- `PLAYER_PROPAGATOR`: Replaced by `PLAYER`
+- `TEAM_PROPAGATOR`: Replaced by `TEAM`

docs/modders/Bonus/Bonus_Updaters.md

@@ -84,19 +84,78 @@ Usage:
 
 Effect: Updates val to `val = clamp(val * floor(stackSize / stepSize), minimum, maximum)`, where stackSize is total number of creatures in current unit stack
 
-Parameters `minimum` and `maximum` are optional and can be dropped if not needed
+Example of short form with default parameters:
 
-Example:
+```json
+"updater" : "TIMES_STACK_SIZE"
+```
+
+Example of long form with custom parameters:
 
 ```json
 "updater" : {
     "type" : "TIMES_STACK_SIZE",
+    
+    // Optional, by default - unlimited
     "minimum" : 0,
+    
+    // Optional, by default - unlimited
     "maximum" : 100,
+    
+    // Optional, by default - 1
     "stepSize" : 2
 }
 ```
 
+## TIMES_ARMY_SIZE
+
+Effect: Updates val to `val = clamp(val * floor(stackSize / stepSize), minimum, maximum)`, where stackSize is total number of creatures in hero army that fulful filter
+
+Parameters:
+
+- `minimum`: minimum possible value of the bonus value. Unlimited by default
+- `maximum`: maximum possible value of the bonus value. Unlimited by default
+- `stepSize`: number of units needed to increase updater multiplier by 1
+- `filteredCreature`: identifier of specific unit to filter
+- `filteredLevel`: level of units that need to be counted. Redundant if `filteredCreature` is used
+- `filteredFaction`: faction of units that need to be counted. Redundant if `filteredCreature` is used
+
+Filtering for specific unit:
+
+```json
+"updater" : {
+    "type" : "TIMES_ARMY_SIZE",
+    "filteredCreature" : "pikeman",
+    
+    // Optional, by default - unlimited
+    "minimum" : 0,
+    
+    // Optional, by default - unlimited
+    "maximum" : 100,
+    
+    // Optional, by default - 1
+    "stepSize" : 2
+}
+```
+
+Filtering for specific faction:
+
+```json
+"updater" : {
+    "type" : "TIMES_STACK_SIZE",
+    "filteredFaction" : "castle"
+}
+```
+
+Filtering for specific unit level:
+
+```json
+"updater" : {
+    "type" : "TIMES_STACK_SIZE",
+    "filteredLevel" : 2
+}
+```
+
 ## BONUS_OWNER_UPDATER
 
 Helper updater for proper functionality of `OPPOSITE_SIDE` limiter