From 54de24c687dbd6d2d43548d3efa1ec545228fac5 Mon Sep 17 00:00:00 2001
From: Ivan Savenko <saven.ivan@gmail.com>
Date: Wed, 11 Jun 2025 17:53:16 +0300
Subject: [PATCH] Document new updaters, review old docs

---
 docs/modders/Bonus/Bonus_Updaters.md | 52 ++++++++++++++++++++--------
 1 file changed, 37 insertions(+), 15 deletions(-)

diff --git a/docs/modders/Bonus/Bonus_Updaters.md b/docs/modders/Bonus/Bonus_Updaters.md
index fef6f5346..7404dc650 100644
--- a/docs/modders/Bonus/Bonus_Updaters.md
+++ b/docs/modders/Bonus/Bonus_Updaters.md
@@ -8,16 +8,15 @@ Check the files in `config/heroes/` for additional usage examples.
 
 ## GROWS_WITH_LEVEL
 
-- Type: Complex
-- Parameters: valPer20, stepSize=1
-- Effect: Updates val to `ceil(valPer20 * floor(heroLevel / stepSize) / 20)`
+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.
 
 ```json
 "updater" : {
-    "parameters" : [ 6, 2 ],
-    "type" : "GROWS_WITH_LEVEL"
+    "type" : "GROWS_WITH_LEVEL",
+    "valPer20" : 6,
+    "stepSize" : 2
 }
 ```
 
@@ -25,8 +24,9 @@ Example: The following updater will cause a bonus to grow by 3 for every 20 leve
 
 ```json
 "updater" : {
-    "parameters" : [ 3 ],
-    "type" : "GROWS_WITH_LEVEL"
+    "type" : "GROWS_WITH_LEVEL",
+    "valPer20" : 6,
+    "stepSize" : 2
 }
 ```
 
@@ -37,15 +37,22 @@ Remarks:
 
 ## TIMES_HERO_LEVEL
 
-- Type: Simple
-- Effect: Updates val to `val * heroLevel`
+Effect: Updates val to `val * heroLevel / stepSize`
 
 Usage: `"updater" : "TIMES_HERO_LEVEL"`
 
+Usage with stepSize greater than one:
+
+```json
+"updater" : {
+    "type" : "TIMES_HERO_LEVEL",
+    "stepSize" : 2
+}
+```
+
 ## TIMES_STACK_LEVEL
 
-- Type: Simple
-- Effect: Updates val to `val * stackLevel`, where `stackLevel` is level of stack (Pikeman is level 1, Angel is level 7)
+Updates val to `val * stackLevel`, where `stackLevel` is level of stack (Pikeman is level 1, Angel is level 7)
 
 Usage:
 
@@ -55,8 +62,7 @@ Remark: The stack level for war machines is 0.
 
 ## DIVIDE_STACK_LEVEL
 
-- Type: Simple
-- Effect: Updates val to `val / stackLevel`, where `stackLevel` is level of stack (Pikeman is level 1, Angel is level 7)
+Updates val to `val / stackLevel`, where `stackLevel` is level of stack (Pikeman is level 1, Angel is level 7)
 
 Usage:
 
@@ -66,8 +72,7 @@ Remark: The stack level for war machines is 0.
 
 ## TIMES_HERO_LEVEL_DIVIDE_STACK_LEVEL
 
-- Type: Simple
-- Effect: Same effect as `TIMES_HERO_LEVEL` combined with `DIVIDE_STACK_LEVEL`: `val * heroLevel / stackLevel`
+Effect: Same effect as `TIMES_HERO_LEVEL` combined with `DIVIDE_STACK_LEVEL`: `val * heroLevel / stackLevel`
 
 Intended to be used as hero bonus (such as specialty, skill, or artifact), for bonuses that affect units (Example: Adela Bless specialty)
 
@@ -75,6 +80,23 @@ Usage:
 
 `"updater" : "TIMES_HERO_LEVEL_DIVIDE_STACK_LEVEL"`
 
+## TIMES_STACK_SIZE
+
+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:
+
+```json
+"updater" : {
+    "type" : "TIMES_STACK_SIZE",
+    "minimum" : 0,
+    "maximum" : 100,
+    "stepSize" : 2
+}
+```
+
 ## BONUS_OWNER_UPDATER
 
 Helper updater for proper functionality of `OPPOSITE_SIDE` limiter