Rewardable
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.
Configurable object definition
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 |
|
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":
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:
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.
- If
visitors
is set to true, game will reset list of visitors (heroes and players) on start of new period, allowing revisits of objects withvisitMode
set toonce
,hero
, orplayer
. Objects with visit mode set tobonus
are not affected. In order to allow revisit such objects use appropriate bonus duration (e.g.ONE_DAY
orONE_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"
Appear Chance definition
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. Note that object that uses appearChance MUST have continuous range for every value in 0-99 range. For example, object with 3 different rewards may want to define them as
"min" : 0, "max" : 33
"min" : 33, "max" : 66
"min" : 66, "max" : 100
In other words, min chance of second reward must be equal to max chance of previous reward
Configurable Properties
Unless stated othervice, all numbers in this section can be replaced with random values, e.g.
In this case, actual value for minLevel will be picked randomly.
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
- Can only be used as limiter. To pass, number of days since game started must be at equal or greater than this value
Resource
- Can be used as limiter. To pass, player needs to have specified resources. Note that limiter will NOT take resources.
- 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
- Alternative format that allows random selection of a resource type
Hero Experience
- Can be used as limiter
- Can be used as reward to grant experience to hero
Hero Level
- Can be used as limiter. Hero requires to have at least specified level
- 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)
Mana Points
- 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
- 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.
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)
Movement Points
- 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.
Movement Percentage
- 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
Commander
- Can be used as limiter, hero must have alive commander
- If hero does not have commander (for example, in games without them), limiter will always fail
Primary Skills
- 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
- Each primary skill can be explicitly specified or randomly selected
- Possible values:
"attack", "defence", "spellpower", "knowledge"
Secondary Skills
- Can be used as limiter, hero must have secondary skill at least at specified level
- Can be used as reward, to grant secondary skills to hero
- 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)
- Each secondary skill can be explicitly specified or randomly selected
- Negative values can be used to downgrade or remove secondary skills from hero
Can learn skills
- Can be used as limiter. Hero must have free skill slot to pass limiter
Bonus System
- Can be used as reward, to grant bonus to visiting hero
- 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
- Can be used as a reward, to grant bonuses to commander of a visiting hero
- This option will have no effect if commander is not present, for example for players without WoG mod
- Granting bonuses to dead commander is possible. use
commanderAlive
limiter if you want to avoid this - Syntax identical to regular
bonuses
field
- Can be used as a reward, to grant bonuses to player that commands visiting hero
- Bonuses will remain even if hero is lost or fired. Use
bonuses
withPLAYER_PROPAGATOR
if you wish for bonus to be removed when hero is lost - Syntax identical to regular
bonuses
field
Artifact Slots
- Can be used as limiter, hero must have listed slots empty to pass the limiter
- Slots occupied by components of combined artifacts are considered to be full
- Can be used as a reward, to remove artifact that is present in slot
- Components of a combined artifact can not be removed in this way
List of supported slots names:
HEAD
- helmet slotSHOULDERS
- slot used by capesNECK
- slot used by neclaces artifactsRIGHT_HAND
- slot for weapons / swordsLEFT_HAND
- slot for shieldsTORSO
- chest slot for armorsRIGHT_RING
- ring slot located next to weapon slotLEFT_RING
- ring slot located next to shield slotFEET
- slot for bootsMISC1
- top-most miscellaneous slotMISC2
- 2nd from top miscellaneous slotMISC3
- 3rd from top miscellaneous slotMISC4
- bottom-right miscellaneous slotMISC5
- bottom-left miscellaneous slotSPELLBOOK
- Hero's spellbook. Its removal is untested and may lead to unintended side effectsMACH1
- Ballista, or alternative war machine from modMACH2
- Ammo Cart, or alternative war machine from modMACH3
- First Aid tent, or alternative war machine from modMACH4
- Catapult slot. Its removal is untested and may lead to unintended side effects
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
- Artifacts added as reward will be used for text substitution. First
%s
in text string will be replaced with name of an artifact
- Alternative format, random artifact generation.
- For artifact class possible values are "TREASURE", "MINOR", "MAJOR", "RELIC"
- Artifact value range can be specified with min value and max value
Taking Artifacts
- Can be used as reward, to take artifact from hero
- Taking part of a combined artifact would disassemble it
- Artifacts can be taken from either equipment or from backpack slots
- Format is identical to Artifacts
Scrolls
- Can be used as limiter, hero must have scroll either equipped or in backpack
- Can be used as reward, to give new scroll to a hero
- Format is identical to Spells
Taking Scrolls
- Can be used as reward, to take scroll from hero
- Format is identical to Spells
Spells
- Can be used as limiter
- Can be used as reward, to give new spell to a hero
- Spells added as reward will be used for text substitution. First
%s
in text string will be replaced with spell name
- Alternative format, random spell selection
- Spell can be selected from specifically selected school
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
Creatures
- Can be used as limiter
- Can be used as reward, to give new creatures to a hero
- For map objects, if hero does not have enough free slots, game will show selection dialog to pick troops to keep
- For town buildings, hero must either have free slot(s) to take them, or have creatures of this type. Othervice reward would fail to give any creatures
- It is possible to specify probability to receive upgraded creature
- Additionally, it is possible to check whether tested troops can be removed, in other words - whether hero has any creatures other than those specified in
creatures
field usinghasExtraCreatures
key - Following check will pass only if hero either has more archers than 20, or has exactly 20 archers and any creatures other than that
Taking Creatures
- Can be used as reward, to take creatures from a hero
- Attempting to take more creatures than hero has, or creatures that hero does not have is legal
- It is not possible to take entire army, however it is possible to replace entire army by providing new creatures.
- Format is identical to Creatures
Creature receiving test
- Can be used as limiter, to test whether hero can accept specified creatures without abandoning any units
- Check will pass if hero has enough free slots to accept creatures, or if hero already has specified creatures, or if hero has units that can be merged to create space for new troops
- Note that attempting to give more troops than hero can accept is legal, and will show unit selection dialog on which hero will have to abandon some of his creatures
Guards
- When used in a reward, these creatures will be added to guards of the objects
- Hero must defeat all guards before being able to receive rewards
- Guards are only reset when object rewards are reset
- Requires
guardsLayout
property to be set in main part of object configuration - It is possible to add up to 7 slots of creatures
- Guards of the same creature type will never merge or rearrange their stacks
Creatures Change
- 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
Spell cast
- 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)
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
Player color
- Can be used as limiter
- Can NOT be used as reward
- Only players with specific color can pass the limiter
Hero types
- Can be used as limiter
- Can NOT be used as reward
- Only specific heroes can pass the limiter
Hero classes
- Can be used as limiter
- Can NOT be used as reward
- Only heroes belonging to specific classes can pass the limiter