games/vcmi
1
0
Fork 0
mirror of https://github.com/vcmi/vcmi.git synced 2025-11-06 09:09:40 +02:00
Code Issues Releases Activity

Updated map object and bonuses documentations

Browse Source
This commit is contained in:
Ivan Savenko
2023-09-12 19:58:15 +03:00
parent c6588e0bd1
commit feb272e102
18 changed files with 439 additions and 551 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
config/schemas/bonus.json
View File

@@ -158,10 +158,10 @@
"description" : "addInfo" "description" : "addInfo"
}, },
"duration" : { "duration" : {
"anyOf" : [ "anyOf" : [
{ "type" : "string"}, { "type" : "string"},
{ "type" : "array", "items" : {"type" : "string"} } { "type" : "array", "items" : {"type" : "string"} }
], ],
"description" : "duration" "description" : "duration"
}, },
"turns" : { "turns" : {

2
config/schemas/objectTemplate.json
View File

@@ -18,7 +18,7 @@
}, },
"visitableFrom" : { "visitableFrom" : {
"type" : "array", "type" : "array",
"description" : "Directions from which this object is visible", "description" : "Directions from which hero can visit this object",
"minItems" : 3, "minItems" : 3,
"maxItems" : 3, "maxItems" : 3,
"items" : { "items" : {

161
docs/modders/Animation_Format.md
View File

@@ -1,13 +1,10 @@
< [Documentation](../Readme.md) / [Modding](Readme.md) / Animation Format < [Documentation](../Readme.md) / [Modding](Readme.md) / Animation Format
VCMI allows overriding HoMM3 .def files with .json replacement. Compared VCMI allows overriding HoMM3 .def files with .json replacement. Compared to .def this format allows:
to .def this format allows:
- Overriding individual frames from json file (e.g. icons) - Overriding individual frames from json file (e.g. icons)
- Modern graphics formats (targa, png - all formats supported by VCMI - Modern graphics formats (targa, png - all formats supported by VCMI image loader)
image loader) - Does not requires any special tools - all you need is text editor and images.
- Does not requires any special tools - all you need is text editor
and images.
# Format description # Format description
@@ -59,150 +56,62 @@ to .def this format allows:
# Creature animation groups # Creature animation groups
Animation for creatures consist from multiple groups, with each group Animation for creatures consist from multiple groups, with each group
representing specific one animation. VCMI uses groups as follows: representing one specific animation. VCMI uses groups as follows:
**Basic animations** **Basic animations**
- \[0\] Movement: Used for creature movement - [0] Movement: Used for creature movement
- \[1\] Mouse over: Used for random idle movements and when mouse is - [1] Mouse over: Used for random idle movements and when mouse is moved on the creature
moved on the creature - [2] Idle: Basic animation that plays continuously when stack is not acting
- \[2\] Idle: Basic animation that plays continuously when stack is - [3] Hitted: Animation that plays whenever stack is hit
not acting - [4] Defence: Alternative animation that plays when stack is defending and was hit in melee
- \[3\] Hitted: Animation that plays whenever stack is hit - [5] Death: Animation that plays when stack dies
- \[4\] Defence: Alternative animation that plays when stack is - [6] Death (ranged): Alternative animation, plays when stack is killed by ranged attack
defending and was hit in melee
- \[5\] Death: Animation that plays when stack dies
- \[6\] Death (ranged): Alternative animation, plays when stack is
killed by ranged attack
**Rotation animations** **Rotation animations**
- \[7\] Turn left: Animation for rotating stack, only contains first - [7] Turn left: Animation for rotating stack, only contains first part of animation, with stack turning towards viewer
part of animation, with stack turning towards viewer - [8] Turn right: Second part of animation for rotating stack
- \[8\] Turn right: Second part of animation for rotating stack - [9] (unused in vcmi, present in H3 files)
- \[9\] (unused in vcmi, present in H3 files) - [10] (unused in vcmi, present in H3 files)
- \[10\] (unused in vcmi, present in H3 files)
**Melee attack animations** **Melee attack animations**
- \[11\] Attack (up): Attacking animation, stack facing upwards - [11] Attack (up): Attacking animation, stack facing upwards
- \[12\] Attack (front): Attacking animation, stack facing front - [12] Attack (front): Attacking animation, stack facing front
- \[13\] Attack (down): Attacking animation, stack facing downwards - [13] Attack (down): Attacking animation, stack facing downwards
**Ranged attack animations** **Ranged attack animations**
- \[14\] Shooting (up): Ranged attack animation, stack facing upwards - [14] Shooting (up): Ranged attack animation, stack facing upwards
- \[15\] Shooting (front): Ranged attack animation, stack facing front - [15] Shooting (front): Ranged attack animation, stack facing front
- \[16\] Shooting (down): Ranged attack animation, stack facing - [16] Shooting (down): Ranged attack animation, stack facing downwards
downwards
**Special animations** **Special animations**
- \[17\] Special (up): Special animation, used if dedicated cast or - [17] Special (up): Special animation, used if dedicated cast or group attack animations were not found
group attack animations were not found - [18] Special (front): Special animation, used if dedicated cast or group attack animations were not found
- \[18\] Special (front): Special animation, used if dedicated cast or - [19] Special (down): Special animation, used if dedicated cast or group attack animations were not found
group attack animations were not found
- \[19\] Special (down): Special animation, used if dedicated cast or
group attack animations were not found
**Additional H3 animations** **Additional H3 animations**
- \[20\] Movement start: Animation that plays before movement - [20] Movement start: Animation that plays before movement animation starts.
animation starts. - [21] Movement end: Animation that plays after movement animation ends.
- \[21\] Movement end: Animation that plays after movement animation
ends.
**Additional VCMI animations** **Additional VCMI animations**
- \[22\] \[VCMI 1.0\] Dead: Animation that plays when creature is - [22] Dead: Animation that plays when creature is dead. If not present, will consist from last frame from "Death" group
dead. If not present, will consist from last frame from "Death" - [23] Dead (ranged): Animation that plays when creature is dead after ranged attack. If not present, will consist from last frame from "Death (ranged)" group
group - [24] Resurrection: Animation that plays when creature is resurrected. If not present, will consist from reversed version of "Death" animation
- \[23\] \[VCMI 1.0\] Dead (ranged): Animation that plays when
creature is dead after ranged attack. If not present, will consist
from last frame from "Death (ranged)" group
- \[24\] \[VCMI 1.2\] Resurrection: Animation that plays when creature
is resurrected. If not present, will consist from reversed version
of "Death" animation
**Spellcasting animations** **Spellcasting animations**
- \[30\] \[VCMI 1.2\] Cast (up): Used when creature casts spell facing - [30] Cast (up): Used when creature casts spell facing upwards
upwards - [31] Cast (front): Used when creature casts spell facing front
- \[31\] \[VCMI 1.2\] Cast (front): Used when creature casts spell - [32] Cast (down): Used when creature casts spell facing downwards
facing front
- \[32\] \[VCMI 1.2\] Cast (down): Used when creature casts spell
facing downwards
**Group attack animations** **Group attack animations**
- \[40\] \[VCMI 1.2\] Group Attack (up): Used when creature attacks - [40] Group Attack (up): Used when creature attacks multiple target, with primary target facing up (Dragon Breath attack, or creatures like Hydra)
multiple target, with primary target facing up (Dragon Breath - [41] Group Attack (front): Used when creature attacks multiple target, with primary target facing front (Dragon Breath attack, or creatures like Hydra)
attack, or creatures like Hydra) - [42] Group Attack (down): Used when creature attacks multiple target, with primary target facing downwards (Dragon Breath attack, or creatures like Hydra)
- \[41\] \[VCMI 1.2\] Group Attack (front): Used when creature attacks
multiple target, with primary target facing front (Dragon Breath
attack, or creatures like Hydra)
- \[42\] \[VCMI 1.2\] Group Attack (down): Used when creature attacks
multiple target, with primary target facing downwards (Dragon Breath
attack, or creatures like Hydra)
# Proposed format extensions
## Texture atlas format
**TODO**
- arbitrary texture coordinates
- margins
- grid-like layout
### Texture atlas format
``` javascript
{
// Base path of all images in animation. Optional.
// Can be used to avoid using long path to images
// If a path is a filename is is treated as single texture atlas
"basepath" : "path/to/images/atlas/bitmap.png",
// List of sequences / groups in animation
"sequences" :
[
{
// Index of group, zero-based
"group" : 1,
// List of files in this group
"frames" :
[
{"x":0, "y":0, "w": 64, "h": 64},
{"x":64, "y":0, "w": 64, "h": 64}
...
]
},
...
]
}
```
### Texture atlas grid format
``` javascript
{
// filename is is treated as single texture atlas
"basepath" : "path/to/images/atlas/bitmap.png",
//optional, atlas is a grid with same size images
//located left to right, top to bottom
//[columns, rows]
//default [1,1]
"gridCols":3,
"gridRows":3,
// List of sequences / groups in animation
// sequence index -> images count in sequence
"sequences" :
[
1,3,5
]
}
```

17
docs/modders/Bonus/Bonus_Duration_Types.md
View File

@@ -1,19 +1,16 @@
< [Documentation](../../Readme.md) / [Modding](../Readme.md) / [Bonus Format](../Bonus_Format.md) / Bonus Duration Types < [Documentation](../../Readme.md) / [Modding](../Readme.md) / [Bonus Format](../Bonus_Format.md) / Bonus Duration Types
Bonus may have any of these durations. They acts in disjunction. Bonus may have any of these durations. They acts in disjunction.
## List of all bonus duration types ## List of all bonus duration types
- PERMANENT - PERMANENT
- ONE_BATTLE //at the end of battle - ONE_BATTLE: at the end of battle
- ONE_DAY //at the end of day - ONE_DAY: at the end of day
- ONE_WEEK //at the end of week (bonus lasts till the end of week, - ONE_WEEK: at the end of week (bonus lasts till the end of week, NOT 7 days)
thats NOT 7 days - N_TURNS: used during battles, after battle bonus is always removed
- N_TURNS //used during battles, after battle bonus is always removed
- N_DAYS - N_DAYS
- UNTIL_BEING_ATTACKED //removed after any damage-inflicting attack - UNTIL_BEING_ATTACKED: removed after any damage-inflicting attack
- UNTIL_ATTACK //removed after attack and counterattacks are performed - UNTIL_ATTACK: removed after attack and counterattacks are performed
- STACK_GETS_TURN //removed when stack gets its turn - used for - STACK_GETS_TURN: removed when stack gets its turn - used for defensive stance
defensive stance
- COMMANDER_KILLED - COMMANDER_KILLED

29
docs/modders/Bonus/Bonus_Limiters.md
View File

@@ -4,11 +4,14 @@
The limiters take no parameters: The limiters take no parameters:
- SHOOTER_ONLY - SHOOTER_ONLY
- DRAGON_NATURE - DRAGON_NATURE
- IS_UNDEAD - IS_UNDEAD
- CREATURE_NATIVE_TERRAIN - CREATURE_NATIVE_TERRAIN
- OPPOSITE_SIDE - CREATURE_FACTION
- SAME_FACTION
- CREATURES_ONLY
- OPPOSITE_SIDE
Example: Example:
@@ -56,7 +59,15 @@ Parameters:
- Alignment identifier - Alignment identifier
### CREATURE_FACTION_LIMITER ### CREATURE_LEVEL_LIMITER
If parameters is empty, level limiter works as CREATURES_ONLY limiter
Parameters:
- Minimal level
- Maximal level
### FACTION_LIMITER
Parameters: Parameters:
@@ -84,6 +95,12 @@ Example:
} ] } ]
``` ```
### UNIT_ON_HEXES
Parameters:
- List of affected battlefield hexes
## Aggregate Limiters ## Aggregate Limiters
The following limiters must be specified as the first element of a list, The following limiters must be specified as the first element of a list,

29
docs/modders/Bonus/Bonus_Propagators.md
View File

@@ -2,26 +2,9 @@
## Available propagators ## Available propagators
- BATTLE_WIDE - BATTLE_WIDE: Affects both sides during battle
- VISITED_TOWN_AND_VISITOR: Used with Legion artifacts (town visited by hero)
Affects both sides during battle - 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).
- VISITED_TOWN_AND_VISITOR - 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.
Used with Legion artifacts (town visited by hero)
- PLAYER_PROPAGATOR
Bonus will affect all objects owned by player. Used by Statue of Legion.
- TEAM_PROPAGATOR
Bonus will affect all objects owned by player and his allies.
- HERO
Bonus will be transferred to hero (for example from stacks in his army).
- GLOBAL_EFFECT
This effect will influence all creatures, heroes and towns on the map.

25
docs/modders/Bonus/Bonus_Range_Types.md
View File

@@ -2,21 +2,18 @@
# List of all Bonus range types # List of all Bonus range types
- NO_LIMIT - NO_LIMIT
- ONLY_DISTANCE_FIGHT - ONLY_DISTANCE_FIGHT
- ONLY_MELEE_FIGHT - ONLY_MELEE_FIGHT
- ONLY_ENEMY_ARMY (before 1.2)
TODO: in 0.91 ONLY_MELEE_FIGHT / ONLY_DISTANCE_FIGHT range types work TODO: ONLY_MELEE_FIGHT / ONLY_DISTANCE_FIGHT range types work ONLY with creature attack, should be extended to all battle abilities.
ONLY with creature attack, should be extended to all battle abilities.
(1.2+) For replacing ONLY_ENEMY_ARMY alias, you should use the following For replacing ONLY_ENEMY_ARMY alias, you should use the following parameters of bonus:
parameters of bonus:
"propagator": "BATTLE_WIDE", ```
"propagationUpdater" : "BONUS_OWNER_UPDATER", "propagator": "BATTLE_WIDE",
"limiters" : [ "OPPOSITE_SIDE" ] "propagationUpdater" : "BONUS_OWNER_UPDATER",
"limiters" : [ "OPPOSITE_SIDE" ]
```
If some propagators was set before, it was actually ignored and should If some propagators was set before, it was actually ignored and should be replaced to code above. And OPPOSITE_SIDE limiter should be first, if any other limiters exists.
be replaced to code above. And OPPOSITE_SIDE limiter should be first, if
any other limiters exists.

37
docs/modders/Bonus/Bonus_Sources.md
View File

@@ -2,22 +2,21 @@
# List of all possible bonus sources # List of all possible bonus sources
- ARTIFACT - ARTIFACT
- ARTIFACT_INSTANCE - ARTIFACT_INSTANCE
- OBJECT - OBJECT
- CREATURE_ABILITY - CREATURE_ABILITY
- TERRAIN_NATIVE - TERRAIN_NATIVE
- TERRAIN_OVERLAY - TERRAIN_OVERLAY
- SPELL_EFFECT - SPELL_EFFECT
- TOWN_STRUCTURE - TOWN_STRUCTURE
- HERO_BASE_SKILL - HERO_BASE_SKILL
- SECONDARY_SKILL - SECONDARY_SKILL
- HERO_SPECIAL - HERO_SPECIAL
- ARMY - ARMY
- CAMPAIGN_BONUS - CAMPAIGN_BONUS
- SPECIAL_WEEK - SPECIAL_WEEK
- STACK_EXPERIENCE - STACK_EXPERIENCE
- COMMANDER - COMMANDER
- GLOBAL_EFFECT (before 1.2) - GLOBAL
- GLOBAL (after 1.2) - OTHER
- OTHER

205
docs/modders/Bonus/Bonus_Types.md
View File

@@ -1,14 +1,18 @@
< [Documentation](../../Readme.md) / [Modding](../Readme.md) / [Bonus Format](../Bonus_Format.md) / Bonus Types < [Documentation](../../Readme.md) / [Modding](../Readme.md) / [Bonus Format](../Bonus_Format.md) / Bonus Types
The bonuses were grouped according to their original purpose. The bonus The bonuses were grouped according to their original purpose. The bonus system allows them to propagate freely betwen the nodes, however they may not be recognized properly beyond the scope of original use.
system allows them to propagate freely betwen the nodes, however they
may not be recognized properly beyond the scope of original use.
# General-purpose bonuses # General-purpose bonuses
### NONE ### NONE
### MORALE, LUCK Special bonus that gives no effect
### MORALE
- val = value
### LUCK
- val = value - val = value
@@ -20,8 +24,6 @@ eg. for magic plains terrain and for magic school secondary skills
earth) earth)
- val - level - val - level
### NO_TYPE
### DARKNESS ### DARKNESS
- val = radius - val = radius
@@ -35,10 +37,6 @@ land
- val = number of movement points (100 points for a tile) - val = number of movement points (100 points for a tile)
### LAND_MOVEMENT, SEA_MOVEMENT (before 1.2)
- val = number of movement points (100 points for a tile)
### WATER_WALKING ### WATER_WALKING
- subtype: 1 - without penalty, 2 - with penalty - subtype: 1 - without penalty, 2 - with penalty
@@ -47,7 +45,7 @@ land
- subtype: 1 - without penalty, 2 - with penalty - subtype: 1 - without penalty, 2 - with penalty
### NO_TERRAIN_PENALTY (since 0.98f) ### NO_TERRAIN_PENALTY
Hero does not get movement penalty on certain terrain type (Nomads Hero does not get movement penalty on certain terrain type (Nomads
ability). ability).
@@ -59,13 +57,7 @@ ability).
- uses subtype to pick skill - uses subtype to pick skill
- additional info if set: 1 - only melee, 2 - only distance - additional info if set: 1 - only melee, 2 - only distance
### SIGHT_RADIOUS (before 1.2) ### SIGHT_RADIUS
Additional bonus to range of sight (Used for Scouting secondary skill)
- val = distance in tiles
### SIGHT_RADIUS (after 1.2)
Sight radius of a hero. Used for base radius + Scouting secondary skill Sight radius of a hero. Used for base radius + Scouting secondary skill
@@ -85,19 +77,13 @@ all mana points are replenished every day
good and neutral creatures can be mixed without morale penalty good and neutral creatures can be mixed without morale penalty
### SECONDARY_SKILL_PREMY (before 1.2)
%
### SURRENDER_DISCOUNT ### SURRENDER_DISCOUNT
% %
### IMPROVED_NECROMANCY ### IMPROVED_NECROMANCY
Before 1.2: allows Necropolis units other than skeletons to be raised by Determine units which is raised by necromancy skill.
necromancy After 1.2: determine units which is raised by necromancy
skill.
- subtype: creature raised - subtype: creature raised
- val: Necromancer power - val: Necromancer power
@@ -110,7 +96,7 @@ skill.
` "addInfo" : 0` ` "addInfo" : 0`
` }` ` }`
### LEARN_BATTLE_SPELL_CHANCE (since 1.2) ### LEARN_BATTLE_SPELL_CHANCE
- subtype: 0 - from enemy hero, 1 - from entire battlefield (not - subtype: 0 - from enemy hero, 1 - from entire battlefield (not
implemented now). implemented now).
@@ -118,14 +104,14 @@ skill.
Note: used for Eagle Eye skill Note: used for Eagle Eye skill
### LEARN_BATTLE_SPELL_LEVEL_LIMIT (since 1.2) ### LEARN_BATTLE_SPELL_LEVEL_LIMIT
- subtype: school (-1 for all), others TODO - subtype: school (-1 for all), others TODO
- val: maximum learning level - val: maximum learning level
Note: used for Eagle Eye skill Note: used for Eagle Eye skill
### LEARN_MEETING_SPELL_LIMIT (since 1.2) ### LEARN_MEETING_SPELL_LIMIT
- subtype: school (-1 for all), others TODO - subtype: school (-1 for all), others TODO
- val: maximum learning level for learning a spell during hero - val: maximum learning level for learning a spell during hero
@@ -133,35 +119,34 @@ Note: used for Eagle Eye skill
Note: used for Scholar skill Note: used for Scholar skill
### ROUGH_TERRAIN_DISCOUNT (since 1.2) ### ROUGH_TERRAIN_DISCOUNT
- val: Non-road terrain discount in movement points - val: Non-road terrain discount in movement points
Note: used for Pathfinding skill Note: used for Pathfinding skill
### WANDERING_CREATURES_JOIN_BONUS (since 1.2) ### WANDERING_CREATURES_JOIN_BONUS
- val: value than used as level of diplomacy inside joining - val: value than used as level of diplomacy inside joining
probability calculating probability calculating
### BEFORE_BATTLE_REPOSITION (since 1.2) ### BEFORE_BATTLE_REPOSITION
- val: number of hexes - 1 than should be used as repositionable hexes - val: number of hexes - 1 than should be used as repositionable hexes before battle (like H3 tactics skill)
before battle (like H3 tactics skill)
### BEFORE_BATTLE_REPOSITION_BLOCK (since 1.2) Note that Tactics phase for both sides simultaneously is not supported
- val: value than block opposite tactics, if value of opposite tactics ### BEFORE_BATTLE_REPOSITION_BLOCK
is less than this value of your hero (for 1.2, double-side tactics
is not working).
### HERO_EXPERIENCE_GAIN_PERCENT (since 1.2) - val: value than block opposite tactics, if value of opposite tactics is less than this value of your hero.
### HERO_EXPERIENCE_GAIN_PERCENT
- val: how many experience hero gains from any source. There is a - val: how many experience hero gains from any source. There is a
global effect which set it by 100 (global value) and it is used as global effect which set it by 100 (global value) and it is used as
learning skill learning skill
### UNDEAD_RAISE_PERCENTAGE (since 1.2) ### UNDEAD_RAISE_PERCENTAGE
- val: Percentage of killed enemy creatures to be raised after battle - val: Percentage of killed enemy creatures to be raised after battle
as undead. as undead.
@@ -169,32 +154,32 @@ Note: used for Pathfinding skill
Note: used for Necromancy secondary skill, Necromancy artifacts and town Note: used for Necromancy secondary skill, Necromancy artifacts and town
buildings. buildings.
### MANA_PER_KNOWLEDGE (since 1.2) ### MANA_PER_KNOWLEDGE
- val: Percentage rate of translating 10 hero knowledge to mana, used - val: Percentage rate of translating 10 hero knowledge to mana, used
for intelligence and global bonus for intelligence and global bonus
### HERO_GRANTS_ATTACKS (since 1.2) ### HERO_GRANTS_ATTACKS
- subtype: creature to have additional attacks - subtype: creature to have additional attacks
- val: Number of attacks - val: Number of attacks
Note: used for Artillery secondary skill Note: used for Artillery secondary skill
### BONUS_DAMAGE_PERCENTAGE (since 1.2) ### BONUS_DAMAGE_PERCENTAGE
- subtype: creature to have additional damage percentage - subtype: creature to have additional damage percentage
- val: percentage to be granted - val: percentage to be granted
Note: used for Artillery secondary skill Note: used for Artillery secondary skill
### BONUS_DAMAGE_CHANCE (since 1.2) ### BONUS_DAMAGE_CHANCE
- subtype: creature to have additional damage chance (will have - subtype: creature to have additional damage chance (will have
BONUS_DAMAGE_PERCENTAGE applied before attack concluded) BONUS_DAMAGE_PERCENTAGE applied before attack concluded)
- val: chance in percent - val: chance in percent
### MAX_LEARNABLE_SPELL_LEVEL (since 1.2) ### MAX_LEARNABLE_SPELL_LEVEL
- val: maximum level of spells than hero can learn from any source. - val: maximum level of spells than hero can learn from any source.
This bonus have priority above any other LEARN\_\*SPELL_LEVEL This bonus have priority above any other LEARN\_\*SPELL_LEVEL
@@ -211,26 +196,14 @@ Note: used as global effect and as wisdom secondary skill.
### SPELL_DAMAGE ### SPELL_DAMAGE
Since 1.2: used for Sorcery secondary skill - val = value in percent
- subtype - spell school
- val = value in percent
### SPECIFIC_SPELL_DAMAGE ### SPECIFIC_SPELL_DAMAGE
- subtype = id of spell - subtype = id of spell
- val = value in percent (Luna, Ciele) - val = value in percent (Luna, Ciele)
### SPECIAL_BLESS_DAMAGE (before 1.2)
- subtype = spell (bless by default)
- val = value per level in percent
### MAXED_SPELL (before 1.2)
Spell always has expert effects but not expert range
- subtype = id
### SPECIAL_PECULIAR_ENCHANT ### SPECIAL_PECULIAR_ENCHANT
blesses and curses with id = val dependent on unit's level blesses and curses with id = val dependent on unit's level
@@ -246,18 +219,9 @@ blesses and curses with id = val dependent on unit's level
### SPELL_DURATION ### SPELL_DURATION
### AIR_SPELL_DMG_PREMY, EARTH_SPELL_DMG_PREMY, FIRE_SPELL_DMG_PREMY, WATER_SPELL_DMG_PREMY
Effect of original Orb artifacts.
- val - **percent** bonus to air / earth / fire / water spell damage.
### BLOCK_MORALE, BLOCK_LUCK (removed in 1.2)
### SPELL ### SPELL
Hero knows spell, even if this spell is banned in map options or set to Hero knows spell, even if this spell is banned in map options or set to "special".
"special".
- subtype - spell id - subtype - spell id
- val - skill level (0 - 3) - val - skill level (0 - 3)
@@ -271,10 +235,11 @@ hero knows all spells of given level
Does not grant spells banned in map options. Does not grant spells banned in map options.
### FIRE_SPELLS, AIR_SPELLS, WATER_SPELLS, EARTH_SPELLS ### SPELLS_OF_SCHOOL
All spells of this school are granted to hero, eg. by Tomes of Magic. - subtype = spell school
Does not grant spells banned in map options.
All spells of this school are granted to hero, eg. by Tomes of Magic. Does not grant spells banned in map options.
### GENERATE_RESOURCE ### GENERATE_RESOURCE
@@ -358,11 +323,7 @@ and don't move.
### DRAGON_NATURE ### DRAGON_NATURE
### KING1, KING2, KING3 (before 1.2) ### KING
Creatures take more damage from basic, advanced or expert Slayer effect.
### KING (after 1.2)
Creatures take more damage from Slayer effect than have greater or equal Creatures take more damage from Slayer effect than have greater or equal
value than KING bonus. value than KING bonus.
@@ -377,14 +338,6 @@ eg. when fighting on cursed ground
eg. when fighting on cursed ground eg. when fighting on cursed ground
### SELF_MORALE (before 1.2)
eg. minotaur
### SELF_LUCK (before 1.2)
halfling
## Combat abilities ## Combat abilities
### FLYING ### FLYING
@@ -446,7 +399,7 @@ in % (value) eg. behemots
- subtype - 0 - shield (melee) , 1 - air shield effect (ranged), -1 - - subtype - 0 - shield (melee) , 1 - air shield effect (ranged), -1 -
armorer secondary skill (all, since 1.2) armorer secondary skill (all, since 1.2)
### PERCENTAGE_DAMAGE_BOOST (since 1.2) ### PERCENTAGE_DAMAGE_BOOST
- subtype: -1 - any damage (not used), 0 - melee damage (offence), 1 - - subtype: -1 - any damage (not used), 0 - melee damage (offence), 1 -
ranged damage (archery) ranged damage (archery)
@@ -541,7 +494,7 @@ Kills extra units after hit
- val: chance in percent to trigger - val: chance in percent to trigger
- addInfo: amount/percentage to kill - addInfo: amount/percentage to kill
### LIMITED_SHOOTING_RANGE (since VCMI 1.2) ### LIMITED_SHOOTING_RANGE
Limits shooting range and/or changes long range penalty Limits shooting range and/or changes long range penalty
@@ -553,19 +506,12 @@ Limits shooting range and/or changes long range penalty
### CATAPULT ### CATAPULT
- subtype: (since 1.2) ability to use when catapulting (usually it - subtype: ability to use when catapulting (usually it contains ballistics parameters, ability for standard catapult and affected by ballistics is core:spell.catapultShot)
contains ballistics parameters, ability for standard catapult and
affected by ballistics is core:spell.catapultShot)
### CATAPULT_EXTRA_SHOTS ### CATAPULT_EXTRA_SHOTS
- subtype: (since 1.2) ability to be affected. Ability of CATAPULT - subtype: ability to be affected. Ability of CATAPULT bonus should match. Used for ballistics secondary skill with subtype of core:spell.catapultShot.
bonus should match. Used for ballistics secondary skill with subtype - val: ability level to be used with catapult. Additional shots configured in ability level, not here.
of core:spell.catapultShot.
- val: (since 1.2) ability level to be used with catapult. Additional
shots configured in ability level, not here.
- val: (before 1.2) number of additional shots, requires CATAPULT
bonus to work
### MANUAL_CONTROL ### MANUAL_CONTROL
@@ -623,7 +569,7 @@ eg. dread knight
First aid tent First aid tent
- subtype: (since 1.2) ability used for healing. - subtype: ability used for healing.
### FIRE_SHIELD ### FIRE_SHIELD
@@ -721,16 +667,13 @@ total duration of spells casted by creature
### ENCHANTED ### ENCHANTED
Stack is permanently enchanted with spell subID of skill level = val, if Stack is permanently enchanted with spell subID of skill level = val, if val > 3 then spell is mass and has level of val-3. Enchantment is refreshed every turn.
val \> 3 then spell is mass and has level of val-3. Enchantment is
refreshed every turn.
## Spell immunities ## Spell immunities
### LEVEL_SPELL_IMMUNITY ### LEVEL_SPELL_IMMUNITY
creature is immune to all spell with level below or equal to value of creature is immune to all spell with level below or equal to value of this bonus
this bonus
### MAGIC_RESISTANCE ### MAGIC_RESISTANCE
@@ -762,24 +705,11 @@ Creature is immune to all mind spells.
- subtype - spell id - subtype - spell id
- ainfo - 0 - normal, 1 - absolute - ainfo - 0 - normal, 1 - absolute
### DIRECT_DAMAGE_IMMUNITY
WoG ability. Creature is completely immune to damage spells.
### RECEPTIVE ### RECEPTIVE
WoG ability. Creature accepts all friendly spells even though it would WoG ability. Creature accepts all friendly spells even though it would
be normally immune to it. be normally immune to it.
## Deprecated creature abilities
### DAEMON_SUMMONING
pit lord - removed in VCMI 1.2 as part of major battles refactoring
- subtype - type of creatures
- val - hp per unit
# Spell effects # Spell effects
### POISON ### POISON
@@ -832,3 +762,48 @@ while in berserk
### NO_RETALIATION ### NO_RETALIATION
Eg. when blinded or paralyzed. Eg. when blinded or paralyzed.
# Undocumented
### LEVEL_COUNTER
for commander artifacts
### BLOCK_MAGIC_ABOVE
blocks casting spells of the level > value
### BLOCK_ALL_MAGIC
blocks casting spells
### SPELL_IMMUNITY
subid - spell id
### GENERAL_DAMAGE_PREMY
### ADDITIONAL_UNITS
val of units with id = subtype will be added to hero's army at the beginning of battle
### SPOILS_OF_WAR
val * 10^-6 * gained exp resources of subtype will be given to hero after battle
### BLOCK
### DISGUISED
subtype - spell level
### VISIONS
subtype - spell level
### SYNERGY_TARGET
dummy skill for alternative upgrades mod
### BLOCK_MAGIC_BELOW
blocks casting spells of the level < value
### SPECIAL_ADD_VALUE_ENCHANT
specialty spell like Aenin has, increased effect of spell, additionalInfo = value to add
### SPECIAL_FIXED_VALUE_ENCHANT
specialty spell like Melody has, constant spell effect (i.e. 3 luck), additionalInfo = value to fix.
### TOWN_MAGIC_WELL
one-time pseudo-bonus to implement Magic Well in the town

4
docs/modders/Bonus/Bonus_Updaters.md
View File

@@ -83,3 +83,7 @@ Remark: The stack level for war machines is 0.
` "parameters" : [ 20, 3, 10, 700 ],` ` "parameters" : [ 20, 3, 10, 700 ],`
` "type" : "ARMY_MOVEMENT"` ` "type" : "ARMY_MOVEMENT"`
` }` ` }`
## BONUS_OWNER_UPDATER
TODO: document me

20
docs/modders/Bonus/Bonus_Value_Types.md
View File

@@ -2,24 +2,16 @@
Total value of Bonus is calculated using the following: Total value of Bonus is calculated using the following:
- For each bonus source type we calculate new source value (for all - For each bonus source type we calculate new source value (for all bonus value types except PERCENT_TO_SOURCE and PERCENT_TO_TARGET_TYPE) using the following:
bonus value types except PERCENT_TO_SOURCE and
PERCENT_TO_TARGET_TYPE) using the following:
` newVal = (val * (100 + PERCENT_TO_SOURCE) / 100))` ` newVal = (val * (100 + PERCENT_TO_SOURCE) / 100))`
PERCENT_TO_TARGET_TYPE applies as PERCENT_TO_SOURCE to targetSourceType - PERCENT_TO_TARGET_TYPE applies as PERCENT_TO_SOURCE to targetSourceType of bonus.
of bonus.
- All bonus value types summarized and then used as subject of the - All bonus value types summarized and then used as subject of the following formula:
following formula:
` clamp(((BASE_NUMBER * (100 + PERCENT_TO_BASE) / 100) + ADDITIVE_VALUE) * (100 + PERCENT_TO_ALL) / 100), INDEPENDENT_MAX, INDEPENDENT_MIN)` ` clamp(((BASE_NUMBER * (100 + PERCENT_TO_BASE) / 100) + ADDITIVE_VALUE) * (100 + PERCENT_TO_ALL) / 100), INDEPENDENT_MAX, INDEPENDENT_MIN)`
As for 1.2, semantics of INDEPENDENT_MAX and INDEPENDENT_MIN are Semantics of INDEPENDENT_MAX and INDEPENDENT_MIN are wrapped, and first means than bonus total value will be at least INDEPENDENT_MAX, and second means than bonus value will be at most INDEPENDENT_MIN.
wrapped, and first means than bonus total value will be at least
INDEPENDENT_MAX, and second means than bonus value will be at most
INDEPENDENT_MIN.
# List of all bonus value types # List of all bonus value types
@@ -29,5 +21,5 @@ INDEPENDENT_MIN.
- PERCENT_TO_BASE - PERCENT_TO_BASE
- INDEPENDENT_MAX - INDEPENDENT_MAX
- INDEPENDENT_MIN - INDEPENDENT_MIN
- PERCENT_TO_SOURCE (since 1.2) - PERCENT_TO_SOURCE
- PERCENT_TO_TARGET_TYPE (since 1.2) - PERCENT_TO_TARGET_TYPE

5
docs/modders/Bonus_Format.md
View File

@@ -15,6 +15,7 @@ All parameters but type are optional.
"duration" : "BONUS_DURATION", //or ["BONUS_DURATION1", "BONUS_DURATION2", ...]" "duration" : "BONUS_DURATION", //or ["BONUS_DURATION1", "BONUS_DURATION2", ...]"
"turns" : 0, "turns" : 0,
"targetSourceType" : "SOURCE_TYPE",
"sourceType" : "SOURCE_TYPE", "sourceType" : "SOURCE_TYPE",
"sourceID" : 0, "sourceID" : 0,
"effectRange" : "EFFECT_RANGE", "effectRange" : "EFFECT_RANGE",
@@ -45,9 +46,7 @@ All parameters but type are optional.
## Subtype resolution ## Subtype resolution
All string identifiers of items can be used in "subtype" field. This All string identifiers of items can be used in "subtype" field. This allows cross-referencing between the mods and make config file more readable.
allows cross-referencing between the mods and make config file more
readable.
### Available prefixes ### Available prefixes

53
docs/modders/Map_Object_Format.md
View File

@@ -14,7 +14,7 @@ Full object consists from 3 parts:
generated by the game. When new object is created its starting generated by the game. When new object is created its starting
appearance will be copied from template appearance will be copied from template
### Object types ## Object types
- [Rewardable](Map_Objects/Rewardable.md) - Visitable object which grants all kinds of rewards (gold, experience, Bonuses etc...) - [Rewardable](Map_Objects/Rewardable.md) - Visitable object which grants all kinds of rewards (gold, experience, Bonuses etc...)
- [Creature Bank](Map_Objects/Creature_Bank.md) - Object that grants award on defeating guardians - [Creature Bank](Map_Objects/Creature_Bank.md) - Object that grants award on defeating guardians
@@ -29,13 +29,8 @@ Full object consists from 3 parts:
{ {
"myCoolObjectGroup": "myCoolObjectGroup":
{ {
//numeric ID, mandatory for h3/wog objects, shall be unique if not defined // Mandatory for new objects,
//used only for H3 objects, mods can not be used by mods
"index":123,
//Mandatory for new objects,
// human readable name, localized // human readable name, localized
//default for original objects from "OBJNAMES.TXT"
"name": "My cool object", "name": "My cool object",
//defines C++/script class name that handles behavior of this object //defines C++/script class name that handles behavior of this object
@@ -54,22 +49,26 @@ Full object consists from 3 parts:
## Object type format ## Object type format
``` javascript ``` javascript
{ {
"myCoolObject": "myCoolObject":
{ {
//numeric sub ID, mandatory for h3/wog objects, shall be unique if set // Additonal parameters that will be passed over to class that controls behavior of the object
//used only for H3 objects, can not be used by mods // See object-specific properties of different object types
"index":123, "propertyA" : "value",
"propertyB" : 12345
// parameters that will be passed over to class that controls behavior of the object // How valuable this object is to AI
"producedResources" : "gold", "aiValue" : 1000,
"producedValue" : 1000
// TODO: allow better selection of template for object, instead of just terrain // Sounds assigned to this object
// field describes how object template will be selected if there are multiple possiblities "sounds" : {
// exact behavior and format depends on object type // Ambient sounds that plays when current hero is near this object
"filter" : { ... }, "ambient" : [ "" ],
// Sounds that plays when hero visits this object
"visit" : [ "" ],
// Sounds that play when this object is removed from the map
"removal" : [ "" ],
},
// Data for random map generator that describes how object should be placed. // Data for random map generator that describes how object should be placed.
// If this entry is missing object will not be placed by RMG // If this entry is missing object will not be placed by RMG
@@ -104,14 +103,13 @@ Full object consists from 3 parts:
{ {
"myCoolObjectTemplate" : "myCoolObjectTemplate" :
{ {
// resource ID of animation, relative to SPRITES directory (def file or json file) // Path to def file with animation of this object
"animation":"DEFNAME.def", "animation":"DEFNAME.def",
// resource ID of animation for mapeditor, relative to SPRITES directory (def file or json file) // Optional path to def file with animation of this object to use in map editor
//0.98c+
"editorAnimation":"DEFNAME.def", "editorAnimation":"DEFNAME.def",
// directions from which hero can visit this object. // Directions from which hero can visit this object.
// "+" means that object can be visited from that direction, or "-" othervice // "+" means that object can be visited from that direction, or "-" othervice
// default not visitable // default not visitable
"visitableFrom" : [ "visitableFrom" : [
@@ -139,17 +137,12 @@ Full object consists from 3 parts:
"0000HHAT" "0000HHAT"
], ],
// optional; default or if explicitly set to null: all terrains except rock // optional; default or if explicitly set to null: all "land" terrains (e.g. not rock and not water)
// allowed terrain types to place object too. Affects also RMG. // allowed terrain types to place object to. Affects also RMG.
// Note that map editor will still allow to place object on other terrains // Note that map editor will still allow to place object on other terrains
// allowed terrain types: "dirt", "sand", "grass", "snow", "swamp", "rough", "subterra", "lava", "water", "rock" // allowed terrain types: "dirt", "sand", "grass", "snow", "swamp", "rough", "subterra", "lava", "water", "rock"
"allowedTerrains":["dirt", "sand"], "allowedTerrains":["dirt", "sand"],
// TODO, default - empty
// tags from object type are always present (???)
// List of tags that can be used to locate object in map editor
"tags":["dirt", "sand", "mine"],
//zindex, defines order in which objects on same tile will be blit. optional, default is 0 //zindex, defines order in which objects on same tile will be blit. optional, default is 0
//NOTE: legacy overlay objects has zindex = 100 //NOTE: legacy overlay objects has zindex = 100
"zIndex": 0 "zIndex": 0

9
docs/modders/Map_Objects/Creature_Bank.md
View File

@@ -1,5 +1,8 @@
< [Documentation](../../Readme.md) / [Modding](../Readme.md) / [Map Object Format](../Map_Object_Format.md) / Creature Bank < [Documentation](../../Readme.md) / [Modding](../Readme.md) / [Map Object Format](../Map_Object_Format.md) / Creature Bank
Reward types for clearing creature bank are limited to resources, creatures, artifacts and spell.
Format of rewards is same as in [Rewardable Objects](Rewardable.md)
``` javascript ``` javascript
{ {
/// List of levels of this bank. On map loading, one of them will be randomly assigned to bank. /// List of levels of this bank. On map loading, one of them will be randomly assigned to bank.
@@ -27,15 +30,9 @@
{ "amount": 4, "type": "cyclop" } { "amount": 4, "type": "cyclop" }
], ],
// How hard are guards of this level. Unused?
"combat_value": 506,
/// Description of rewards granted for clearing bank /// Description of rewards granted for clearing bank
"reward" : { "reward" : {
/// Approximate value of reward, known to AI. Unused?
"value": 10000,
/// Granted resources /// Granted resources
"resources": { "resources": {
"wood" : 4, "wood" : 4,

1
docs/modders/Map_Objects/Dwelling.md
View File

@@ -14,6 +14,7 @@
/// Boolean true/false - If set to "true", guards will be generated using H3 formula: /// Boolean true/false - If set to "true", guards will be generated using H3 formula:
/// 3 week growth of first available creatures /// 3 week growth of first available creatures
/// List of objects - custom guards, each entry represent one stack in defender army /// List of objects - custom guards, each entry represent one stack in defender army
"guards" : true,
"guards" : [ "guards" : [
{ "amount" : 12, "type" : "earthElemental" } { "amount" : 12, "type" : "earthElemental" }
] ]

3
docs/modders/Map_Objects/Market.md
View File

@@ -77,8 +77,7 @@ Game logic prohibits using modes unavailable for faction
# Offer # Offer
This field allows to configure specific items available in the market. This field allows to configure specific items available in the market. It can be used only for `resource-skill` mode
In VCMI-1.3 it can be used only for `resource-skill` mode
See [Secondary skills](Rewardable.md#secondary-skills) description for more details See [Secondary skills](Rewardable.md#secondary-skills) description for more details

128
docs/modders/Map_Objects/Rewardable.md
View File

@@ -26,7 +26,7 @@
## Base object definition ## 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. 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.
```js ```jsonc
{ {
"baseObjectName" : { "baseObjectName" : {
"name" : "Object name", "name" : "Object name",
@@ -58,7 +58,7 @@ Rewardable object is defined similarly to other objects, with key difference bei
``` ```
## Configurable object definition ## Configurable object definition
```js ```jsonc
// List of potential rewards // List of potential rewards
"rewards" : [ "rewards" : [
{ {
@@ -92,7 +92,7 @@ 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 that will be shown if this is the only available award
"message": "{Warehouse of Crystal}" "message": "{Warehouse of Crystal}"
// (VCMI 1.2) object will be disappeared after taking reward is set to true // object will be disappeared after taking reward is set to true
"removeObject": false "removeObject": false
// See "Configurable Properties" section for additiona parameters // See "Configurable Properties" section for additiona parameters
@@ -100,7 +100,7 @@ Rewardable object is defined similarly to other objects, with key difference bei
} }
], ],
// (VCMI 1.2) If true, hero can not move to visitable tile of the object and will access this object from adjacent tile (e.g. Treasure Chest) // 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, "blockedVisitable" : true,
// Message that will be shown if there are no applicable awards // Message that will be shown if there are no applicable awards
@@ -126,13 +126,7 @@ Rewardable object is defined similarly to other objects, with key difference bei
// Note that in this case object will not become "visited" and can still be revisited later // Note that in this case object will not become "visited" and can still be revisited later
"canRefuse": true, "canRefuse": true,
// object reset period. Note that period is counted from game start and not from hero visit // Controls when object state will be reset, allowing potential revisits. See Reset Parameters definition section
// reset duration of 7 will always reset object on new week & duration of 28 will reset on new month
// if field is not present or set to 0 object will never reset
// (VCMI 1.2) This property has been removed in favor of more detailed "resetParameters" property
"resetDuration" : 7,
// (VCMI 1.2) see Reset Parameters definition section
"resetParameters" : { "resetParameters" : {
} }
@@ -153,14 +147,12 @@ Rewardable object is defined similarly to other objects, with key difference bei
``` ```
## Reset Parameters definition ## Reset Parameters definition
(VCMI 1.2 only)
This property describes how object state should be reset. Objects without this field will never reset its state. 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. - 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 with `visitMode` set to `once`, `hero`, or `player`. Objects with visit mode set to `bonus` are not affected. In order to allow revisit such objects use appropriate bonus duration (e.g. `ONE_DAY` or `ONE_WEEK`) instead. - If `visitors` is set to true, game will reset list of visitors (heroes and players) on start of new period, allowing revisits of objects with `visitMode` set to `once`, `hero`, or `player`. Objects with visit mode set to `bonus` are not affected. In order to allow revisit such objects use appropriate bonus duration (e.g. `ONE_DAY` or `ONE_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" - If `rewards` is set to true, object will re-randomize its provided rewards, similar to such H3 objects as "Fountain of Fortune" or "Windmill"
```js ```jsonc
"resetParameters" : { "resetParameters" : {
"period" : 7, "period" : 7,
"visitors" : true, "visitors" : true,
@@ -172,7 +164,7 @@ This property describes how object state should be reset. Objects without this f
This property describes chance for reward to be selected. 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 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
```js ```jsonc
"appearChance": "appearChance":
{ {
// (Advanced) rewards with different dice number will get different dice number // (Advanced) rewards with different dice number will get different dice number
@@ -190,24 +182,24 @@ When object is initialized on map load, game will roll a "dice" - random number
## Configurable Properties ## Configurable Properties
Unless stated othervice, all numbers in this section can be replaced with random values, e.g. Unless stated othervice, all numbers in this section can be replaced with random values, e.g.
```js ```jsonc
"minLevel" : { "min" : 5, "max" : 10 } // select random number between 5-10, including both 5 & 10 "minLevel" : { "min" : 5, "max" : 10 } // select random number between 5-10, including both 5 & 10
"minLevel" : [ 2, 4, 6, 8, 10] // (VCMI 1.2) select random number out of provided list, with equal chance for each "minLevel" : [ 2, 4, 6, 8, 10] // (VCMI 1.2) select random number out of provided list, with equal chance for each
``` ```
In this case, actual value for minLevel will be picked randomly. In this case, actual value for minLevel will be picked randomly.
(VCMI 1.2) Keep in mind, that all randomization is performed on map load and on reset (only if `rewards` field in `resetParameter` was set). Keep in mind, that all randomization is performed on map load and on object reset (if `rewards` field in `resetParameter` was set).
### Current Day ### 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, current day of week should be equal to this value. 1 = first day of the week, 7 = last day
```js ```jsonc
"dayOfWeek" : 0 "dayOfWeek" : 0
``` ```
- (VCMI 1.2) Can only be used as limiter. To pass, number of days since game started must be at equal or greater than this value - Can only be used as limiter. To pass, number of days since game started must be at equal or greater than this value
```js ```jsonc
"daysPassed" : 8 "daysPassed" : 8
``` ```
@@ -216,15 +208,15 @@ In this case, actual value for minLevel will be picked randomly.
- Can be used as reward to grant resources to player - 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 - If negative value is used as reward, it will be used as cost and take resources from player
```js ```jsonc
"resources": { "resources": {
"crystal" : 6, "crystal" : 6,
"gold" : -1000, "gold" : -1000,
}, },
``` ```
- (VCMI 1.2) Alternative format that allows random selection of a resource type - Alternative format that allows random selection of a resource type
```js ```jsonc
"resources": [ "resources": [
{ {
"list" : [ "wood", "ore" ], "list" : [ "wood", "ore" ],
@@ -238,41 +230,41 @@ In this case, actual value for minLevel will be picked randomly.
``` ```
### Experience ### Experience
- (VCMI 1.2) Can be used as limiter - Can be used as limiter
- Can be used as reward to grant experience to hero - Can be used as reward to grant experience to hero
```js ```jsonc
"heroExperience" : 1000, "heroExperience" : 1000,
``` ```
### Hero Level ### Hero Level
- Can be used as limiter. Hero requires to have at least specified level - Can be used as limiter. Hero requires to have at least specified level
- (VCMI 1.2) 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) - 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)
```js ```jsonc
"heroLevel" : 1, "heroLevel" : 1,
``` ```
### Mana Points ### Mana Points
- (VCMI 1.2) Can be used as limiter. Hero must have at least specific mana amount - 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. - 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 negative value is used as reward, it will be used as cost and take mana from player
```js ```jsonc
"manaPoints": -10, "manaPoints": -10,
``` ```
- (VCMI 1.2) 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. - 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.
```js ```jsonc
"manaOverflowFactor" : 50, "manaOverflowFactor" : 50,
``` ```
### Mana Percentage ### Mana Percentage
- (VCMI 1.2) Can be used as limiter. Hero must have at least specific 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) - Can be used to set hero mana level to specified percentage value, not restricted to mana pool limit (Magic Well, Mana Spring)
```js ```jsonc
"manaPercentage": 200, "manaPercentage": 200,
``` ```
@@ -280,7 +272,7 @@ In this case, actual value for minLevel will be picked randomly.
- Can NOT be used as limiter - 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. - Can be used as reward, to give movement points to hero. Movement points may go above mana pool limit.
```js ```jsonc
"movePoints": 200, "movePoints": 200,
``` ```
@@ -288,7 +280,7 @@ In this case, actual value for minLevel will be picked randomly.
- Can NOT be used as limiter - 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 - Can be used to set hero movement points level to specified percentage value. Value of 0 will take away any remaining movement points
```js ```jsonc
"movePercentage": 50, "movePercentage": 50,
``` ```
@@ -296,8 +288,10 @@ In this case, actual value for minLevel will be picked randomly.
- Can be used as limiter, hero must have primary skill at least at specified level - 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 - 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 - If reward value is negative, value will be used as cost, decreasing primary skill
- (VCMI 1.3) Each primary skill can be explicitly specified or randomly selected - Each primary skill can be explicitly specified or randomly selected
```js - Possible values: `"attack", "defence", "spellpower", "knowledge"`
```jsonc
"primary": [ "primary": [
{ {
// Specific primary skill // Specific primary skill
@@ -321,14 +315,6 @@ In this case, actual value for minLevel will be picked randomly.
} }
] ]
``` ```
- Possible values: `"attack", "defence", "spellpower", "knowledge"`
- (VCMI 1.2) Deprecated format
```js
"primary": {
"attack" : 1,
"spellpower": -1
},
```
### Secondary Skills ### Secondary Skills
- Can be used as limiter, hero must have secondary skill at least at specified level - Can be used as limiter, hero must have secondary skill at least at specified level
@@ -336,8 +322,8 @@ In this case, actual value for minLevel will be picked randomly.
- If hero already has specified skill, the skills will be leveled up specified number of times - 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 - 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) - Possible values: 1 (basic), 2 (advanced), 3 (expert)
- (VCMI 1.3) Each secondary skill can be explicitly specified or randomly selected - Each secondary skill can be explicitly specified or randomly selected
```js ```jsonc
"secondary": [ "secondary": [
{ {
// Specific skill // Specific skill
@@ -361,20 +347,14 @@ In this case, actual value for minLevel will be picked randomly.
} }
] ]
``` ```
- (VCMI 1.2) deprecated format
```js
"secondary": {
"wisdom" : 1
},
```
### Bonus System ### Bonus System
- (VCMI 1.2) Can be used as reward, to grant bonus to player - Can be used as reward, to grant bonus to player
- (VCMI 1.2) if present, MORALE and LUCK bonus will add corresponding image component to UI. - if present, MORALE and LUCK bonus will add corresponding image component to UI.
- (VCMI 1.2) Note that unlike most values, parameter of bonuses can NOT be randomized - Note that unlike most values, parameter of bonuses can NOT be randomized
- (VCMI 1.X) Description can be string or number of corresponding string from `arraytxt.txt` - Description can be string or number of corresponding string from `arraytxt.txt`
```js ```jsonc
"bonuses" : [ "bonuses" : [
{ {
"type" : "MORALE", "type" : "MORALE",
@@ -388,9 +368,9 @@ In this case, actual value for minLevel will be picked randomly.
### Artifacts ### Artifacts
- Can be used as limiter, hero must have artifact either equipped or in backpack - 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 - Can be used as reward, to give new artifact to a hero
- (VCMI 1.2) Artifacts added as reward will be used for text substitution. First `%s` in text string will be replaced with name of an artifact - Artifacts added as reward will be used for text substitution. First `%s` in text string will be replaced with name of an artifact
```js ```jsonc
"artifacts": [ "artifacts": [
"ribCage" "ribCage"
], ],
@@ -400,7 +380,7 @@ In this case, actual value for minLevel will be picked randomly.
- For artifact class possible values are "TREASURE", "MINOR", "MAJOR", "RELIC" - For artifact class possible values are "TREASURE", "MINOR", "MAJOR", "RELIC"
- Artifact value range can be specified with min value and max value - Artifact value range can be specified with min value and max value
```js ```jsonc
"artifacts": [ "artifacts": [
{ {
"class" : "TREASURE", "class" : "TREASURE",
@@ -411,20 +391,20 @@ In this case, actual value for minLevel will be picked randomly.
``` ```
### Spells ### Spells
- (VCMI 1.2) Can be used as limiter - Can be used as limiter
- Can be used as reward, to give new spell to a hero - Can be used as reward, to give new spell to a hero
- (VCMI 1.2) Spells added as reward will be used for text substitution. First `%s` in text string will be replaced with spell name - Spells added as reward will be used for text substitution. First `%s` in text string will be replaced with spell name
```js ```jsonc
"spells": [ "spells": [
"magicArrow" "magicArrow"
], ],
``` ```
- Alternative format, random spell selection - Alternative format, random spell selection
- (VCMI 1.X) Spell can be selected from specifically selected school - Spell can be selected from specifically selected school
```js ```jsonc
"spells": [ "spells": [
{ {
"level" : 1, "level" : 1,
@@ -438,7 +418,7 @@ In this case, actual value for minLevel will be picked randomly.
- Can be used as reward, to give new creatures to a hero - Can be used as reward, to give new creatures to a hero
- If hero does not have enough free slots, game will show selection dialog to pick troops to keep - If hero does not have enough free slots, game will show selection dialog to pick troops to keep
- It is possible to specify probabilty to receive upgraded creature - It is possible to specify probabilty to receive upgraded creature
```js ```jsonc
"creatures" : [ "creatures" : [
{ {
"creature" : "archer", "creature" : "archer",
@@ -449,22 +429,22 @@ In this case, actual value for minLevel will be picked randomly.
``` ```
### Creatures Change ### Creatures Change
- (VCMI 1.2) Can NOT be used as limiter - Can NOT be used as limiter
- (VCMI 1.2) 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 - 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
- (VCMI 1.2) This parameter will not change creatures given by `creatures` parameter on the same visit - This parameter will not change creatures given by `creatures` parameter on the same visit
```js ```jsonc
"changeCreatures" : { "changeCreatures" : {
"cavalier" : "champion" "cavalier" : "champion"
} }
``` ```
### Spell cast ### Spell cast
- (VCMI 1.3) Can NOT be used as limiter - Can NOT be used as limiter
- (VCMI 1.3) 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 - 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) - School level possible values: 1 (basic), 2 (advanced), 3 (expert)
```js ```jsonc
"spellCast" : { "spellCast" : {
"spell" : "townPortal", "spell" : "townPortal",
"schoolLevel": 3 "schoolLevel": 3

236
docs/modders/Mod_File_Format.md
View File

@@ -3,57 +3,76 @@
## Fields with description of mod ## Fields with description of mod
``` javascript ``` javascript
{ {
// Name of your mod. While it does not have hard length limit // Name of your mod. While it does not have hard length limit
// it should not be longer than ~30 symbols to fit into allowed space // it should not be longer than ~30 symbols to fit into allowed space
"name" : "My test mod", "name" : "My test mod",
// More lengthy description of mod. No hard limit. This text will be visible in launcher. // More lengthy description of mod. No hard limit. This text will be visible in launcher.
// This field can use small subset of HTML, see link at the bottom of this page. // This field can use small subset of HTML, see link at the bottom of this page.
"description" : "My test mod that add a lot of useless stuff into the game", "description" : "My test mod that add a lot of useless stuff into the game",
// Author of mod. Can be nickname, real name or name of team // Author of mod. Can be nickname, real name or name of team
"author" : "Anonymous", "author" : "Anonymous",
// Full name of license used by mod. Should be set only if you're author of mod // Full name of license used by mod. Should be set only if you're author of mod
// or received permission to use such license from original author // or received permission to use such license from original author
"licenseName" : "Creative Commons Attribution-ShareAlike", "licenseName" : "Creative Commons Attribution-ShareAlike",
// URL which user can use to see license terms and text // URL which user can use to see license terms and text
"licenseURL" : "https://creativecommons.org/licenses/by-sa/4.0/", "licenseURL" : "https://creativecommons.org/licenses/by-sa/4.0/",
// Home page of mod or link to forum thread to contact the author // Home page of mod or link to forum thread to contact the author
"contact" : "http://example.com", "contact" : "http://example.com",
// Type of mod, list of all possible values: // Current mod version, up to 3 numbers, dot-separated. Format: A.B.C
// "Translation", "Town", "Test", "Templates", "Spells", "Music", "Sounds", "Skills", "Other", "Objects", "version" : "1.2.3"
// "Mechanics", "Interface", "Heroes", "Graphical", "Expansion", "Creatures", "Artifacts", "AI"
"modType" : "Graphical",
// List of mods that are required to run this one // Type of mod, list of all possible values:
"depends" : // "Translation", "Town", "Test", "Templates", "Spells", "Music", "Sounds", "Skills", "Other", "Objects",
[ // "Mechanics", "Interface", "Heroes", "Graphical", "Expansion", "Creatures", "Artifacts", "AI"
"baseMod" "modType" : "Graphical",
],
// List of mods that can't be enabled in the same time as this one // Base language of the mod, before applying localizations. By default vcmi assumes English
"conflicts" : // This property is mostly needed for translation mods only
[ "language" : "english"
"badMod"
],
//List of changes/new features in each version // List of mods that are required to run this one
"changelog" : "depends" :
{ [
"1.0" : [ "initial release" ], "baseMod"
"1.0.1" : [ "change 1", "change 2" ], ],
"1.1" : [ "change 3", "change 4" ]
},
// If set to true, mod will not be enabled automatically on install // List of mods that can't be enabled in the same time as this one
"keepDisabled" : false "conflicts" :
[
"badMod"
],
// Supported versions of vcmi engine
"compatibility" : {
"min" : "1.2.0"
"max" : "1.3.0"
}
//List of changes/new features in each version
"changelog" :
{
"1.0" : [ "initial release" ],
"1.0.1" : [ "change 1", "change 2" ],
"1.1" : [ "change 3", "change 4" ]
},
// If set to true, mod will not be enabled automatically on install
"keepDisabled" : false
// List of game settings changed by a mod. See <VCMI Install>/config/gameConfig.json for reference
"settings" : {
"combat" : {
"goodLuckDice" : [] // disable luck
}
}
} }
``` ```
@@ -64,71 +83,98 @@ These are fields that are present only in local mod.json file
``` javascript ``` javascript
{ {
// Following section describes configuration files with content added by mod // Following section describes configuration files with content added by mod
// It can be split into several files in any way you want but recommended organization is // It can be split into several files in any way you want but recommended organization is
// to keep one file per object (creature/hero/etc) and, if applicable, add separate file // to keep one file per object (creature/hero/etc) and, if applicable, add separate file
// with translatable strings for each type of content // with translatable strings for each type of content
// See "additional links" at the bottom of page for descriptions of each of these formats
// list of factions/towns configuration files // list of factions/towns configuration files
"factions" : "factions" :
[ [
"config/myMod/faction.json" "config/myMod/faction.json"
] ]
// List of hero classes configuration files // List of hero classes configuration files
"heroClasses" : "heroClasses" :
[ [
"config/myMod/heroClasses.json" "config/myMod/heroClasses.json"
], ],
// List of heroes configuration files // List of heroes configuration files
"heroes" : "heroes" :
[ [
"config/myMod/heroes.json" "config/myMod/heroes.json"
], ],
// list of creature configuration files // List of configuration files for skills
"creatures" : skills
[
"config/myMod/creatures.json"
],
// List of artifacts configuration files // list of creature configuration files
"artifacts" : "creatures" :
[ [
"config/myMod/artifacts.json" "config/myMod/creatures.json"
], ],
// List of objects defined in this mod // List of artifacts configuration files
"objects" : "artifacts" :
[ [
"config/myMod/objects.json" "config/myMod/artifacts.json"
], ],
// List of spells defined in this mod // List of objects defined in this mod
"spells" : "objects" :
[ [
"config/myMod/spells.json" "config/myMod/objects.json"
], ],
// List of RMG templates defined in this mod // List of spells defined in this mod
"templates" : "spells" :
[ [
"config/myMod/templates.json" "config/myMod/spells.json"
], ],
// Optional, description on how files are organized in your mod // List of configuration files for terrains
// In most cases you do not need to use this field "terrains" :
// Needed mostly to port any existing mods to vcmi (e.g. WoG distributed with Era) [
// Example below is default value, which is "Content" directory that acts as H3 root directory "config/myMod/terrains.json"
"filesystem": ],
{
"": // List of configuration files for roads
[ "roads" :
{"type" : "dir", "path" : "/Content"} [
] "config/myMod/roads.json"
} ],
// List of configuration files for rivers
"rivers" :
[
"config/myMod/rivers.json"
],
// List of configuration files for battlefields
"battlefields" :
[
"config/myMod/battlefields.json"
],
// List of configuration files for obstacles
"obstacles" :
[
"config/myMod/obstacles.json"
],
// List of RMG templates defined in this mod
"templates" :
[
"config/myMod/templates.json"
],
// Optional, primaly used by translation mods
// Defines strings that are translated by mod into base language specified in "language" field
"translations" :
[
"config/myMod/englishStrings.json
]
} }
``` ```