games/vcmi
1
0
Fork 0
mirror of https://github.com/vcmi/vcmi.git synced 2025-11-27 22:49:25 +02:00
Code Issues Releases Activity

First part of documentation import

Browse Source
This commit is contained in:
Ivan Savenko
2023-08-12 12:39:44 +03:00
parent 211bcb6e82
commit 6ac0dabcab
18 changed files with 2924 additions and 209 deletions
Download Patch File Download Diff File Expand all files Collapse all files

218
docs/modders/Animation Format.md Normal file
View File

@@ -0,0 +1,218 @@
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.
# Format description
``` javascript
{
// Base path of all images in animation. Optional.
// Can be used to avoid using long path to images
"basepath" : "path/to/images/directory/",
// List of sequiences / groups in animation
// This will replace original group with specified list of files
// even if original animation is longer
"sequences" :
[
{
// Index of group, zero-based
"group" : 1,
// List of files in this group
"frames" :
[
"frame1.png",
"frame2.png"
...
]
},
...
],
// Allow overriding individual frames in file
"images" :
[
{
// Group of this image. Optional, default = 0
"group" : 0,
// Imdex of the image in group
"frame" : 0,
// Filename for this frame
"file" : "filename.png"
}.
...
]
}
```
# Creature animation groups
Animation for creatures consist from multiple groups, with each group
representing specific one 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
**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)
**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
**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
**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
**Additional H3 animations**
- \[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
**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
**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
## Void format
- vcmi client
- map editor
Json header may be omitted. In such case a single frame will be loaded
from same resource ID. Resource id should have no extension, image must
be in SPRITES/ virtual directory.
## 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
- vcmi client
- map editor
``` 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
]
}
```

52
docs/modders/Artifact Format.md Normal file
View File

@@ -0,0 +1,52 @@
See thread <http://forum.vcmi.eu/viewtopic.php?t=558> for discussion
Artifact bonuses use [Bonus Format](Bonus_Format "wikilink").
TODO:
- Artifacts growing with Commander level
## Required data
In order to make functional artifact you also need:
- Icon for hero inventory (1 image)
- Icon for popup windows (1 image, optional)
- Animation for adventure map (1 animation)
## Format
``` javascript
{
"type": ["HERO", "CREATURE", "COMMANDER"] //what kind of bearer can use this artifact
"class": "TREASURE", //TREASURE, MINOR, MAJOR, RELIC, SPECIAL
"slot": "HEAD", //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
"value": 12000, //based on ARTRAITS.txt
"text":
{
"name": "Big Sword",
"description": "Big sword gived +10 attack to hero",
"event": "On your travel, you stumble upon big sword. You dust it off and stick in your backpack"
},
"graphics":
{
"image": "BigSword.png",
"large": "BigSword_large.png",
"map": "BigSword.def"//def file for adventure map
},
"bonuses":
{
Bonus_1,
Bonus_2
},
"components": //optional, for combined artifacts only
[
"artifact1",
"artifact2",
"artifact3"
],
"warMachine" : "some.creature" //if set with artifact works like war machine
}
```

96
docs/modders/Bonus Format.md Normal file
View File

@@ -0,0 +1,96 @@
Enumerative parameters are described in HeroBonus.h file.
### Short format
``` javascript
{
["BONUS_TYPE", val, subtype, addInfo]
}
```
### Full format
All parameters but type are optional.
``` javascript
{
"type": "BONUS_TYPE",
"subtype": 0,
"val" : 0,
"valueType": "VALUE_TYPE",
"addInfo" : 0, // or [1, 2, ...]
"duration" : "BONUS_DURATION", //or ["BONUS_DURATION1", "BONUS_DURATION2", ...]"
"turns" : 0,
"sourceType" : "SOURCE_TYPE",
"sourceID" : 0,
"effectRange" : "EFFECT_RANGE",
"limiters" : [
"PREDEFINED_LIMITER", optional_parameters (...), //whhich one is preferred?
{"type" : LIMITER_TYPE, "parameters" : [1,2,3]}
],
"propagator" : ["PROPAGATOR_TYPE", optional_parameters (...)],
"updater" : {Bonus Updater},
"propagationUpdater" : {Bonus Updater, but works during propagation},
"description" : "",
"stacking" : ""
}
```
## 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.
### Available prefixes
- creature.
- artifact.
- skill.
``` javascript
"pathfinding", "archery", "logistics", "scouting", "diplomacy",
"navigation", "leadership", "wisdom", "mysticism", "luck",
"ballistics", "eagleEye", "necromancy", "estates", "fireMagic",
"airMagic", "waterMagic", "earthMagic", "scholar", "tactics",
"artillery", "learning", "offence", "armorer", "intelligence",
"sorcery", "resistance", "firstAid"
```
- resource.
Possible values:
``` javascript
"wood", "mercury", "ore", "sulfur", "crystal", "gems", "gold", "mithril"
```
- hero.
- faction.
- spell.
- primSkill
``` javascript
"attack", "defence", "spellpower", "knowledge"
```
- terrain (since 0.99)
``` javascript
"dirt", "sand", "grass", "snow", "swamp", "rough", "subterra", "lava", "water", "rock"
```
### Example
``` javascript
"bonus" :
{
"type" : "HATE",
"subtype" : "creature.enchanter",
"val" : 50
}
```
This bonus makes creature do 50% more damage to Enchanters.

198
docs/modders/Creature Format.md Normal file
View File

@@ -0,0 +1,198 @@
Schema in git:
[config/schemas/creature.json](https://github.com/vcmi/vcmi/blob/develop/config/schemas/creature.json)
See thread <http://forum.vcmi.eu/viewtopic.php?t=533> for discussion.
## Required data
In order to make functional creature you also need:
### Animation
- Battle animation (1 def file)
- Set of rendered projectiles (1 def files, shooters only)
- Adventure map animation (1 def file)
### Images
- Small portrait for hero exchange window (1 image)
- Large portrait for hero window (1 image)
### Sounds
- Set of sounds (up to 8 sounds)
## Format
``` javascript
// camelCase unique creature identifier
"creatureName" :
{
// translatable names
"name" :
{
"singular" : "Creature",
"plural" : "Creatures"
},
"level" : 0,
// if set to true creature will not appear in-game randomly (e.g. as neutral creature)
"special" : true,
// config name of faction. Examples: castle, rampart
"faction" : "",
// cost to recruit, zero values can be omitted.
"cost" :
{
"wood" : 0,
"mercury" : 0,
"ore" : 0,
"sulfur" : 0,
"crystal" : 0,
"gems" : 0,
"gold" : 0
},
// "value" of creature, used to determine for example army strength
"fightValue" : 0,
// "ai value" - how valuable this creature should be for AI
"aiValue" : 0,
// normal growth in town or external dwellings
"growth" : 0,
// growth bonus from horde building
// TODO: reconsider need of this field after configurable buildings support
"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
"spellPoints" : 0,
// initial size of creature army 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
"upgrades" :
[
"anotherCreature"
],
// Creature is 2-tiles in size on the battlefield
"doubleWide" : false,
// All creature abilities, using bonus format
"abilities" :
[
"someName1" : Bonus Format,
"someName2" : Bonus Format
],
"hasDoubleWeek": true,
"graphics" :
{
// name of file with creature battle animation
"animation" : "",
// adventure map animation def
"map" : "",
// path to small icon for tooltips & hero exchange window
"iconSmall" : "",
// path to large icon, used on town screen and in hero screen
"iconLarge" : "",
// animation parameters
// how often creature should play idle animation
"timeBetweenFidgets" : 1.00,
// unused H3 property
"troopCountLocationOffset" : 0,
"animationTime" :
{
// movement animation time.
"walk" : 1.00,
// idle animation time. For H3 creatures this value is always 10
"idle" : 10.00,
// 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
"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)
"ray" :
[
{ // definition of first (top-most) line in the ray
"start" : [ 160, 192, 0, 255 ], // color (RGBA components) of ray at starting point
"end" : [ 160, 192, 0, 64 ] // color (RGBA components) of ray at finishing point
},
{}, // definition of second from top line in the ray, identical format
... // definitions of remaining lines, till desired width of the ray
],
// Frame at which shooter shoots his projectile (e.g. releases arrow)
"attackClimaxFrame" : 0,
// offsets between position of shooter and position where projectile should appear
"offset" :
{
"upperX" : 0,
"upperY" : 0,
"middleX" : 0,
"middleY" : 0,
"lowerX" : 0,
"lowerY" : 0
},
// angles from which frames in .def file were rendered, -90...90 range
// Example below will work for file that contains following frames:
// 1) facing top, 2) facing top-right, 3)facing right,
// 4) facing bottom-right 5) facing bottom.
"frameAngles" : [ -90, -45, 0, 45, 90]
}
},
// names of sound files
"sound" :
{
// Creature attack enemy in melee (counter-)attack
"attack": "",
// Creature in "defend mode" is attacked
"defend": "",
// Creature killed
"killed": "",
// Plays in loop during creature movement
"move": "",
// Shooters only, creature shoots
"shoot" : "",
// Creature not in "defend mode" is under attack
"wince": "",
// Creature start/end movement or teleports
"startMoving" : "",
"endMoving" : ""
}
}
```

112
docs/modders/Hero Classes Format.md Normal file
View File

@@ -0,0 +1,112 @@
Schema in git:
[config/schemas/heroClass.json](https://github.com/vcmi/vcmi/blob/develop/config/schemas/heroClass.json)
## Required data
In order to make functional hero class you also need:
- Adventure animation (1 def file)
- Battle animation, male and female version (2 def files)
## Format
``` javascript
// Unique identifier of hero class, camelCase
"myClassName" :
{
// Various hero animations
"animation"
{
"battle" :
{
// Battle animation for female heroes
"female" : "myMod/battle/heroFemale",
// Battle animation for male heroes, can be same as female
"male" : "myMod/battle/heroMale"
}
},
// Description of map object representing this hero class. See map template format for details
"mapObject" : {
// Optional, hero ID-base filter, using same rules as building requirements
"filters" : {
"mutare" : [ "anyOf", [ "mutare" ], [ "mutareDrake" ]]
},
// List of templates used for this object, normally - only one is needed
"templates" : {
"normal" : { "animation" : "AH00_.def" }
}
},
// Translatable name of hero class
"name" : "My hero class",
// Identifier of faction this class belongs to
"faction" : "myFaction",
// Identifier of creature that should be used as commander for this hero class
// Can be a regular creature that has shooting animation
"commander" : "mage",
// Affinity of this class, might or magic
"affinity" : "might",
// Initial primary skills of heroes
"primarySkills" :
{
"attack" : 2,
"defence" : 0,
"spellpower" : 1,
"knowledge" : 2
},
// Chance to get specific primary skill on level-up
// This set specifies chances for levels 2-9
"lowLevelChance" :
{
"attack" : 15,
"defence" : 10,
"spellpower" : 50,
"knowledge" : 25
},
// Chance to get specific primary skill on level-up
// This set specifies chances for levels starting from 10
"highLevelChance" :
{
"attack" : 25,
"defence" : 5,
"spellpower" : 45,
"knowledge" : 25
},
// Chance to get specific secondary skill on level-up
// Skills not listed here will be considered as unavailable, including universities
"secondarySkills" :
{
"pathfinding" : 3.
"archery" : 6.
...
"resistance" : 5,
"firstAid" : 4
},
// Chance for a this hero class to appear in a town, creates pair with same field in town format
// Used for situations where chance was not set in "tavern" field, chance will be determined as:
// square root( town tavern chance * hero class tavern chance )
"defaultTavern" : 5,
// Chance for this hero to appear in tavern of this factions.
// Reversed version of field "tavern" from town format
// If faction-class pair is not listed in any of them
// chance set to 0 and the class won't appear in tavern of this town
"tavern" :
{
"castle" : 4,
...
"conflux" : 6
}
}
```

129
docs/modders/Hero Format.md Normal file
View File

@@ -0,0 +1,129 @@
Schema in git:
[config/schemas/hero.json](https://github.com/vcmi/vcmi/blob/develop/config/schemas/hero.json)
## Required data
In order to make functional hero you also need:
- Portraits, small and big versions (2 images)
- Specialty icons, small and big versions (2 images)
## Format
``` javascript
"myHeroName" :
{
// Identifier of class. Usually camelCase version of human-readable name
"class" : "wizard",
// List of starting spells, if available. Will also grant spellbook
"spellbook" :
[
"magicArrow"
],
// Set to true if the hero is female by default (can be changed in map editor)
"female" : true,
// If set to true hero will be unavailable on start and won't appear in taverns (campaign heroes)
"special" : true,
// All translatable texts related to hero
"texts" :
{
"name" : "My Hero",
"biography" : "This is a long story...",
"specialty" :
{
// Description visible when hovering over specialty icon
"description" : "Spell mastery: Magic Arrow",
// Tooltip visible on clicking icon. Can use {} symbols to change title to yellow
// as well as escape sequences "\n" to add line breaks
"tooltip" : "{Magic Arrow}\n\nCasts powerfull magic arrows",
// Name of your specialty
"name" : "Magic Arrow"
}
},
// Graphics used by hero
"images" :
{
// Small 32px speciality icon
"specialtySmall" : "myMod/myHero/specSmall.png",
// Large 44px speciality icon
"specialtyLarge" : "myMod/myHero/specLarge.png",
// Large 58x64px portrait
"large" : "myMod/myHero/large.png",
// Small 48x32px portrait
"small" : "myMod/myHero/small.png"
// Class-independent animation in battle
"small" : "myMod/myHero/battle.def"
},
// Initial hero army when recruited in tavern
// Must have 1-3 elements
"army" :
[
// First always available stack
{
// Identifier of creature in this stack
"creature" : "mage",
// Minimal and maximum size of stack. Size will be
// determined randomly at the start of the game
"max" : 2,
"min" : 1
},
// Second stack has 90 % chance to appear
{
"creature" : "archmage",
"max" : 1,
"min" : 1
},
// Third stack with just 20 % chance to appear
{
"creature" : "mage",
"max" : 2,
"min" : 1
}
],
// List of skills received by hero
// Not limited by size - you can add as many skills as you wish
"skills" :
[
{
// Skill level, basic, advanced or expert
"level" : "basic",
// Skill identifier, camelCase version of name
"skill" : "wisdom"
},
{
"level" : "basic",
"skill" : "waterMagic"
}
],
// Description of specialty mechanics using bonuses (with updaters)
"specialty" : {
// to be merged with all bonuses, use for specialties with multiple similar bonuses (optional)
"base" : {common bonus properties},
"bonuses" : {
// use updaters for bonuses that grow with level
"someBonus" : {Bonus Format},
"anotherOne" : {Bonus Format}
},
// adds creature specialty following the HMM3 default formula
"creature" : "griffin"
}
}
```

164
docs/modders/Mod file Format.md Normal file
View File

@@ -0,0 +1,164 @@
This is description of mod.json file, main file for mods.
Schema in git:
[config/schemas/mod.json](https://github.com/vcmi/vcmi/blob/develop/config/schemas/mod.json)
## Fields for local file and repository
``` 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",
// 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",
// 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/",
// Home page of mod or link to forum thread to contact the author
"contact" : "http://example.com",
// 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",
// 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 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
}
```
## Fields specific for local file
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
// list of factions/towns configuration files
"factions" :
[
"config/myMod/faction.json"
]
// List of hero classes configuration files
"heroClasses" :
[
"config/myMod/heroClasses.json"
],
// List of heroes configuration files
"heroes" :
[
"config/myMod/heroes.json"
],
// list of creature configuration files
"creatures" :
[
"config/myMod/creatures.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 spells defined in this mod
"spells" :
[
"config/myMod/spells.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"}
]
}
}
```
## Fields present only in repository
This is list of fields that must be added to mod record in repository
file
``` javascript
{
// URL which launcher will use to download mod
"download" : "http://example.com/mods/helloworld.zip",
// size of mod archive, in kilobytes
"size" : 12345,
// list of URL's with screenshots for this mod
"screenshots" : [
"http://example.com/images/helloworld_1.png"
]
}
```
## Notes
For mod description it is possible to use certain subset of HTML as
described here:
<http://qt-project.org/doc/qt-5.0/qtgui/richtext-html-subset.html>

236
docs/modders/Modding guidelines.md Normal file
View File

@@ -0,0 +1,236 @@
If you just want to play see [mod list](mod_list "wikilink").
## Creating mod
To make your own mod you need to create subdirectory in
**<data dir>/Mods/** with name that will be used as identifier for your
mod.
Main mod is file called **mod.json** and should be placed into main
folder of your mod, e.g. **Mods/myMod/mod.json**
All content of your mod should go into **Content** directory, e.g.
**Mods/myMod/Content/**. In future it will be possible to replace this
directory with single .zip archive.
Example of how directory structure of your mod may look like:
Mods/
myMod/
mod.json
Content/
data/ - unorganized files, mostly bitmap images (.bmp, .png, .pcx)
config/ - json configuration files
maps/ - h3m maps added or modified by mod
music/ - music files. Mp3 is fully supported, ogg may be added if needed
sounds/ - sound files, in wav format.
sprites/ - animation, image sets (H3 .def files or VCMI .json files)
video/ - video files, .bik or .smk
## Updating mod to next version of VCMI
See [Modding changelog](Modding_changelog "wikilink")
## Creating mod file
All VCMI configuration files use [JSON
format](http://en.wikipedia.org/wiki/Json) so you may want to
familiarize yourself with it first.
Mod.json is main file in your mod and must be present in any mod. This
file contains basic description of your mod, dependencies or conflicting
mods (if present), list of new content and so on.
Minimalistic version of this file:
``` javascript
{
"name" : "My test mod",
"description" : "My test mod that add a lot of useless stuff into the game"
}
```
See [Mod file Format](Mod_file_Format "wikilink") for its full
description.
## Overriding graphical files from Heroes III
Any graphical replacer mods fall under this category. In VCMI directory
**<mod name>/Content** acts as mod-specific game root directory. So for
example file **<mod name>/Content/Data/AISHIELD.PNG** will replace file
with same name from **H3Bitmap.lod** game archive.
Any other files can be replaced in exactly same way.
Note that replacing files from archives requires placing them into
specific location:
H3Bitmap.lod -> Data
H3Sprite.lod -> Sprites
Heroes3.snd -> Sounds
Video.vid -> Video
This includes archives added by expansions (e.g. **H3ab_bmp.lod** uses
same rules as **H3Bitmap.lod**)
### Replacing .def animation files
Heroes III uses custom format for storing animation: def files. These
files are used to store all in-game animations as well as for some GUI
elements like buttons and for icon sets.
These files can be replaced by another def file but in some cases
original format can't be used. This includes but not limited to:
- Replacing one (or several) icons in set
- Replacing animation with fully-colored 32-bit images
In VCMI these animation files can also be replaced by json description
of their content. See [Animation Format](Animation_Format "wikilink")
for full description of this format.
Example: replacing single icon
``` javascript
{
// List of replaced images
"images" :
[ // Index of replaced frame
{ "frame" : 0, "file" : "HPS000KN.bmp"}
//name of file that will be used as replacement
]
}
```
"High resolution main menu" mod can be used as example of file replacer
mod.
## Packaging mod into archive
For distribution it is recommended to package mod into .zip archives. To
create .zip archive you need to have file archiver like
[7zip](http://www.7-zip.org)
File structure of packaged mod should look like this
<modname>.zip/ <- Zip archive with high compression ratio
modname/ <- Archive contains main mod directory
mod.json <- main mod file
Content.zip/ <- Uncompressed archive with all mod data
Data/
... <- Identical to Content directory
Sprites/
You can create such structure using following instructions:
- Go to Mods/<modname>/Content directory
- Select all files in this directory and create archive with following
parameters:
- Archive name: Content.zip
- Format: ZIP
- Compression level: None/Store only
- Move created archive into Mods/<modname> directory and remove no
longer needed Content directory.
- Go to Mods/ directory
- Create archive from your mod with following parameters:
- Archive name: <modname>.zip
- Format: ZIP
- Compression level: Maximum
Resulting archive is recommended form for distributing mods for VCMI
## Releasing mods
Right now there are 3 ways to bring your mod to players:
- Manual download
- VCMI Repository
- Private repository
### Manual download
You can upload mod into some online file hosting and add link with
description of your mod into [mod list](mod_list "wikilink").
Note: Avoid using services that require registration or remove files
after certain period of time (examples are Wikisend and 4shared).
Instead you may use any of the services listed below:
- [MediaFire](http://mediafire.com)
- [Dropbox](https://dropbox.com)
- [Google Drive](https://drive.google.com)
- Any other service that does not has aforementioned problems
### VCMI Repository
Another option is to add mod into VCMI repository. This will allow
players to install mods directly from VCMI Launcher without visiting any
3rd-party sites.
Check for more details in [Mods repository](Mods_repository "wikilink").
### Private repository
It it also possible to create your own repository. To do this you need
to own your own server capable of file hosting or use file service that
provide direct download links (e.g. Dropbox with enabled public
directory).
Providing own repository allows you to deliver any new mods or updates
almost instantly and on the same level of integration with VCMI as mods
from VCMI repository.
To create empty repository you need to:
- Create directory that will contain repository
- Create file named "repository.json" in it
To add mods into such repository you need to:
- Copy packaged archive <modname>.zip into repository directory
- Copy mod information from mod.json into repository.json
- Add two extra fields about this mod into repository.json:
- "download" - public link that can be used to download the mod,
including <http://> prefix
- "size" - size of mod, in kilobytes. VCMI will use this number to
inform player on size of the mod.
Example on how mod entry should look in repository.json
``` javascript
{
...
"exampleMod" // ID of the mod, lowercase version of mod directory name
{
"name" : "My test mod",
"description" : "My test mod that add a lot of useless stuff into the game",
"author" : "Anonymous",
"contact" : "http://example.com",
"modType" : "Graphical",
"depends" :
[
"baseMod"
],
"download" : "http://example.com/vcmi/repository/exampleMod.zip",
"size" : 1234 //size, in kilobytes
//Note that entries that refer to files, e.g. "heroes". "creatures", "artifacts" and such
//are not necessary in repository.json and therefore can be removed
},
...
}
```
When repository is ready you can share public link to repository.json
with players. New repositories can added to vcmi launcher from settings
tab.
#### Dropbox: enabling public directory
New accounts create on Dropbox no longer have Public directory enabled
by default. You can enable it using this
[link](https://www.dropbox.com/enable_public_folder)
This will give you directory named "Public" as well as option "get
public link" for all files inside this directory.

99
docs/modders/Mods repository.md Normal file
View File

@@ -0,0 +1,99 @@
This article will introduce you to new VCMI mod repository system and
explain how new mods can be added there.
# How mod repository work
## Where files are hosted
Mods list hosted under main VCMI organization:
[vcmi-mods-repository](https://github.com/vcmi/vcmi-mods-repository).
Each mod hosted in it's own repository under separate organization
[vcmi-mods](https://github.com/vcmi-mods). This way if engine become
more popular in future we can create separate teams for each mod and
accept as many people as needed.
## Why Git / GitHub?
It's solve a lot of problems:
- Engine developers get control over all mods and can easily update
them without adding extra burden for modders / mod maintainers.
- With tools such as [GitHub Desktop](https://desktop.github.com/)
it's easy for non-programmers to contribute.
- Forward and backward compatibility. Stable releases of game use
compatible version of mods while users of daily builds will be able
to test mods supporting bleeding edge features.
- Tracking of changes for repository and mods. It's not big deal now,
but once we have scripting it's will be important to keep control
over what code included in mods.
- GitHub also create ZIP archives for us so mods will be stored
uncompressed and version can be identified by commit hash.
## On backward compatibility
Our mod list in vcmi-mods-repository had "develop" as primary branch.
Daily builds of VCMI use mod list file from this branch.
Once VCMI get stable release there will be branching into "1.0.0",
"1.1.0", etc. Launcher of released version will request mod list for
particular version.
Same way we can also create special stable branch for every mod under
"vcmi-mods" organization umbrella once new stable version is released.
So this way it's will be easier to maintain two versions of same mod:
for stable and latest version.
# Getting mod into repository
## Getting into vcmi-mods organization
Before your mod can be accepted into official mod list you need to get
it into repository under "vcmi-mods" organization umbrella. To do this
contact one of mod repository maintainers. If needed you can get own
team within "vcmi-mods" organization.
Link to our mod will looks like that:
https://github.com/vcmi-mods/adventure-ai-trace
## Rules of repository
### Allowed name for mod identifier
For sanity reasons mod identifier must only contain lower-case English
characters, numbers and hyphens.
my-mod-name
2000-new-maps
Sub-mods can be named as you like, but we strongly encourage everyone to
use proper identifiers for them as well.
### Rewriting History
Once you submitted certain commit into official mod list you are not
allowed to rewrite history before that commit. This way we can make sure
that VCMI launcher will always be able to download older version of any
mod.
Branches such as "develop" or stable branches like "1.0.0" should be
marked as protected on GitHub.
## Submitting mods to repository
Once mod ready for general public maintainer to make PR to
[vcmi-mods-repository](https://github.com/vcmi/vcmi-mods-repository).
## Requirements
Right now main requirements for a mod to be accepted into VCMI mods list
are:
- Mod must be complete. For work-in-progress mods it is better to use
other way of distribution.
- Mod must met some basic quality requirements. Having high-quality
content is always preferable.
- Mod must not contain any errors detectable by validation (console
message you may see during loading)
- Music files must be in Ogg/Vorbis format (\*.ogg extension)

153
docs/modders/Object Format.md Normal file
View File

@@ -0,0 +1,153 @@
## Description
Full object consists from 3 parts:
- Object group - set of objects that have similar behavior and share
same identifier in H3 (towns, heroes, mines, etc)
- Object type - object with fixed behavior but without fixed
appearance. Multiple objects types may share same group
- Object template - defines appearance of an object - image used to
display it, its size & blockmap. These entries only describe
templates that will be used when object is placed via map editor or
generated by the game. When new object is created its starting
appearance will be copied from template
To create visitable object which grants all kinds of rewards (gold,
experience, Bonuses etc...), see
[Rewardable](https://github.com/vcmi/vcmi/wiki/Modding-~-Objects-~-Rewardable)
page.
## Object group format
``` javascript
{
"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,
// 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
"handler" : "mine",
// default values, will be merged with each type during loading
"base" : { <object type format> },
"types" : {
<list of object types, see below>
}
}
}
```
## 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,
// 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" : { ... },
// Data for random map generator that describes how object should be placed.
// If this entry is missing object will not be placed by RMG
"rmg" : {
// How valuable this object is, 1k = worthless, 20k = relic level
"value" : 5000,
// Optional, how many of such objects can be placed on map
"mapLimit" : 25,
// Optional, how many of such objects can be placed in one zone
"zoneLimit" : 4,
// Rarity of object, 10 = rare, 100 = common
"rarity" : 50
}
// default values, will be merged with each template during loading
// mostly needed to avoid redefining whole template to change 1-2 fields
"base" : { <template format> },
"templates" : {
<templates description, see below>
}
}
}
```
## Object template format
``` javascript
{
"myCoolObjectTemplate" :
{
// resource ID of animation, relative to SPRITES directory (def file or json file)
"animation":"DEFNAME.def",
// resource ID of animation for mapeditor, relative to SPRITES directory (def file or json file)
//0.98c+
"editorAnimation":"DEFNAME.def",
// directions from which hero can visit this object.
// "+" means that object can be visited from that direction, or "-" othervice
// default not visitable
"visitableFrom" : [
"---",
"+++",
"+++"
],
// passability of the object
// 0=not visible, passable. Space symbol ' ' can be used as well
// V=visible, passable
// B=blocked, visible
// H=hidden - blocked, not visible tile
// A=activable, visible, passable depending on visitableFrom field
// T=trigger - visiting the tile will trigger the object, tile is not visible (e.g. event)
//top and left leading zeros are optional and in fact ignored
//bottom, right corner of mask = bottom right corner of animation frame
//animation can not be larger than size of mask
"mask":[
"00000000",
"00000000",
"00000000",
"0000VVVV",
"0000HBBB",
"0000HHAT"
],
// optional; default or if explicitly set to null: all terrains except rock
// allowed terrain types to place object too. 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"
"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
}
}
```

86
docs/modders/Skill Format.md Normal file
View File

@@ -0,0 +1,86 @@
## Main format
``` javascript
{
"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}
}
}
```
## Skill level base format
Json object with data common for all levels can be put here. These
configuration parameters will be default for all levels. All mandatory
level fields become optional if they equal "base" configuration.
## Skill level format
``` javascript
{
//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}
//...
}
}
```
## Example
The following modifies the tactics skill to grant an additional speed
boost at advanced and expert levels.
``` javascript
"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 }
}
}
}
```

400
docs/modders/Spell Format.md Normal file
View File

@@ -0,0 +1,400 @@
# Main format
``` javascript
{
"spellName":
{ //numeric id of spell required only for original spells, prohibited for new spells
"index": 0,
//Original Heroes 3 info
//Mandatory, spell type
"type": "adventure",//"adventure", "combat", "ability"
//Mandatory, spell target type
"targetType":"NO_TARGET",//"CREATURE","OBSTACLE"."LOCATION"
//Mandatory
"name": "Localizable name",
//Mandatory, flags structure of school names, Spell schools this spell belongs to
"school": {"air":true, "earth":true, "fire":true, "water":true},
//number, mandatory, Spell level, value in range 1-5
"level": 1,
//Mandatory, base power
"power": 10,
//Mandatory, default chance for this spell to appear in Mage Guilds
//Used only if chance for a faction is not set in gainChance field
"defaultGainChance": 0,
//Optional, chance for it to appear in Mage Guild of a specific faction
//NOTE: this field is linker with faction configuration
"gainChance":
{
"factionName": 3
},
//VCMI info
"animation":{<Animation format>},
//countering spells, flags structure of spell ids (spell. prefix is required)
"counters": {"spell.spellID1":true, ...}
//Mandatory,flags structure:
// indifferent, negative, positive - Positiveness of spell for target (required)
// damage - spell does damage (direct or indirect)
// offensive - direct damage (implicitly sets damage and negative)
// rising - rising spell (implicitly sets positive)
// summoning //todo:
// special - can be obtained only with bonus::SPELL
"flags" : {"flag1": true, "flag2": true},
//DEPRECATED | optional| no default | flags structure of bonus names,any one of these bonus grants immunity. Negatable by the Orb.
"immunity": {"BONUS_NAME":true, ...},
//DEPRECATED | optional| no default | flags structure of bonus names
//any one of these bonus grants immunity, cant be negated
"absoluteImmunity": {"BONUS_NAME": true, ...},
//DEPRECATED | optional| no default | flags structure of bonus names, presence of all bonuses required to be affected by. Negatable by the Orb.
"limit": {"BONUS_NAME": true, ...},
//DEPRECATED | optional| no default | flags structure of bonus names, presence of all bonuses required to be affected by. Cant be negated
"absoluteLimit": {"BONUS_NAME": true, ...},
//[WIP] optional | default no limit no immunity
//
"targetCondition" {
//at least one required to be affected
"anyOf" : {
//generic format
"mod:metaClassName.typeName":"absolute",//"normal", null or empty ignored - use for overrides
},
//all required to be affected (like [absolute]limit)
"allOf" : {
//bonus type format
"bonus.BONUS_TYPE":"absolute"//"normal" Short bonus type format
"modId:bonus.bonusTypeName":"absolute"//"normal" Future bonus format for configurable bonuses
},
//at least one grants immunity (like [absolute]immunity)
"noneOf": {
//some more examples
"core:creature.imp":"absolute", //[to be in initial version] this creature explicitly absolutely immune
"core:bonus.MIND_IMMUITY":"normal", // [to be in initial version] new format of existing mind spell immunity
"core:artifact.armorOfWonder":"absolute", //[possible future extension] this artifact on target itself (!) explicitly grant absolute immune
"core:luck":["absolute", 3], // [possible future extension] lack value of at least 3 grant absolute immunity from this horrible spell
"core:custom":[<script>] // [possible future extension] script lines for arbitrary condition
}
}
//graphics; mandatory; object;
"graphics":
{
// ! will be moved to bonus type config in next bonus config version
// iconImmune - OPTIONAL; string;
//resource path of icon for SPELL_IMMUNITY bonus (relative to DATA or SPRITES)
"iconImmune":"ZVS/LIB1.RES/E_SPMET",
// iconScenarioBonus- mandatory, string, image resource path
//resource path of icon for scenario bonus
"iconScenarioBonus": "MYSPELL_B",
// iconEffect- mandatory, string, image resource path
//resource path of icon for spell effects during battle
"iconEffect": "MYSPELL_E",
// iconBook- mandatory, string, image resource path
//resource path of icon for spellbook
"iconBook": "MYSPELL_E",
// iconScroll- mandatory, string, image resource path
//resource path of icon for spell scrolls
"iconScroll": "MYSPELL_E"
},
//OPTIONAL; object; TODO
"sounds":
{
//OPTIONAL; resourse path, casting sound
"cast":"LIGHTBLT"
},
//Mandatory structure
//configuration for no skill, basic, adv, expert
"levels":{
"base": {Spell level base format},
"none": {Spell level format},
"basic":{Spell level format},
"advanced":{Spell level format},
"expert":{Spell level format}
}
}
}
```
# Animation format
``` javascript
{
"projectile": [
{"minimumAngle": 0 ,"defName":"C20SPX4"},
{"minimumAngle": 0.60 ,"defName":"C20SPX3"},
{"minimumAngle": 0.90 ,"defName":"C20SPX2"},
{"minimumAngle": 1.20 ,"defName":"C20SPX1"},
{"minimumAngle": 1.50 ,"defName":"C20SPX0"}
],
"hit":["C20SPX"],
"affect":[{"defName":"C03SPA0", "verticalPosition":"bottom"}, "C11SPA1"]
}
```
# Spell level base format
Json object with data common for all levels can be put here. These
configuration parameters will be default for all levels. All mandatory
level fields become optional if they equal "base" configuration.
## Example
This will make spell affect single target on all levels except expert,
where it is massive spell.
``` javascript
"base":{
"range": 0
},
"expert":{
"range": "X"
}
```
# Spell level format
``` javascript
{
//Mandatory, localizable description
//Use {xxx} for formatting
"description": "",
//Mandatory, number,
//cost in mana points
"cost": 1,
//Mandatory, number
"power": 10,
//Mandatory, number
"aiValue": 20,
//Mandatory, flags structure //TODO
// modifiers make sense for creature target
//
//
"targetModifier":
{
"smart": false, //true: friendly/hostile based on positiveness; false: all targets
"clearTarget": false,
"clearAffected": false,
}
//Mandatory
//spell range description in SRSL
// range "X" + smart modifier = enchanter casting, expert massive spells
// range "X" + no smart modifier = armageddon, death ripple, destroy undead
"range": "X",
//DEPRECATED, Optional, arbitrary name - bonus format map
//timed effects, overriding by name
"effects":
{
"firstEffect": {[bonus format]},
"secondEffect": {[bonus format]}
//...
},
//DEPRECATED, cumulative effects that stack while active
"cumulativeEffects":
{
"firstCumulativeEffect": {[bonus format]}
//...
},
"battleEffects":
{
"mod:firstEffect": {[effect format]},
"mod:secondEffect": {[effect format]}
//...
}
}
```
# Configurable battle effects
**If spell have at least one special effect it become configurable spell
and spell configuration processed different way**
## Configurable spell
Configurable spells ignore *offensive* flag, *effects* and
*cumulativeEffects*. For backward compatibility *offensive* flag define
Damage effect, *effects* and *cumulativeEffects* define Timed effect.
## Special effect common format
``` javascript
"mod:effectId":{
"type":"mod:effectType", //identifier of effect type
"indirect": false, // effect will be deferred (f.e. land mine damage)
"optional": false // you can cast spell even if this effect in not applicable
//for unit target effects
"ignoreImmunity" : false,
"chainFactor" : 0.5,
"chainLength" : 4
//other fields depending on type
}
```
## catapult
``` javascript
"mod:effectId":{
"type": "core:catapult"
"targetsToAttack": 1, //How many targets will be attacked by this
"chanceToHitKeep" : 5, //If it is a targeted spell, chances to hit keep
"chanceToHitGate" : 25, //If it is a targeted spell, chances to hit gate
"chanceToHitTower" : 10, //If it is a targeted spell, chances to hit tower
"chanceToHitWall" : 50, //If it is a targeted spell, chances to hit wall
"chanceToNormalHit" : 60, //Chance to have 1 damage to wall, used for both targeted and massive
"chanceToCrit" : 30 //Chance to have 2 damage to wall, used for both targeted and massive
}
```
## Clone
Configurable version of Clone spell.
``` javascript
"mod:effectId":{
"type": "core:clone"
"maxTier" : 3//unit tier
}
```
## Damage effect
If effect is automatic, spell behave like offensive spell (uses power,
levelPower etc)
``` javascript
"mod:effectId":{
"type": "core:damage",
"killByCount": false, //if true works like Death Stare
"killByPercentage" : false, //if true works like DESTRUCTION ability
//TODO: options override
}
```
## Dispel
documetation
## Heal
documetation
## Obstacle
documetation
## Remove obstacle
documetation
## Sacrifice
documetation
## Summon
documetation
## Teleport
documetation
## Timed
If effect is automatic, spell behave like \[de\]buff spell (effect and
cumulativeEffects ignored)
``` javascript
"mod:effectId":{
"type": "core:timed",
"cumulative": false
"bonus":
{
"firstBonus":{[bonus format]}
//...
}
}
```
# Additional documentation
## Targets, ranges, modifiers
- CREATURE target (only battle spells)
- range 0: smart assumed single creature target
- range "X" + smart modifier = enchanter casting, expert massive
spells
- range "X" + no smart modifier = armageddon, death ripple,
destroy undead
- any other range (including chain effect)
- smart modifier: smth like cloud of confusion in H4 (if I
remember correctly :) )
- no smart modifier: like inferno, fireball etc. but target
only creature
<!-- -->
- NO_TARGET
- no target selection,(abilities, most adventure spells)
<!-- -->
- LOCATION
- any tile on map/battlefield (inferno, fireball etc.), DD also
here but with special handling
- clearTarget - destination hex must be clear (unused so far)
- clearAfffected - all affected hexes must be clear (forceField,
fireWall)
<!-- -->
- OBSTACLE target
- range 0: any single obstacle
- range X: all obstacles

388
docs/modders/Town Format.md Normal file
View File

@@ -0,0 +1,388 @@
## Required data
In order to make functional town you also need:
### Images
- Creature backgrounds images, 120x100 and 130x100 versions (2 images)
- Set of puzzle map pieces (48 images)
- Background scenery (1 image)
- 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)
- Destructible walls (4 parts, 3 images each)
- Static walls (3 images)
- Town gates (5 images)
- Moat (2 images)
### Animation
- Adventure map images for village, town and capitol (3 def files)
### Music
- Town theme music track (1 music file)
### Buildings
Each town requires a set of buildings (Around 30-45 buildings)
- Town animation file (1 animation file)
- Selection highlight (1 image)
- Selection area (1 image)
- Town hall icon (1 image)
## Faction node (root entry for town configuration)
``` javascript
// Unique faction identifier. Should be unique.
"myTown" :
{
// 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
"nativeTerrain" : "grass",
// Localizable town name, e.g. "Rampart"
"name" : "",
// Faction alignment. Can be good, neutral (default) or evil.
"alignment" : "",
// Backgrounds for creature screen, two versions: 120px-height and 130-px height
"creatureBackground"
{
// Paths to background images
"120px" : "",
"130px" : ""
}
// Town puzzle map
"puzzleMap" :
{
// Prefix for image names, e.g. "PUZCAS" for name "PUZCAS12.png"
"prefix" : "",
// List of map pieces. First image will have name <prefix>00, second - <prefix>01 and so on
"pieces" :
[
{
// Position of image on screen
"x" : 0
"y" : 0
//indicates order in which this image will be opened
"index" : 0
},
...
]
]
}
```
## Town node
``` javascript
{
// 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
"mapObject" :
{
// Optional, controls what template will be used to display this object.
// Whenever player builds a building in town game will test all applicable templates using
// tests with matching name and on success - set such template as active.
// There are 3 predefined filters: "village", "fort" and "capitol" that emulate H3 behavior
"filter" : {
"capitol" : [ "anyOf", [ "capitol" ], [ "castle" ] ]
},
// List of templates that represent this object. For towns only animation is required
// See object template description for other fields that can be used.
"templates" : {
"village" : { "animation" : "" },
"castle" : { "animation" : "" },
"capitol" : { "animation" : "" }
}
},
//icons, small and big. Built versions indicate constructed during this turn building.
"icons" :
{
"village" : {
"normal" : {
"small" : "modname/icons/hall-small.bmp",
"large" : "modname/icons/hall-big.bmp"
},
"built" : {
"small" : "modname/icons/hall-builded-small.bmp",
"large" : "modname/icons/hall-builded-big.bmp"
}
},
"fort" : {
"normal" : {
"small" : "modname/icons/fort-small.bmp",
"large" : "modname/icons/fort-big.bmp"
},
"built" : {
"small" : "modname/icons/fort-builded-small.bmp",
"large" : "modname/icons/fort-builded-big.bmp"
}
}
},
// Path to town music theme, e.g. "music/castleTheme"
"musicTheme" : "",
// List of structures which represents visible graphical objects on town screen.
// See detailed description below
"structures" :
{
"building1" : { ... },
...
"building9" : { ... }
},
// List of names for towns on adventure map e.g. "Dunwall", "Whitestone"
// Does not have any size limitations
"names" : [ "", ""],
// Background scenery for town screen, size must be 800x374
"townBackground": "",
// Small scenery for window in mage guild screen
"guildWindow": "",
// Background image for window in mage guild screen - since 0.95b
"guildBackground" : "",
// Video for tavern window - since 0.95b
"tavernVideo" : "",
// 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
"hallSlots":
[
[ [ "buildingID1" ], [ "buildingID2", "buildingID3" ] ],
...
],
// List of creatures available on each tier. Number of creatures on each tier
// is not hardcoded but it should match with number of dwelling for each level.
// For example structure below would need buildings with these id's:
// first tier: 30 and 37, second tier: 31, third tier: 32, 39, 46
"creatures" :
[
["centaur", "captainCentaur"],
["dwarf"],
["elf", "grandElf", "sharpshooter"],
...
],
// Buildings, objects in town that affect mechanics. See detailed description below
"buildings" :
{
"building1" : { ... },
...
"building9" : { ... }
},
// Description of siege screen, see below
"siege" : { ... },
// Chance for a hero class to appear in this town, creates pair with same field in class format
// Used for situations where chance was not set in "tavern" field, chance will be determined as:
// square root( town tavern chance * hero class tavern chance )
"defaultTavern" : 5,
// Chance of specific hero class to appear in this town
// Mirrored version of field "tavern" from hero class format
"tavern" :
{
"knight" : 5,
"druid" : 6
},
// 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
"primaryResource" : "gems",
// maximum level of mage guild
"mageGuild" : 4,
// war machine produced in town
"warMachine" : "ballista"
}
```
## Siege node
``` javascript
// 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"
{
// shooter creature name
"shooter" : "archer",
// (VCMI 1.1 or later) Large icon of towers, for use in battle queue
"towerIconLarge" : "",
// (VCMI 1.1 or later) Small icon of towers, for use in battle queue
"towerIconSmall" : "",
// prefix for all siege images. Final name will be composed as <prefix><suffix>
"imagePrefix" : "SGCS",
// Descriptions for towers. Each tower consist from 3 parts:
// tower itself - two images with untouched and destroyed towers
// battlement or creature cover - section displayed on top of creature
// creature using type from "shooter" field above
"towers":
{
// Top tower description
"top" :
{
"tower" : { "x": 0, "y": 0}, // "TW21" ... "TW22"
"battlement" : { "x": 0, "y": 0}, // "TW2C"
"creature" : { "x": 0, "y": 0}
},
// Central keep description
"keep" :
{
"tower" : { "x": 0, "y": 0}, // "MAN1" ... "MAN2"
"battlement" : { "x": 0, "y": 0}, // "MANC"
"creature" : { "x": 0, "y": 0}
},
// Bottom tower description
"bottom" :
{
"tower" : { "x": 0, "y": 0}, // "TW11" ... "TW12"
"battlement" : { "x": 0, "y": 0}, // "TW1C"
"creature" : { "x": 0, "y": 0}
},
},
//Two parts of gate: gate itself and arch above it
"gate" :
{
"gate" : { "x": 0, "y": 0}, // "DRW1" ... "DRW3" and "DRWC" (rope)
"arch" : { "x": 0, "y": 0} // "ARCH"
},
// Destructible walls. In this example they are ordered from top to bottom
// Each of them consist from 3 files: undestroyed, damaged, destroyed
"walls" :
{
"upper" : { "x": 0, "y": 0}, // "WA61" ... "WA63"
"upperMid" : { "x": 0, "y": 0}, // "WA41" ... "WA43"
"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"
// Static non-destructible walls. All of them have only one piece
"static" :
{
// Section between two bottom destructible walls
"bottom" : { "x": 0, "y": 0}, // "WA2"
// Section between two top destructible walls
"top" : { "x": 0, "y": 0}, // "WA5"
// Topmost wall located behind hero
"background" : { "x": 0, "y": 0} // "TPWL"
}
}
```
## Building node
``` javascript
{
"id" : 0,
"name" : "",
"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
//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"
}
```
Building requirements can be described using logical expressions:
``` javascript
"requires" :
[
"allOf", // Normal H3 "build all" mode
[ "mageGuild1" ],
[
"noneOf", // available only when none of these building are built
[ "dwelling5A" ],
[ "dwelling5AUpgrade" ]
],
[
"anyOf", // any non-zero number of these buildings must be built
[ "tavern" ],
[ "blacksmith" ]
]
]
```
## Structure node
``` javascript
{
"animation" : "", // def file with animation
"x" : 0,
"y" : 0,
"z" : 0, // used for blit order. Higher value places structure close to screen
"border" : "", // selection highlight
"area" : "" // used to detect building selection
}
```