Mod file Format

From VCMI Project Wiki
Jump to: navigation, search

This is description of mod.json file, main file for mods.

Schema in git: config/schemas/mod.json

Fields for local file and repository

    // 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" : "",

    // Home page of mod or link to forum thread to contact the author
    "contact" : "",

    // 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" :
    // List of mods that can't be enabled in the same time as this one
    "conflicts" :

    //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

    // 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" :

    // List of hero classes configuration files
    "heroClasses" :

    // List of heroes configuration files
    "heroes" :

    // list of creature configuration files
    "creatures" :

    // List of artifacts configuration files
    "artifacts" :

    // List of objects defined in this mod
    "objects" :

    // List of spells defined in this mod
    "spells" :

    // List of RMG templates defined in this mod
    "templates" :

    // 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
                {"type" : "dir",  "path" : "/Content"}

Fields present only in repository

This is list of fields that must be added to mod record in repository file

    // URL which launcher will use to download mod
    "download" : "",

    // size of mod archive, in kilobytes
    "size" : 12345,

    // list of URL's with screenshots for this mod
    "screenshots" : [


For mod description it is possible to use certain subset of HTML as described here:

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