Modding changelog

From VCMI Project Wiki
Jump to: navigation, search

This page lists changes in modding format between various versions of vcmi

0.95 -> 0.96


  • Submods support. Mod may have their own "submods" located in <modname>/Mods directory
  • Town dwellings must be defined using Object Format instead of being part of town format. Example of fully configured dwelling in 0.96, See dwelling format for details. File with this code must be listed in "objects" entry in mod.json
	"core:creatureGeneratorCommon" : {
		"types" : {
			"waterfall" : {
				"name" : "Waterfall",
				"creatures" : [[ "nymph" ]],
				"templates" : {
					"default" : {
						"animation" : "hota/map/waterfall",
						"mask" : [ "VVV", "VVV", "VBA" ]
  • Appearance of town and heroes can be configured using "mapObject" entry instead of "adventureMap". See VCMI config files for examples or this test mod as example for some non-standard usage (like Heroes II or HotA behavior)

Mod file format

  • New fields to indicate license used by mod: "licenseURL" and "licenseName".
  • Launcher can now display mod changelog from field "changelog" in mod format.
  • Launcher will now download and display screenshots from a mod. Screenshots must be listed under "screenshots" field in repository
  • New field in mod format: "keepDisabled". Mods with this field set to true will not be automatically enabled on install

Spells format

  • Spells now use new configuration format described here

Town format

  • New fields in town node: "tavernVideo" that controls video displayed in tavern and "guildBackground" that controls background for mages guild.
  • Entry "adventureMap" has been replaced by "mapObject"
  • Resources provided by buildings may now be configured in "produce" entry.

Hero classes format

  • Entry "adventureMap" has been replaced by "mapObject"


  • New propagators are avaliable: HERO, TEAM_PROPAGATOR, GLOBAL_EFFECT. See full list of bonus propagators
  • Heroes per player limit can now be configured in defaultMods.json file

0.94 -> 0.95


  • VCMI now supports Unicode. All json files that contain non-English data must be converted to UTF-8 encoding.
  • Json validation has been improved. VCMI will now detect any missing files on startup.
  • All translatable strings are now in file config/translate.json. Mods may replace this file in order to provide translation for vcmi.


  • It is possible to replace win/loss conditions from map or campaign using subset of map header format (see Map format). To do this mod must contain file "config/mapOverrides.json" using same format as file with such name in vcmi.


  • New field for hero class and town formats: "defaultTavern". This property will determine chance of hero class to appear in tavern if such value was not found in "tavern" fields.
  • Support for extended building requirements.
  • String identifiers for buildings are now actually used in:
    • Town hall buildings list
    • Town buliding property "upgrades"
    • Town structure property "builds"
    • Town structure property "id" is no longer used and has been removed
  • Property "commander" has been moved to hero class

Hero class

  • New field for hero class and town formats: "defaultTavern". This property will determine chance of hero class to appear in tavern if such value was not found in "tavern" fields.
  • New field: affinity (might or magic)
  • Property "commander" has been moved to hero class


  • New field: "idle" that indicates speed of idle animation.

0.93 -> 0.94


  • All mods must already be compatible with vcmi 0.93. This can be checked bu running mod with 0.93 installed: any error messages printed in console log on start must be fixed.
  • Zip support. Mods may use zip archives for their data. This is optional but recommended for performance reasons.
    • To use zip archives: create archive with files from Content directory in it and place it in mod directory with name
    • Note: if both archive and directory are present files in directory will override files in archive.
    • See update cove mod for example:
  • For music mods should use Ogg/Vorbis format instead of Mp3. This is necessary but not enforced due to lack of mp3 support on some platforms as well as legal issues from mp3 patents.

Mod file format

  • New required fields: "version", "author", "contact" and "modType".


  • property "town/siege/shooterHeight" has been removed

0.92 -> 0.93


  • Identifiers resolution system. Same string identifiers from different mods will no longer conflict. Side effect: mod can access identifiers only from mods that are explicitly marked as required. This causes issue with current way to add new towns via 3 mods. There are two ways to fix this:
    • Merge 3 mods into one.
    • Move all creatures and hero classes into "neutral" faction and add proper overrides into town mod. See Cove for example.


  • Icons use path to icon instead of image indexes:
"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"
  • Buildings and structures use string identifiers instead of list
"buildings" :
    "building1" : { <Building format> },


  • Field graphics/iconIndex removed in favor of paths to two icons:
"graphics" :
    "iconSmall" : "modname/icons/iconSmall.png",
    "iconLarge" : "modname/icons/iconLarge.png"
  • Abilities use string identifiers instead of list
"ability" :
    "ability" : { <Bonus format> },
  • Field graphics/attackClimaxFrame was moved into missile description
  • Field graphics/missile/spinning is now removed.


  • Field iconIndex removed in favor of path to icon


  • Field iconIndex removed in favor of path to icons
  • Spellbook description now uses string ID's for spells instead of numeric indexes:
"spellbook" :

Modding related articles

Main articles
Modding changelog Modding guidelines Mod Handler

Mod file Format
Town Format Creature Format Hero Classes Format
Artifact Format Animation Format Hero Format
Bonus Format Object Format Spell Format

Work-in-progress formats
Building bonuses Map format
Bonus Type Format Random map template

Outdated pages
Mod system proposal