games/vcmi
1
0
Fork 0
mirror of https://github.com/vcmi/vcmi.git synced 2025-03-29 21:56:54 +02:00
Code Issues Releases Activity

Merge pull request #2811 from IvanSavenko/update_modding_docs

Browse Source 
Update modding documentation
This commit is contained in:
Ivan Savenko 2023-09-13 22:07:29 +03:00 committed by GitHub
commit 4d9cca36c6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
34 changed files with 1002 additions and 960 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
config/factions/neutral.json
View File

@ -5,6 +5,7 @@
"index" : 9,
"nativeTerrain" : "none",
"alignment" : "neutral",
"boat" : "boatFortress",
"creatureBackground" :
{
"120px" : "TPCASNEU",

2
config/schemas/artifact.json
View File

@ -123,7 +123,7 @@
},
"onlyOnWaterMap" : {
"type" : "boolean",
"description" : "It true, artifact won't spawn on a map without water"
"description" : "If set to true, artifact won't spawn on a map without water"
}
}
}

8
config/schemas/bonus.json
View File

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

16
config/schemas/creature.json
View File

@ -23,7 +23,7 @@
},
"disabled" : {
"type" : "boolean",
"description" : "Object is competely disabled and may not be even loaded in-game"
"description" : "Internal. Object is competely disabled and may not be even loaded in-game"
},
"name" : {
"type" : "object",
@ -122,26 +122,22 @@
"$ref" : "bonus.json"
}
},
"abilityText" : {
"type" : "string",
"description" : "Text version of creature abilities. Used only with original creature window"
},
"graphics" : {
"type" : "object",
"additionalProperties" : false,
"description" : "Describes how this creature looks like during battles",
"description" : "Describes how this creature looks like",
"required" : [
"animation", "animationTime", "timeBetweenFidgets"
],
"properties" : {
"animation" : {
"type" : "string",
"description" : ".def file with animation of this creature in battles",
"description" : "File with animation of this creature in battles",
"format" : "defFile"
},
"map" : {
"type" : "string",
"description" : ".def file with animation of this creature on adventure map",
"description" : "File with animation of this creature on adventure map",
"format" : "defFile"
},
"mapMask" : {
@ -247,7 +243,7 @@
},
"attackClimaxFrame" : {
"type" : "number",
"description" : "Frame from attack animation during which creature deals damage"
"description" : "Frame at which shooter shoots his projectile (e.g. releases arrow)"
}
}
},
@ -264,7 +260,7 @@
"sound" : {
"type" : "object",
"additionalProperties" : false,
"description" : "Various sound files associated with this creature",
"description" : "Sound files associated with this creature",
"properties" : {
"attack" : { "type" : "string", "format" : "soundFile" },
"defend" : { "type" : "string", "format" : "soundFile" },

14
config/schemas/faction.json
View File

@ -30,20 +30,20 @@
"$schema" : "http://json-schema.org/draft-04/schema",
"title" : "VCMI faction format",
"description" : "Json format for defining new faction (aka towns) in VCMI",
"required" : [ "name", "alignment", "nativeTerrain", "creatureBackground" ],
"required" : [ "name", "boat", "alignment", "nativeTerrain", "creatureBackground" ],
"dependencies" : {
"town" : [ "puzzleMap", "boat" ]
"town" : [ "puzzleMap" ]
},
"additionalProperties" : false,
"properties" : {
"name" : {
"type" : "string",
"description" : "Translatable name of town"
"description" : "Localizable faction name, e.g. Rampart"
},
"alignment" : {
"type" : "string",
"enum" : [ "good", "neutral", "evil" ],
"description" : "Town alignment, good, neutral or evil"
"description" : "Faction alignment, good, neutral or evil"
},
"nativeTerrain" : {
"type" : "string",
@ -51,12 +51,12 @@
},
"boat" : {
"type" : "string",
"description" : "Identifier of boat type that is produced by shipyard in town, if any"
"description" : "Identifier of boat type that is produced by shipyard and used by heroes in water taverns or prisons"
},
"preferUndergroundPlacement" : {
"type" : "boolean",
"description" : "Random map generator places player/cpu-owned towns underground if true is specified and on the ground otherwise. Parameter is unused for maps without underground. False by default."
"description" : "Random map generator places player/cpu-owned towns underground if true is specified and on the ground otherwise. Parameter is unused for maps without underground."
},
"creatureBackground" : {
"type" : "object",
@ -173,7 +173,7 @@
},
"buildingsIcons" : {
"type" : "string",
"description" : "Path to .def file with building icons",
"description" : "Path to building icons for town hall",
"format" : "animationFile"
},
"mapObject" : {

12
config/schemas/hero.json
View File

@ -16,19 +16,19 @@
"properties" : {
"special" : {
"type" : "boolean",
"description" : "Marks this object as special and not available by default"
"description" : "If set to true hero will be unavailable on start and won't appear in taverns (campaign heroes)"
},
"class" : {
"type" : "string",
"description" : "Hero class, e.g. knight or battleMage"
"description" : "Identifier of class this hero belongs to. Such as knight or battleMage"
},
"female" : {
"type" : "boolean",
"description" : "This hero is female (changeable via editor)"
"description" : "Set to true if the hero is female by default (can be changed in map editor)"
},
"battleImage" : {
"type" : "string",
"description" : "Custom def used on battle",
"description" : "Custom animation to be used on battle, overrides hero class property",
"format" : "defFile"
},
"images" : {
@ -174,11 +174,11 @@
},
"onlyOnWaterMap" : {
"type" : "boolean",
"description" : "It true, hero won't show up on a map with water"
"description" : "If set to true, hero won't show up on a map with water"
},
"onlyOnMapWithoutWater" : {
"type" : "boolean",
"description" : "It true, hero will show up only if the map contains no water"
"description" : "If set to true, hero will show up only if the map contains no water"
}
}
}

2
config/schemas/heroClass.json
View File

@ -16,7 +16,7 @@
},
"faction" : {
"type" : "string",
"description" : "Faction this hero class belongs to"
"description" : "Identifier of faction this class belongs to"
},
"affinity" : {
"type" : "string",

4
config/schemas/objectTemplate.json
View File

@ -14,11 +14,11 @@
"editorAnimation" : {
"type" : "string",
"description" : "Optional path to def file with animation of this object to use in map editor",
"format" : "defFile"
"format" : "defFile"
},
"visitableFrom" : {
"type" : "array",
"description" : "Directions from which this object is visible",
"description" : "Directions from which hero can visit this object",
"minItems" : 3,
"maxItems" : 3,
"items" : {

32
config/schemas/skill.json
View File

@ -15,7 +15,7 @@
},
"images" : {
"type" : "object",
"description" : "skill icons of varying size",
"description" : "Skill icons of varying size",
"properties" : {
"small" : {
"type" : "string",
@ -47,11 +47,11 @@
"properties" : {
"name" : {
"type" : "string",
"description" : "localizable skill name"
"description" : "Mandatory, localizable skill name"
},
"index" : {
"type" : "number",
"description" : "numeric id of skill, required for existing skills"
"description" : "Internal, numeric id of skill, required for existing skills"
},
"obligatoryMajor" : {
"type" : "boolean",
@ -63,22 +63,16 @@
},
"gainChance" : {
"description" : "Chance for the skill to be offered on level-up (heroClass may override)",
"anyOf" : [
{
"type" : "number"
},
{
"type" : "object",
"required" : ["might", "magic"],
"properties" : {
"might" : {
"type" : "number",
"description" : "Chance for hero classes with might affinity"
},
"magic" : {
"type" : "number",
"description" : "Chance for hero classes with magic affinity"
}
"type" : "object",
"required" : ["might", "magic"],
"properties" : {
"might" : {
"type" : "number",
"description" : "Chance for hero classes with might affinity"
},
"magic" : {
"type" : "number",
"description" : "Chance for hero classes with magic affinity"
}
}
]

12
config/schemas/townBuilding.json
View File

@ -27,11 +27,11 @@
"description" : "Numeric identifier of this building"
},
"name" : {
"description" : "Name of this building",
"description" : "Localizable name of this building",
"type" : "string"
},
"description" : {
"description" : "Full decsription of this building",
"description" : "Localizable decsription of this building",
"type" : "string"
},
"type" : {
@ -53,13 +53,13 @@
"description" : "List of town buildings that must be built before this one"
},
"upgrades" : {
"description" : "If this building is upgrade, identifier of base building",
"description" : "Optional, indicates that this building upgrades another base building",
"type" : "string"
},
"cost" : {
"type" : "object",
"additionalProperties" : false,
"description" : "Cost to build this building",
"description" : "Resources needed to build building",
"properties" : {
"gold" : { "type" : "number"},
"wood" : { "type" : "number"},
@ -69,11 +69,11 @@
"crystal" : { "type" : "number"},
"gems" : { "type" : "number"}
}
},
},
"produce" : {
"type" : "object",
"additionalProperties" : false,
"description" : "Resources this building produce each day",
"description" : "Resources produced each day by this building",
"properties" : {
"gold" : { "type" : "number"},
"wood" : { "type" : "number"},

2
config/schemas/townStructure.json
View File

@ -21,7 +21,7 @@
},
"area" : {
"type" : "string",
"description" : "Area that indicate when building is selected. Must be 8-bit image",
"description" : "Area that indicate when building is selected.",
"format" : "imageFile"
},
"border" : {

161
docs/modders/Animation_Format.md
View File

@ -1,13 +1,10 @@
< [Documentation](../Readme.md) / [Modding](Readme.md) / Animation Format
VCMI allows overriding HoMM3 .def files with .json replacement. Compared
to .def this format allows:
VCMI allows overriding HoMM3 .def files with .json replacement. Compared to .def this format allows:
- Overriding individual frames from json file (e.g. icons)
- Modern graphics formats (targa, png - all formats supported by VCMI
image loader)
- Does not requires any special tools - all you need is text editor
and images.
- Modern graphics formats (targa, png - all formats supported by VCMI image loader)
- Does not requires any special tools - all you need is text editor and images.
# Format description
@ -59,150 +56,62 @@ to .def this format allows:
# Creature animation groups
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**
- \[0\] Movement: Used for creature movement
- \[1\] Mouse over: Used for random idle movements and when mouse is
moved on the creature
- \[2\] Idle: Basic animation that plays continuously when stack is
not acting
- \[3\] Hitted: Animation that plays whenever stack is hit
- \[4\] Defence: Alternative animation that plays when stack is
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
- [0] Movement: Used for creature movement
- [1] Mouse over: Used for random idle movements and when mouse is moved on the creature
- [2] Idle: Basic animation that plays continuously when stack is not acting
- [3] Hitted: Animation that plays whenever stack is hit
- [4] Defence: Alternative animation that plays when stack is 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**
- \[7\] Turn left: Animation for rotating stack, only contains first
part of animation, with stack turning towards viewer
- \[8\] Turn right: Second part of animation for rotating stack
- \[9\] (unused in vcmi, present in H3 files)
- \[10\] (unused in vcmi, present in H3 files)
- [7] Turn left: Animation for rotating stack, only contains first part of animation, with stack turning towards viewer
- [8] Turn right: Second part of animation for rotating stack
- [9] (unused in vcmi, present in H3 files)
- [10] (unused in vcmi, present in H3 files)
**Melee attack animations**
- \[11\] Attack (up): Attacking animation, stack facing upwards
- \[12\] Attack (front): Attacking animation, stack facing front
- \[13\] Attack (down): Attacking animation, stack facing downwards
- [11] Attack (up): Attacking animation, stack facing upwards
- [12] Attack (front): Attacking animation, stack facing front
- [13] Attack (down): Attacking animation, stack facing downwards
**Ranged attack animations**
- \[14\] Shooting (up): Ranged attack animation, stack facing upwards
- \[15\] Shooting (front): Ranged attack animation, stack facing front
- \[16\] Shooting (down): Ranged attack animation, stack facing
downwards
- [14] Shooting (up): Ranged attack animation, stack facing upwards
- [15] Shooting (front): Ranged attack animation, stack facing front
- [16] Shooting (down): Ranged attack animation, stack facing downwards
**Special animations**
- \[17\] Special (up): Special animation, used if dedicated cast or
group attack animations were not found
- \[18\] Special (front): Special animation, used if dedicated cast or
group attack animations were not found
- \[19\] Special (down): Special animation, used if dedicated cast or
group attack animations were not found
- [17] Special (up): Special animation, used if dedicated cast or group attack animations were not found
- [18] Special (front): Special animation, used if dedicated cast or 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**
- \[20\] Movement start: Animation that plays before movement
animation starts.
- \[21\] Movement end: Animation that plays after movement animation
ends.
- [20] Movement start: Animation that plays before movement animation starts.
- [21] Movement end: Animation that plays after movement animation ends.
**Additional VCMI animations**
- \[22\] \[VCMI 1.0\] Dead: Animation that plays when creature is
dead. If not present, will consist from last frame from "Death"
group
- \[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
- [22] Dead: Animation that plays when creature is dead. If not present, will consist from last frame from "Death" group
- [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
- [24] Resurrection: Animation that plays when creature is resurrected. If not present, will consist from reversed version of "Death" animation
**Spellcasting animations**
- \[30\] \[VCMI 1.2\] Cast (up): Used when creature casts spell facing
upwards
- \[31\] \[VCMI 1.2\] Cast (front): Used when creature casts spell
facing front
- \[32\] \[VCMI 1.2\] Cast (down): Used when creature casts spell
facing downwards
- [30] Cast (up): Used when creature casts spell facing upwards
- [31] Cast (front): Used when creature casts spell facing front
- [32] Cast (down): Used when creature casts spell facing downwards
**Group attack animations**
- \[40\] \[VCMI 1.2\] Group Attack (up): Used when creature attacks
multiple target, with primary target facing up (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
]
}
```
- [40] Group Attack (up): Used when creature attacks multiple target, with primary target facing up (Dragon Breath attack, or creatures like Hydra)
- [41] Group Attack (front): Used when creature attacks multiple target, with primary target facing front (Dragon Breath 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)

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
Bonus may have any of these durations. They acts in disjunction.
## List of all bonus duration types
- PERMANENT
- ONE_BATTLE //at the end of battle
- ONE_DAY //at the end of day
- ONE_WEEK //at the end of week (bonus lasts till the end of week,
thats NOT 7 days
- N_TURNS //used during battles, after battle bonus is always removed
- ONE_BATTLE: at the end of battle
- ONE_DAY: at the end of day
- ONE_WEEK: at the end of week (bonus lasts till the end of week, NOT 7 days)
- N_TURNS: used during battles, after battle bonus is always removed
- N_DAYS
- UNTIL_BEING_ATTACKED //removed after any damage-inflicting attack
- UNTIL_ATTACK //removed after attack and counterattacks are performed
- STACK_GETS_TURN //removed when stack gets its turn - used for
defensive stance
- UNTIL_BEING_ATTACKED: removed after any damage-inflicting attack
- UNTIL_ATTACK: removed after attack and counterattacks are performed
- STACK_GETS_TURN: removed when stack gets its turn - used for defensive stance
- COMMANDER_KILLED

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

@ -4,11 +4,14 @@
The limiters take no parameters:
- SHOOTER_ONLY
- DRAGON_NATURE
- IS_UNDEAD
- CREATURE_NATIVE_TERRAIN
- OPPOSITE_SIDE
- SHOOTER_ONLY
- DRAGON_NATURE
- IS_UNDEAD
- CREATURE_NATIVE_TERRAIN
- CREATURE_FACTION
- SAME_FACTION
- CREATURES_ONLY
- OPPOSITE_SIDE
Example:
@ -56,7 +59,15 @@ Parameters:
- 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:
@ -84,6 +95,12 @@ Example:
} ]
```
### UNIT_ON_HEXES
Parameters:
- List of affected battlefield hexes
## Aggregate Limiters
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
- BATTLE_WIDE
Affects both sides during battle
- VISITED_TOWN_AND_VISITOR
Used with Legion artifacts (town visited by hero)
- PLAYER_PROPAGATOR
Bonus will affect all objects owned by player. Used by Statue of Legion.
- 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.
- BATTLE_WIDE: Affects both sides during battle
- VISITED_TOWN_AND_VISITOR: Used with Legion artifacts (town visited by hero)
- PLAYER_PROPAGATOR: Bonus will affect all objects owned by player. Used by Statue of Legion.
- HERO: Bonus will be transferred to hero (for example from stacks in his army).
- TEAM_PROPAGATOR: Bonus will affect all objects owned by player and his allies.
- GLOBAL_EFFECT: This effect will influence all creatures, heroes and towns on the map.

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

@ -2,21 +2,18 @@
# List of all Bonus range types
- NO_LIMIT
- ONLY_DISTANCE_FIGHT
- ONLY_MELEE_FIGHT
- ONLY_ENEMY_ARMY (before 1.2)
- NO_LIMIT
- ONLY_DISTANCE_FIGHT
- ONLY_MELEE_FIGHT
TODO: in 0.91 ONLY_MELEE_FIGHT / ONLY_DISTANCE_FIGHT range types work
ONLY with creature attack, should be extended to all battle abilities.
TODO: ONLY_MELEE_FIGHT / ONLY_DISTANCE_FIGHT range types work ONLY with creature attack, should be extended to all battle abilities.
(1.2+) For replacing ONLY_ENEMY_ARMY alias, you should use the following
parameters of bonus:
For replacing ONLY_ENEMY_ARMY alias, you should use the following parameters of bonus:
"propagator": "BATTLE_WIDE",
"propagationUpdater" : "BONUS_OWNER_UPDATER",
"limiters" : [ "OPPOSITE_SIDE" ]
```
"propagator": "BATTLE_WIDE",
"propagationUpdater" : "BONUS_OWNER_UPDATER",
"limiters" : [ "OPPOSITE_SIDE" ]
```
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.
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.

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

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

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

File diff suppressed because it is too large Load Diff

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 ],`
` "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:
- 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:
- 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:
` newVal = (val * (100 + PERCENT_TO_SOURCE) / 100))`
PERCENT_TO_TARGET_TYPE applies as PERCENT_TO_SOURCE to targetSourceType
of bonus.
- PERCENT_TO_TARGET_TYPE applies as PERCENT_TO_SOURCE to targetSourceType of bonus.
- All bonus value types summarized and then used as subject of the
following formula:
- All bonus value types summarized and then used as subject of the following formula:
` 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
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.
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.
# List of all bonus value types
@ -29,5 +21,5 @@ INDEPENDENT_MIN.
- PERCENT_TO_BASE
- INDEPENDENT_MAX
- INDEPENDENT_MIN
- PERCENT_TO_SOURCE (since 1.2)
- PERCENT_TO_TARGET_TYPE (since 1.2)
- PERCENT_TO_SOURCE
- 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", ...]"
"turns" : 0,
"targetSourceType" : "SOURCE_TYPE",
"sourceType" : "SOURCE_TYPE",
"sourceID" : 0,
"effectRange" : "EFFECT_RANGE",
@ -45,9 +46,7 @@ All parameters but type are optional.
## Subtype resolution
All string identifiers of items can be used in "subtype" field. This
allows cross-referencing between the mods and make config file more
readable.
All string identifiers of items can be used in "subtype" field. This allows cross-referencing between the mods and make config file more readable.
### Available prefixes

50
docs/modders/Entities_Format/Artifact_Format.md
View File

@ -2,10 +2,6 @@
Artifact bonuses use [Bonus Format](../Bonus_Format.md)
TODO:
- Artifacts growing with Commander level
## Required data
In order to make functional artifact you also need:
@ -16,50 +12,72 @@ In order to make functional artifact you also need:
## Format
``` javascript
``` jsonc
{
//what kind of bearer can use this artifact
// Type of this artifact - creature, hero or commander
"type": ["HERO", "CREATURE", "COMMANDER"]
//TREASURE, MINOR, MAJOR, RELIC, SPECIAL
// TREASURE, MINOR, MAJOR, RELIC, SPECIAL
"class": "TREASURE",
//SHOULDERS, NECK, RIGHT_HAND, LEFT_HAND, TORSO, RIGHT_RING, LEFT_RING, FEET, MISC1, MISC2, MISC3, MISC4,
//MACH1, MACH2, MACH3, MACH4, SPELLBOOK, MISC5
//also possible MISC, RING
// Slot(s) to which this artifact can be put, if applicable
// SHOULDERS, NECK, RIGHT_HAND, LEFT_HAND, TORSO, RIGHT_RING, LEFT_RING, FEET, MISC1, MISC2, MISC3, MISC4,
// MACH1, MACH2, MACH3, MACH4, SPELLBOOK, MISC5
// MISC, RING
"slot": "HEAD",
"slot": [ "LEFT_HAND", "RIGHT_HAND ],
//based on ARTRAITS.txt
// Cost of this artifact, in gold
"value": 12000,
"text":
{
// Name of the artifact
"name": "Big Sword",
// Long description of this artifact
"description": "Big sword gived +10 attack to hero",
// Text that visible on picking this artifact on map
"event": "On your travel, you stumble upon big sword. You dust it off and stick in your backpack"
},
"graphics":
{
// Base image for this artifact, used for example in hero screen
"image": "BigSword.png",
// Large image, used for drag-and-drop and popup messages
"large": "BigSword_large.png",
//def file for adventure map
"map": "BigSword.def"
},
// Bonuses provided by this artifact using bonus system
"bonuses":
{
Bonus_1,
Bonus_2
},
//optional, for combined artifacts only
// Optional, list of components for combinational artifacts
"components":
[
"artifact1",
"artifact2",
"artifact3"
],
//if set with artifact works like war machine
// Creature id to use on battle field. If set, this artifact is war machine
"warMachine" : "some.creature"
// If set to true, artifact won't spawn on a map without water
"onlyOnWaterMap" : false,
// TODO: document
"growing" : {
"bonusesPerLevel" : {},
"thresholdBonuses" : {},
}
}
```
```

77
docs/modders/Entities_Format/Creature_Format.md
View File

@ -25,7 +25,7 @@ In order to make functional creature you also need:
// camelCase unique creature identifier
"creatureName" :
{
// translatable names
// Translatable names for this creature
"name" :
{
"singular" : "Creature",
@ -33,12 +33,13 @@ In order to make functional creature you also need:
},
"level" : 0,
// if set to true creature will not appear in-game randomly (e.g. as neutral creature)
// Marks this object as special and not available by default
"special" : true,
// config name of faction. Examples: castle, rampart
// Faction this creature belongs to. Examples: castle, rampart
"faction" : "",
// cost to recruit, zero values can be omitted.
// Cost to recruit this creature, zero values can be omitted.
"cost" :
{
"wood" : 0,
@ -52,75 +53,80 @@ In order to make functional creature you also need:
// "value" of creature, used to determine for example army strength
"fightValue" : 0,
// "ai value" - how valuable this creature should be for AI
// Describes how valuable this creature is to AI. Usually similar to fightValue
"aiValue" : 0,
// normal growth in town or external dwellings
// Basic growth of this creature in town or in external dwellings
"growth" : 0,
// growth bonus from horde building
// TODO: reconsider need of this field after configurable buildings support
// Bonus growth of this creature from built horde
"hordeGrowth" : 0,
// Creature stats in battle
"attack" : 0,
"defense" : 0,
"hitPoints" : 0,
"shots" : 0,
"speed" : 0,
"damage" :
{
"min" : 0,
"max" : 0
},
// spellpoints this creature has, how many times creature may cast its spells
// Number of shots this creature has, required only for ranged units
"shots" : 0,
// Spell points this creature has (usually equal to number of casts)
"spellPoints" : 0,
// initial size of creature army on adventure map
// Initial size of random stacks on adventure map
"advMapAmount" :
{
"min" : 0,
"max" : 0
},
// Creature to which this creature can be upgraded
// Note that only one upgrade can be available from UI
// List of creatures to which this one can be upgraded
"upgrades" :
[
"anotherCreature"
],
// Creature is 2-tiles in size on the battlefield
// If set, creature will be two tiles wide on battlefield
"doubleWide" : false,
// All creature abilities, using bonus format
// Creature abilities described using Bonus system
"abilities" :
[
"someName1" : Bonus Format,
"someName2" : Bonus Format
],
// creature may receive "week of" events
"hasDoubleWeek": true,
"graphics" :
{
// name of file with creature battle animation
// File with animation of this creature in battles
"animation" : "",
// adventure map animation def
// File with animation of this creature on adventure map
"map" : "",
// path to small icon for tooltips & hero exchange window
// Optional. Object mask that describes on which tiles object is visible/blocked/activatable
"mapMask" : [ "VV", "VA" ],
// Small icon for this creature, used for example in exchange screen
"iconSmall" : "",
// path to large icon, used on town screen and in hero screen
// Large icon for this creature, used for example in town screen
"iconLarge" : "",
// animation parameters
// how often creature should play idle animation
"timeBetweenFidgets" : 1.00,
// unused H3 property
"troopCountLocationOffset" : 0,
"animationTime" :
{
// movement animation time.
// movement animation time factor
"walk" : 1.00,
// idle animation time. For H3 creatures this value is always 10
@ -128,19 +134,15 @@ In order to make functional creature you also need:
// ranged attack animation time. Applicable to shooting and casting animation
// NOTE: does NOT affects melee attacks
// This is H3 behaviour, for proper synchronization of attack/defense animations
// This is H3 behaviour, likely for proper synchronization of attack/defense animations
"attack" : 1.00,
// How far flying creature should move during one "round" of movement animation
// This is multiplier to base value (200 pixels)
"flight" : 1.00
},
"missile" :
{
// name of file for missile
"animation" : "",
// (VCMI 1.1 or later only) indicates that creature uses ray animation for ranged attacks instead of missile image (e.g. Evil Eye)
// indicates that creature uses ray animation for ranged attacks instead of missile image (e.g. Evil Eye)
"ray" :
[
{ // definition of first (top-most) line in the ray
@ -153,7 +155,7 @@ In order to make functional creature you also need:
// Frame at which shooter shoots his projectile (e.g. releases arrow)
"attackClimaxFrame" : 0,
// offsets between position of shooter and position where projectile should appear
// Position where projectile image appears during shooting in specific direction
"offset" :
{
"upperX" : 0,
@ -190,6 +192,19 @@ In order to make functional creature you also need:
// Creature start/end movement or teleports
"startMoving" : "",
"endMoving" : ""
}
},
// Stack experience, using bonus system
"stackExperience" : [
{
// Bonus description
"bonus" : { BONUS_FORMAT },
// Per-level value of bonus. Must have 10 elements
"values" : [
0, 0, 1, 1, 2, 2, 3, 3, 4, 4
]
},
...
]
}
```

139
docs/modders/Entities_Format/Faction_Format.md
View File

@ -12,16 +12,12 @@ In order to make functional town you also need:
- Mage guild window view (1 image)
- Town hall background (1 image)
<!-- -->
- Set of town icons, consists from all possible combinations of: (8
images total)
- small and big icons
- village and fort icons
- built and normal icons
<!-- -->
- Set for castle siege screen, consists from:
- Background (1 image)
- Destructible towers (3 parts, 3 images each)
@ -49,18 +45,18 @@ Each town requires a set of buildings (Around 30-45 buildings)
## Faction node (root entry for town configuration)
``` javascript
// Unique faction identifier. Should be unique.
"myTown" :
```jsonc
// Unique faction identifier.
"myFaction" :
{
// Main part of town description, see below
// Optional but it should be present for playable faction
"town" : { ... },
// Native terrain for this town. See config/terrains.json for identifiers
// Native terrain for creatures. Creatures fighting on native terrain receive several bonuses
"nativeTerrain" : "grass",
// Localizable town name, e.g. "Rampart"
// Localizable faction name, e.g. "Rampart"
"name" : "",
// Faction alignment. Can be good, neutral (default) or evil.
@ -72,7 +68,13 @@ Each town requires a set of buildings (Around 30-45 buildings)
// Paths to background images
"120px" : "",
"130px" : ""
}
},
// Identifier of boat type that is produced by shipyard and used by heroes in water taverns or prisons
"boat" : "boatFortress",
// Random map generator places player/cpu-owned towns underground if true is specified and on the ground otherwise. Parameter is unused for maps without underground.
"preferUndergroundPlacement" : false
// Town puzzle map
"puzzleMap" :
@ -98,17 +100,9 @@ Each town requires a set of buildings (Around 30-45 buildings)
## Town node
``` javascript
```jsonc
{
// DEPRECATED, see "mapObject" field below | Path to images of object on adventure map
"adventureMap" :
{
"village": "", // village without built fort
"castle" : "", // town with built fort
"capitol": "" // town with capitol (usually have some additional flags)
},
// field that describes behavior of map object part of town. Town-specific part of object format
// Field that describes behavior of map object part of town. Town-specific part of object format
"mapObject" :
{
// Optional, controls what template will be used to display this object.
@ -174,21 +168,20 @@ Each town requires a set of buildings (Around 30-45 buildings)
// Small scenery for window in mage guild screen
"guildWindow": "",
// Background image for window in mage guild screen - since 0.95b
// Background image for window in mage guild screen
"guildBackground" : "",
// Video for tavern window - since 0.95b
// Video for tavern window
"tavernVideo" : "",
// Building icons for town hall
// Path to building icons for town hall
"buildingsIcons": "HALLCSTL.DEF",
// Background image for town hall window
"hallBackground": "",
// List of buildings available in each slot of town hall window
// As in most cases there is no hard limit on number of columns, rows
// or items in any of them, but size of gui is limited to 5 rows and 4 columns
// Note that size of gui is limited to 5 rows and 4 columns
"hallSlots":
[
[ [ "buildingID1" ], [ "buildingID2", "buildingID3" ] ],
@ -232,19 +225,16 @@ Each town requires a set of buildings (Around 30-45 buildings)
// Chance of specific spell to appear in mages guild of this town
// If spell is missing or set to 0 it will not appear unless set as "always present" in editor
// Spells from unavailable levels are not required to be in this list
// TODO: Mirrored version of field "guildSpells" from spell format
"guildSpells" :
{
"magicArrow" : 30,
"bless" : 10
},
// TODO: Entries below should be replaced with autodetection
// Which tiers in this town have creature hordes. Set to -1 to disable horde(s)
"horde" : [ 2, -1 ],
// Resource given by starting bonus, if not set silo will produce wood + ore
// Resource given by starting bonus. If not set silo will produce wood + ore
"primaryResource" : "gems",
// maximum level of mage guild
@ -252,12 +242,15 @@ Each town requires a set of buildings (Around 30-45 buildings)
// war machine produced in town
"warMachine" : "ballista"
// Identifier of spell that will create effects for town moat during siege
"moatAbility" : "castleMoat"
}
```
## Siege node
``` javascript
```jsonc
// Describes town siege screen
// Comments in the end of each graphic position indicate specify required suffix for image
// Note: one not included image is battlefield background with suffix "BACK"
@ -265,13 +258,13 @@ Each town requires a set of buildings (Around 30-45 buildings)
// shooter creature name
"shooter" : "archer",
// (VCMI 1.1 or later) Large icon of towers, for use in battle queue
// Large icon of towers, for use in battle queue
"towerIconLarge" : "",
// (VCMI 1.1 or later) Small icon of towers, for use in battle queue
// (Small icon of towers, for use in battle queue
"towerIconSmall" : "",
// prefix for all siege images. Final name will be composed as <prefix><suffix>
// Prefix for all siege images. Final name will be composed as <prefix><suffix>
"imagePrefix" : "SGCS",
// Descriptions for towers. Each tower consist from 3 parts:
@ -302,7 +295,7 @@ Each town requires a set of buildings (Around 30-45 buildings)
"creature" : { "x": 0, "y": 0}
},
},
//Two parts of gate: gate itself and arch above it
// Two parts of gate: gate itself and arch above it
"gate" :
{
"gate" : { "x": 0, "y": 0}, // "DRW1" ... "DRW3" and "DRWC" (rope)
@ -317,8 +310,13 @@ Each town requires a set of buildings (Around 30-45 buildings)
"bottomMid" : { "x": 0, "y": 0}, // "WA31" ... "WA33"
"bottom" : { "x": 0, "y": 0} // "WA11" ... "WA13"
},
// Two pieces for moat: moat itself and shore
"moat" : { "x": 0, "y": 0}, // moat: "MOAT", shore: "MLIP"
// Two pieces for moat: moat itself and moat bank
"moat" :
{
"bank" : { "x" : 0, "y" : 0 }, // "MOAT"
"moat" : { "x" : 0, "y" : 0 } // "MLIP"
},
// Static non-destructible walls. All of them have only one piece
"static" :
@ -337,28 +335,56 @@ Each town requires a set of buildings (Around 30-45 buildings)
## Building node
``` javascript
```jsonc
{
// Numeric identifier of this building
"id" : 0,
// Localizable name of this building
"name" : "",
// Localizable decsription of this building
"description" : "",
"upgrades" : "baseBuilding", // optional, which building can be upgraded by this one
"requires" : [ "allOf", [ "mageGuild1" ], [ "tavern" ] ], // building requirements, H3-style. See below for full format.
"cost" : { ... }, //resources needed to buy building
"produce" : { ... }, //resources produced each day by building - since 0.95b
// Optional, indicates that this building upgrades another base building
"upgrades" : "baseBuilding",
// List of town buildings that must be built before this one. See below for full format
"requires" : [ "allOf", [ "mageGuild1" ], [ "tavern" ] ],
// Resources needed to build building
"cost" : { ... },
// TODO: Document me: Subtype for some special buildings
"type" : "",
// TODO: Document me: Height for lookout towers and some grails
"height" : "average"
// Resources produced each day by this building
"produce" : { ... },
//determine how this building can be built. Possible values are:
// normal - default value. Fulfill requirements, use resources, spend one day
// auto - building appears when all requirements are built
// special - building can not be built manually
// grail - building reqires grail to be built
"mode" : "auto"
"mode" : "auto",
// Buildings which bonuses should be overridden with bonuses of the current building
"overrides" : [ "anotherBuilding ]
// Bonuses, provided by this special building on build using bonus system
"bonuses" : BONUS_FORMAT
// Bonuses, provided by this special building on hero visit and applied to the visiting hero
"onVisitBonuses" : BONUS_FORMAT
}
```
Building requirements can be described using logical expressions:
``` javascript
```jsonc
"requires" :
[
"allOf", // Normal H3 "build all" mode
@ -378,13 +404,30 @@ Building requirements can be described using logical expressions:
## Structure node
``` javascript
```jsonc
{
"animation" : "", // def file with animation
// Main animation file for this building
"animation" : "",
// Horizontal position on town screen
"x" : 0,
// Vertical position on town screen
"y" : 0,
"z" : 0, // used for blit order. Higher value places structure close to screen
"border" : "", // selection highlight
"area" : "" // used to detect building selection
// used for blit order. Higher value places structure close to screen and drawn on top of buildings with lower values
"z" : 0,
// Path to image with golden border around building, displayed when building is selected
"border" : "",
// Path to image with area that indicate when building is selected
"area" : "",
//TODO: describe me
"builds": "",
// If upgrade, this building will replace parent animation but will not alter its behaviour
"hidden" : false
}
```

8
docs/modders/Entities_Format/Hero_Class_Format.md
View File

@ -61,8 +61,7 @@ In order to make functional hero class you also need:
"knowledge" : 2
},
// Chance to get specific primary skill on level-up
// This set specifies chances for levels 2-9
// Chance to get specific primary skill on level-up, applicable for levels less than 10
"lowLevelChance" :
{
"attack" : 15,
@ -71,8 +70,7 @@ In order to make functional hero class you also need:
"knowledge" : 25
},
// Chance to get specific primary skill on level-up
// This set specifies chances for levels starting from 10
// Chance to get specific primary skill on level-up, applicable for levels starting from 10
"highLevelChance" :
{
"attack" : 25,
@ -82,7 +80,7 @@ In order to make functional hero class you also need:
},
// Chance to get specific secondary skill on level-up
// Skills not listed here will be considered as unavailable, including universities
// All missing skills are considered to be banned, including universities
"secondarySkills" :
{
"pathfinding" : 3.

19
docs/modders/Entities_Format/Hero_Type_Format.md
View File

@ -12,10 +12,10 @@ In order to make functional hero you also need:
``` javascript
"myHeroName" :
{
// Identifier of class. Usually camelCase version of human-readable name
// Identifier of class this hero belongs to. Such as knight or battleMage
"class" : "wizard",
// List of starting spells, if available. Will also grant spellbook
// List of starting spells, if available. This entry (even empty) will also grant spellbook
"spellbook" :
[
"magicArrow"
@ -26,6 +26,12 @@ In order to make functional hero you also need:
// If set to true hero will be unavailable on start and won't appear in taverns (campaign heroes)
"special" : true,
// If set to true, hero won't show up on a map with water
"onlyOnWaterMap" : false,
// If set to true, hero will show up only if the map contains no water
"onlyOnMapWithoutWater" : false,
// All translatable texts related to hero
"texts" :
@ -61,11 +67,10 @@ In order to make functional hero you also need:
// Small 48x32px portrait
"small" : "myMod/myHero/small.png"
// Class-independent animation in battle
"small" : "myMod/myHero/battle.def"
},
// Custom animation to be used on battle, overrides hero class property
"battleImage" : "heroInBattle.def"
// Initial hero army when recruited in tavern
// Must have 1-3 elements
@ -95,7 +100,7 @@ In order to make functional hero you also need:
}
],
// List of skills received by hero
// List of skills initially known by hero
// Not limited by size - you can add as many skills as you wish
"skills" :
[

149
docs/modders/Entities_Format/Secondary_Skill_Format.md
View File

@ -2,21 +2,39 @@
## Main format
``` javascript
```jsonc
{
"skillName":
{
//numeric id of skill required only for original skills, prohibited for new skills
"index": 0,
//Mandatory
"name": "Localizable name",
//optional base format, will be merged with basic/advanced/expert
"base": {Skill level base format},
//configuration for different skill levels
"basic": {Skill level format},
"advanced": {Skill level format},
"expert": {Skill level format}
}
"skillName":
{
//Mandatory, localizable skill name
"name": "Localizable name",
// Optional base format, will be merged with basic/advanced/expert
"base": {Skill level base format},
// Configuration for different skill levels
"basic": {Skill level format},
"advanced": {Skill level format},
"expert": {Skill level format},
// Chance for the skill to be offered on level-up (heroClass may override)
"gainChance" : {
// Chance for hero classes with might affinity
"might" : 4,
// Chance for hero classes with magic affinity
"magic" : 6,
// Chance for specific classes
"knight" : 2,
"cleric" : 8,
...
},
// This skill is major obligatory (like H3 Wisdom) and is guaranteed to be offered once per specific number of levels
"obligatoryMajor" : false,
// This skill is minor obligatory (like H3 Magic school) and is guaranteed to be offered once per specific number of levels
"obligatoryMinor" : false,
}
}
```
@ -28,19 +46,30 @@ level fields become optional if they equal "base" configuration.
## Skill level format
``` javascript
```jsonc
{
//Optional, localizable description
//Use {xxx} for formatting
"description": "",
//Bonuses provided by skill at given level
//If different levels provide same bonus with different val, only the highest applies
"effects":
{
"firstEffect": {bonus format},
"secondEffect": {bonus format}
//...
}
// Localizable description
// Use {xxx} for formatting
"description": "",
// Bonuses provided by skill at given level
// If different levels provide same bonus with different val, only the highest applies
"effects":
{
"firstEffect": {bonus format},
"secondEffect": {bonus format}
//...
},
// Skill icons of varying size
"images" : {
// 32x32 skill icon
"small" : "",
// 44x44 skill icon
"medium" : "",
// 82x93 skill icon
"large" : "",
}
}
```
@ -49,40 +78,40 @@ level fields become optional if they equal "base" configuration.
The following modifies the tactics skill to grant an additional speed
boost at advanced and expert levels.
``` javascript
```jsonc
"core:tactics" : {
"base" : {
"effects" : {
"main" : {
"subtype" : "skill.tactics",
"type" : "SECONDARY_SKILL_PREMY",
"valueType" : "BASE_NUMBER"
},
"xtra" : {
"type" : "STACKS_SPEED",
"valueType" : "BASE_NUMBER"
}
}
},
"basic" : {
"effects" : {
"main" : { "val" : 3 },
"xtra" : { "val" : 0 }
}
},
"advanced" : {
"description" : "{Advanced Tactics}\n\nAllows you to rearrange troups within 5 hex rows, and increases their speed by 1.",
"effects" : {
"main" : { "val" : 5 },
"xtra" : { "val" : 1 }
}
},
"expert" : {
"description" : "{Expert Tactics}\n\nAllows you to rearrange troups within 7 hex rows, and increases their speed by 2.",
"effects" : {
"main" : { "val" : 7 },
"xtra" : { "val" : 2 }
}
}
"base" : {
"effects" : {
"main" : {
"subtype" : "skill.tactics",
"type" : "SECONDARY_SKILL_PREMY",
"valueType" : "BASE_NUMBER"
},
"xtra" : {
"type" : "STACKS_SPEED",
"valueType" : "BASE_NUMBER"
}
}
},
"basic" : {
"effects" : {
"main" : { "val" : 3 },
"xtra" : { "val" : 0 }
}
},
"advanced" : {
"description" : "{Advanced Tactics}\n\nAllows you to rearrange troups within 5 hex rows, and increases their speed by 1.",
"effects" : {
"main" : { "val" : 5 },
"xtra" : { "val" : 1 }
}
},
"expert" : {
"description" : "{Expert Tactics}\n\nAllows you to rearrange troups within 7 hex rows, and increases their speed by 2.",
"effects" : {
"main" : { "val" : 7 },
"xtra" : { "val" : 2 }
}
}
}
```

55
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
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...)
- [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":
{
//numeric ID, mandatory for h3/wog objects, shall be unique if not defined
//used only for H3 objects, mods can not be used by mods
"index":123,
//Mandatory for new objects,
// Mandatory for new objects,
// human readable name, localized
//default for original objects from "OBJNAMES.TXT"
"name": "My cool 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
``` javascript
{
"myCoolObject":
{
//numeric sub ID, mandatory for h3/wog objects, shall be unique if set
//used only for H3 objects, can not be used by mods
"index":123,
// Additonal parameters that will be passed over to class that controls behavior of the object
// See object-specific properties of different object types
"propertyA" : "value",
"propertyB" : 12345
// parameters that will be passed over to class that controls behavior of the object
"producedResources" : "gold",
"producedValue" : 1000
// TODO: allow better selection of template for object, instead of just terrain
// field describes how object template will be selected if there are multiple possiblities
// exact behavior and format depends on object type
"filter" : { ... },
// How valuable this object is to AI
"aiValue" : 1000,
// Sounds assigned to this object
"sounds" : {
// Ambient sounds that plays when current hero is near this object
"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.
// If this entry is missing object will not be placed by RMG
@ -104,14 +103,13 @@ Full object consists from 3 parts:
{
"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",
// resource ID of animation for mapeditor, relative to SPRITES directory (def file or json file)
//0.98c+
// Optional path to def file with animation of this object to use in map editor
"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
// default not visitable
"visitableFrom" : [
@ -139,17 +137,12 @@ Full object consists from 3 parts:
"0000HHAT"
],
// optional; default or if explicitly set to null: all terrains except rock
// allowed terrain types to place object too. Affects also RMG.
// optional; default or if explicitly set to null: all "land" terrains (e.g. not rock and not water)
// allowed terrain types to place object to. Affects also RMG.
// 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"],
// 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
//NOTE: legacy overlay objects has zindex = 100
"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
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
{
/// 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" }
],
// How hard are guards of this level. Unused?
"combat_value": 506,
/// Description of rewards granted for clearing bank
"reward" : {
/// Approximate value of reward, known to AI. Unused?
"value": 10000,
/// Granted resources
"resources": {
"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:
/// 3 week growth of first available creatures
/// List of objects - custom guards, each entry represent one stack in defender army
"guards" : true,
"guards" : [
{ "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
This field allows to configure specific items available in the market.
In VCMI-1.3 it can be used only for `resource-skill` mode
This field allows to configure specific items available in the market. It can be used only for `resource-skill` mode
See [Secondary skills](Rewardable.md#secondary-skills) description for more details

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

@ -26,7 +26,7 @@
## 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.
```js
```jsonc
{
"baseObjectName" : {
"name" : "Object name",
@ -58,7 +58,7 @@ Rewardable object is defined similarly to other objects, with key difference bei
```
## Configurable object definition
```js
```jsonc
// List of potential 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": "{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
// 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,
// 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
"canRefuse": true,
// object reset period. Note that period is counted from game start and not from hero visit
// 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
// Controls when object state will be reset, allowing potential revisits. See Reset Parameters definition section
"resetParameters" : {
}
@ -147,20 +141,19 @@ Rewardable object is defined similarly to other objects, with key difference bei
//determines way to select granted rewards if multiple options are available
// "selectFirst", - first reward which passes "limiter" will be granted to player
// "selectPlayer", - player will be allowed to choose between rewards (e.g. treasure chest)
"selectMode" : "selectFirst", "selectPlayer"
// "selectRandom", - granted reward will be picked randomly when hero visits object
"selectMode" : "selectFirst"
}
```
## 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.
- 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 `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" : {
"period" : 7,
"visitors" : true,
@ -172,7 +165,7 @@ This property describes how object state should be reset. Objects without this f
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
```js
```jsonc
"appearChance":
{
// (Advanced) rewards with different dice number will get different dice number
@ -190,24 +183,24 @@ When object is initialized on map load, game will roll a "dice" - random number
## Configurable Properties
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" : [ 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.
(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
- 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
```
- (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
```
@ -216,15 +209,15 @@ In this case, actual value for minLevel will be picked randomly.
- 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
```js
```jsonc
"resources": {
"crystal" : 6,
"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": [
{
"list" : [ "wood", "ore" ],
@ -238,41 +231,41 @@ In this case, actual value for minLevel will be picked randomly.
```
### Experience
- (VCMI 1.2) Can be used as limiter
- Can be used as limiter
- Can be used as reward to grant experience to hero
```js
```jsonc
"heroExperience" : 1000,
```
### Hero 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,
```
### 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.
- If negative value is used as reward, it will be used as cost and take mana from player
```js
```jsonc
"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,
```
### 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)
```js
```jsonc
"manaPercentage": 200,
```
@ -280,7 +273,7 @@ In this case, actual value for minLevel will be picked randomly.
- 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.
```js
```jsonc
"movePoints": 200,
```
@ -288,7 +281,7 @@ In this case, actual value for minLevel will be picked randomly.
- 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
```js
```jsonc
"movePercentage": 50,
```
@ -296,8 +289,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 reward, to increase hero primary skills by selected value
- 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
```js
- Each primary skill can be explicitly specified or randomly selected
- Possible values: `"attack", "defence", "spellpower", "knowledge"`
```jsonc
"primary": [
{
// Specific primary skill
@ -321,14 +316,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
- Can be used as limiter, hero must have secondary skill at least at specified level
@ -336,8 +323,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 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)
- (VCMI 1.3) Each secondary skill can be explicitly specified or randomly selected
```js
- Each secondary skill can be explicitly specified or randomly selected
```jsonc
"secondary": [
{
// Specific skill
@ -361,20 +348,14 @@ In this case, actual value for minLevel will be picked randomly.
}
]
```
- (VCMI 1.2) deprecated format
```js
"secondary": {
"wisdom" : 1
},
```
### Bonus System
- (VCMI 1.2) 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.
- (VCMI 1.2) 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`
- 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`
```js
```jsonc
"bonuses" : [
{
"type" : "MORALE",
@ -388,9 +369,9 @@ In this case, actual value for minLevel will be picked randomly.
### 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
- (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": [
"ribCage"
],
@ -400,7 +381,7 @@ In this case, actual value for minLevel will be picked randomly.
- For artifact class possible values are "TREASURE", "MINOR", "MAJOR", "RELIC"
- Artifact value range can be specified with min value and max value
```js
```jsonc
"artifacts": [
{
"class" : "TREASURE",
@ -409,22 +390,22 @@ In this case, actual value for minLevel will be picked randomly.
}
],
```
### Spells
- (VCMI 1.2) Can be used as limiter
- 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
```js
### 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
```jsonc
"spells": [
"magicArrow"
],
```
- 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": [
{
"level" : 1,
@ -432,13 +413,13 @@ In this case, actual value for minLevel will be picked randomly.
}
],
```
### Creatures
- Can be used as limiter
- 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
- It is possible to specify probabilty to receive upgraded creature
```js
```jsonc
"creatures" : [
{
"creature" : "archer",
@ -449,22 +430,22 @@ In this case, actual value for minLevel will be picked randomly.
```
### Creatures Change
- (VCMI 1.2) 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
- (VCMI 1.2) This parameter will not change creatures given by `creatures` parameter on the same visit
- 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
```js
```jsonc
"changeCreatures" : {
"cavalier" : "champion"
}
```
### Spell cast
- (VCMI 1.3) 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
- 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)
```js
```jsonc
"spellCast" : {
"spell" : "townPortal",
"schoolLevel": 3

240
docs/modders/Mod_File_Format.md
View File

@ -3,57 +3,76 @@
## Fields with description of mod
``` javascript
{
// 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
"name" : "My test mod",
// 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
"name" : "My test mod",
// 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.
"description" : "My test mod that add a lot of useless stuff into the game",
// 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.
"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" : "Anonymous",
// Author of mod. Can be nickname, real name or name of team
"author" : "Anonymous",
// 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
"licenseName" : "Creative Commons Attribution-ShareAlike",
// 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
"licenseName" : "Creative Commons Attribution-ShareAlike",
// URL which user can use to see license terms and text
"licenseURL" : "https://creativecommons.org/licenses/by-sa/4.0/",
// URL which user can use to see license terms and text
"licenseURL" : "https://creativecommons.org/licenses/by-sa/4.0/",
// Home page of mod or link to forum thread to contact the author
"contact" : "http://example.com",
// Home page of mod or link to forum thread to contact the author
"contact" : "http://example.com",
// Current mod version, up to 3 numbers, dot-separated. Format: A.B.C
"version" : "1.2.3"
// Type of mod, list of all possible values:
// "Translation", "Town", "Test", "Templates", "Spells", "Music", "Sounds", "Skills", "Other", "Objects",
// "Mechanics", "Interface", "Heroes", "Graphical", "Expansion", "Creatures", "Artifacts", "AI"
"modType" : "Graphical",
// Type of mod, list of all possible values:
// "Translation", "Town", "Test", "Templates", "Spells", "Music", "Sounds", "Skills", "Other", "Objects",
// "Mechanics", "Interface", "Heroes", "Graphical", "Expansion", "Creatures", "Artifacts", "AI"
"modType" : "Graphical",
// Base language of the mod, before applying localizations. By default vcmi assumes English
// This property is mostly needed for translation mods only
"language" : "english"
// List of mods that are required to run this one
"depends" :
[
"baseMod"
],
// List of mods that are required to run this one
"depends" :
[
"baseMod"
],
// List of mods that can't be enabled in the same time as this one
"conflicts" :
[
"badMod"
],
// List of mods that can't be enabled in the same time as this one
"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" ]
},
//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
// 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
{
// 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
// to keep one file per object (creature/hero/etc) and, if applicable, add separate file
// with translatable strings for each type of content
// See "additional links" at the bottom of page for descriptions of each of these formats
// 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
// to keep one file per object (creature/hero/etc) and, if applicable, add separate file
// with translatable strings for each type of content
// list of factions/towns configuration files
"factions" :
[
"config/myMod/faction.json"
]
// list of factions/towns configuration files
"factions" :
[
"config/myMod/faction.json"
]
// List of hero classes configuration files
"heroClasses" :
[
"config/myMod/heroClasses.json"
],
// List of hero classes configuration files
"heroClasses" :
[
"config/myMod/heroClasses.json"
],
// List of heroes configuration files
"heroes" :
[
"config/myMod/heroes.json"
],
// List of heroes configuration files
"heroes" :
[
"config/myMod/heroes.json"
],
// List of configuration files for skills
skills
// list of creature configuration files
"creatures" :
[
"config/myMod/creatures.json"
],
// list of creature configuration files
"creatures" :
[
"config/myMod/creatures.json"
],
// List of artifacts configuration files
"artifacts" :
[
"config/myMod/artifacts.json"
],
// List of artifacts configuration files
"artifacts" :
[
"config/myMod/artifacts.json"
],
// List of objects defined in this mod
"objects" :
[
"config/myMod/objects.json"
],
// List of objects defined in this mod
"objects" :
[
"config/myMod/objects.json"
],
// List of spells defined in this mod
"spells" :
[
"config/myMod/spells.json"
],
// List of spells defined in this mod
"spells" :
[
"config/myMod/spells.json"
],
// List of configuration files for terrains
"terrains" :
[
"config/myMod/terrains.json"
],
// List of configuration files for roads
"roads" :
[
"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, description on how files are organized in your mod
// In most cases you do not need to use this field
// 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
"filesystem":
{
"":
[
{"type" : "dir", "path" : "/Content"}
]
}
// 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
]
}
```

3
lib/CCreatureHandler.cpp
View File

@ -566,7 +566,8 @@ std::vector<JsonNode> CCreatureHandler::loadLegacyData()
data["advMapAmount"]["min"].Float() = parser.readNumber();
data["advMapAmount"]["max"].Float() = parser.readNumber();
data["abilityText"].String() = parser.readString();
// unused - ability text, not used since we no longer have original creature window
parser.readString();
loadBonuses(data, parser.readString()); //Attributes
h3Data.push_back(data);