Starting from version 1.3, VCMI supports its own campaign format. Campaigns have *.vcmp file format and it consists from campaign json and set of scenarios (can be both *.vmap and *.h3m)
To start making campaign, create file named 00.json. See also Packing campaign
Basic structure of this file is here, each section is described in details below
{
"version" : 1,
<header properties>
"scenarios" : [
{
//scenario 1
<scenario properties>
},
{
//scenario 2
<scenario properties>
}
]
}"version" defines version of campaign file. Larger versions should have more features and flexibility, but may not be supported by older VCMI engines. See compatibility table
In header are parameters describing campaign properties
...
"regions": {...},
"name": "Campaign name",
"description": "Campaign description",
"author": "Author",
"authorContact": "Author contact",
"campaignVersion": "Campaign version",
"creationDateTime": "Creation date and time",
"allowDifficultySelection": true, "regions"contains information about background and regions. See section campaign regions for more information"name"is a human readable title of campaign"description"is a human readable description of campaign"author"is the author of the campaign"authorContact"is a contact address for the author (e.g. email)"campaignVersion"is creator defined version"creationDateTime"unix time of campaign creation"allowDifficultySelection"is a boolean field (true/false) which allows or disallows to choose difficulty before scenario start
Scenario description looks like follow:
{
"map": "maps/SomeMap",
"preconditions": [],
"color": 0,
"difficulty": 2,
"regionText": "",
"prolog": {},
"epilog": {},
"heroKeeps": [],
"keepCreatures": [],
"startOptions": "none",
"playerColor": 0,
"bonuses": [ <see bonus description> ]
}"map"map name without extension but with relative path. Both *.h3m and *.vmap maps are supported. If you will pack scenarios inside campaign, numerical map name should be used, see details in packing campaign"preconditions"enumerate scenarios indexes which must be completed to unlock this scenario. For example, if you want to make sequential missions, you should specify"preconditions": []for first scenario, but for second scenario it should be"preconditions": [0]and for third"preconditions": [0, 1]. But you can allow non-linear conquering using this parameter"color"defines color id for the region. Possible values are0: red, 1: blue, tan: 2, green: 3, orange: 4, purple: 5, teal: 6, pink: 7"difficulty"sets initial difficulty for this scenario. If"allowDifficultySelection"is defined for campaign, difficulty may be changed by player. Possible values are0: pawn, 1: knight, 2: rook, 3: queen, 4: king"regionText"is a text which will be shown if player holds right button over region"prolog"/"epilog"optional, defines prolog/epilog for scenario. See prolog/epilog section for more information"heroKeeps"defines what hero will carry to the next scenario. Can be specified one or several attributes from list"experience", "primarySkills", "secondarySkills", "spells", "artifacts""keepCreatures"array of creature types which hero will carry to the next scenario. Game identifiers are used to specify creature type."startOptions"defines what type of bonuses player may have. Possible values are"none", "bonus", "crossover", "hero"none: player starts scenario without bonuses. Descriptionbonus: player chooses one of the predefined bonuses. Descriptioncrossover: player will start with hero from previous scenario. Descriptionhero: player will start scenario with specified hero. Description
"playerColor"defines color id of flag which player will play for. Possible values are0: red, 1: blue, tan: 2, green: 3, orange: 4, purple: 5, teal: 6, pink: 7- "bonuses" array of possible bonus objects, format depends on
"startOptions"parameter
Prolog and epilog properties are optional
{
"video": "NEUTRALA.smk", //video to show
"music": "musicFile.ogg", //music to play, should be located in music directory
"voice": "musicFile.wav", //voice to play, should be located in sounds directory
"text": "some long text" //text to be shown
}If startOptions is none, bonuses field will be ignored
If startOptions is bonus, bonus format may vary depending on its type.
{
"what": "",
<attributes>
},"what"field defines bonus type. Possible values are:spell, creature, building, artifact, scroll, primarySkill, secondarySkill, resource"spell"has following attributes (fields):"hero": hero who will get spell (see below)"type": spell type, string, e.g. "firewall"
"creature"has following attributes (fields):"hero": hero who will get spell (see below)"type": creature type, string, e.g. "pikeman""amount": amount of creatures
"building"has following attributes (fields):"type": building type (string), e.g. "citadel" or "dwellingLvl1"
"artifact"has following attributes (fields):"hero": hero who will get spell (see below)"type": artifact type, string, e.g. "spellBook"
"scroll"has following attributes (fields):"hero": hero who will get spell (see below)"type": spell type in the scroll, string, e.g. "firewall"
"primarySkill"has following attributes (fields):"hero": hero who will get spell (see below)"attack": amount of attack gained"defence": amount of defence gained"spellpower": amount of spellpower gained"knowledge": amount of knowledge gained
"secondarySkill"has following attributes (fields):"hero": hero who will get spell (see below)"type": skill type, string, e.g. "logistics""amount": skill level,1: beginner, 2: advanced, 3: expert
"resource"has following attributes (fields):"type": resource type, one ofwood, ore, mercury, sulfur, crystal, gems, gold, common, rare, wherecommonis both wood and ore,raremeans that bonus gives each rare resource"amount": amount of resources
"hero"can be specified as explicit hero name and as one of keywords:strongest,generated
If startOptions is crossover, heroes from specific scenario will be moved to this scenario. Bonus format is following
{
"playerColor": 0,
"scenario": 0
},"playerColor"from what player color heroes shall be taken. Possible values are0: red, 1: blue, tan: 2, green: 3, orange: 4, purple: 5, teal: 6, pink: 7"scenario"from which scenario heroes shall be taken. 0 means first scenario
If startOptions is hero, hero can be chosen as a starting bonus. Bonus format is following
{
"playerColor": 0,
"hero": "random"
}"playerColor"from what player color heroes shall be taken. Possible values are0: red, 1: blue, tan: 2, green: 3, orange: 4, purple: 5, teal: 6, pink: 7"hero"can be specified as explicit hero name and as one of keywords:random
Predefined campaign regions are located in file campaign_regions.json
{
"prefix": "G3",
"color_suffix_length": 1,
"desc": [
{ "infix": "A", "x": 289, "y": 376 },
{ "infix": "B", "x": 60, "y": 147 },
{ "infix": "C", "x": 131, "y": 202 }
]
},"prefix"used to identify all images related to campaign. In this example, background picture will beG3_BG"inflix"ised to identify all images related to region. In this example, it will be pictures starting fromG3A_..., G3B_..., G3C_...""color_suffix_length"identifies suffix length for region colourful frames. 1 is used forR, B, N, G, O, V, T, P, value 2 is used forRe, Bl, Br, Gr, Or, Vi, Te, Pi
After campaign scenarios and campaign description are ready, you should pack them into *.vcmp file. This file is basically headless gz archive.
Your campaign should be stored in some folder with json describing campaign information.
Place all your scenarios inside same folder and enumerate their filenames, e.g 01.vmap, '02.vmap', etc.
my-campaign/
|-- 00.json
|-- 01.vmap
|-- 02.vmap
|-- 03.vmap
If you use unix system, execute this command to pack your campaign:
gzip -c -n ./* >> my-campaign.vcmp
If you are using Windows system, try this https://gnuwin32.sourceforge.net/packages/gzip.htm
| Version | Min VCMI | Max VCMI | Description |
|---|---|---|---|
| 1 | 1.3 | Initial release |