Update documentation

docs/modders/Map_Objects/Rewardable.md

@@ -4,6 +4,7 @@
 - [Base object definition](#base-object-definition)
 - [Configurable object definition](#configurable-object-definition)
 - [Base object definition](#base-object-definition)
+- [Variables Parameters definition](#variables-parameters-definition)
 - [Reset Parameters definition](#reset-parameters-definition)
 - [Appear Chance definition](#appear-chance-definition)
 - [Configurable Properties](#configurable-properties)
@@ -17,12 +18,18 @@
 - - [Movement Percentage](#movement-percentage)
 - - [Primary Skills](#primary-skills)
 - - [Secondary Skills](#secondary-skills)
+- - [Can learn skills](#can-learn-skills)
 - - [Bonus System](#bonus-system)
 - - [Artifacts](#artifacts)
 - - [Spells](#spells)
+- - [Can learn spells](#can-learn-spells)
 - - [Creatures](#creatures)
 - - [Creatures Change](#creatures-change)
 - - [Spell cast](#spell-cast)
+- - [Fog of War](#fog-of-war)
+- - [Player color](#player-color)
+- - [Hero types](#hero-types)
+- - [Hero classes](#hero-classes)
 
 ## 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.
@@ -92,20 +99,47 @@ 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}"
 
+    // Alternative object description that will be used in place of generic description after player visits this object and reveals its content
+    // For example, Tree of Knowledge will display cost of levelup (gems or gold) only after object has been visited once
+    "description" : "",
+
     // object will be disappeared after taking reward is set to true
-    "removeObject": false
+    "removeObject": false,
 
     // See "Configurable Properties" section for additional parameters
     <additional properties>
   }
 ],
 
+/// List of variables shared between all rewards and limiters
+/// See "Variables" section for description
+"variables" : {
+}
+
 // 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
 "onEmptyMessage": "",
 
+// Object description that will be shown when player right-clicks object
+"description" : "",
+
+// If set to true, right-clicking previously visited object would show preview of its content. For example, Witch Hut will show icon with provided skill
+"showScoutedPreview" : true,
+
+// Text that should be used if hero has not visited this object. If not specified, game will use standard "(Not visited)" text
+"notVisitedTooltip" : "",
+
+// Text that should be used if hero has already visited this object. If not specified, game will use standard "(Already visited)" text
+"visitedTooltip" : "",
+
+// Used only if visitMode is set to "limiter"
+// Hero that passes this limiter will be considered to have visited this object
+// Note that if player or his allies have never visited this object, it will always show up as "not visited"
+"visitLimiter" : {
+},
+
 // Alternatively, rewards for empty state:
 // Format is identical to "rewards" section, allowing to fine-tune behavior in this case, including giving awards or different messages to explain why object is "empty". For example, Tree of Knowledge will give different messages depending on whether it asks for gold or crystals
 "onEmpty" : [
@@ -133,6 +167,7 @@ Rewardable object is defined similarly to other objects, with key difference bei
 // determines who can revisit object before reset
 // "once",     - object can only be visited once. First visitor takes it all.
 // "hero",     - object can be visited if this hero has not visited it before
+// "limiter",  - object can be visited if hero fails to fulfill provided limiter
 // "player",   - object can be visited if this player has not visited it before
 // "bonus"     - object can be visited if hero no longer has bonus from this object (including any other object of the same type)
 // "unlimited" - no restriction on revisiting.
@@ -147,6 +182,39 @@ Rewardable object is defined similarly to other objects, with key difference bei
 }
 ```
 
+## Variables Parameters definition
+
+This property allows defining "variables" that are shared between all rewards and limiters of this object.
+Variables are randomized only once, so you can use them multiple times for example, to give skill only if hero does not have this skill (e.g. Witch Hut).
+
+Example of creation of a variable named "gainedSkill" of type "secondarySkill":
+```json
+"variables" : {
+	"secondarySkill" : {
+		"gainedSkill" : {
+			"noneOf" : [
+				"leadership",
+				"necromancy"
+			]
+		}
+	}
+}
+```
+
+Possible variable types:
+- number: can be used in any place that expects a number
+- artifact
+- spell
+- primarySkill
+- secondarySkill
+
+To reference variable in limiter prepend variable name with '@' symbol:
+```json
+"secondary" : {
+    "@gainedSkill" : 1
+},
+```
+
 ## Reset Parameters definition
 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.
@@ -349,13 +417,21 @@ Keep in mind, that all randomization is performed on map load and on object rese
 ]
 ```
 
+### Can learn skills
+
+- Can be used as limiter. Hero must have free skill slot to pass limiter
+
+```json
+    "canLearnSkills" : true
+```
+
 ### Bonus System
 - 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`
 
-```jsonc
+```json
 "bonuses" : [
     {
         "type" : "MORALE", 
@@ -414,6 +490,22 @@ Keep in mind, that all randomization is performed on map load and on object rese
 ],
 ```
 
+### Can learn spells
+
+- Can be used as limiter. Hero must be able to learn spell to pass the limiter
+- Hero is considered to not able to learn the spell if:
+- - he already has specified spell
+- - he does not have a spellbook 
+- - he does not have sufficient Wisdom level for this spell
+
+```json
+    "canLearnSpells" : [
+        "magicArrow"
+],
+```
+
+canLearnSpells
+
 ### Creatures
 - Can be used as limiter
 - Can be used as reward, to give new creatures to a hero
@@ -445,13 +537,32 @@ Keep in mind, that all randomization is performed on map load and on object rese
 - 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)
 
-```jsonc
+```json
 "spellCast" : {
     "spell" : "townPortal",
     "schoolLevel": 3
 }
 ```
 
+### Fog of War
+
+- Can NOT be used as limiter
+- Can be used as reward, to reveal or hide affected tiles
+- If radius is not specified, then all matching tiles on the map will be affected
+- It is possible to specify which terrain classes should be affected. Tile will be affected if sum of values its classes is positive. For example, `"water" : 1` will affect all water tiles, while `"surface" : 1, "subterra" : -1` will include terrains that have "surface" flag but do not have "subterra" flag
+- If 'hide' is set to true, then instead of revealing terrain, game will hide affected tiles for all other players
+
+```json
+"revealTiles" : {
+	"radius" : 20,
+	"surface" : 1,
+	"subterra" : 1,
+	"water" : 1,
+	"rock" : 1,
+	"hide" : true
+}
+```
+
 ### Player color
 - Can be used as limiter
 - Can NOT be used as reward