- Markdown will now be validated as part of Github CI - Applied auto-fix to most common issues (mostly whitespace related) - Fixed manually some of more complex cases Some valid markdownlint rules are currently disabled, to avoid failing CI, can be enabled in future
9.6 KiB
Campaign Format
Introduction
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 header.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
Header properties
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"loadingBackground"
is for setting a different loading screen background"introVideo"
is for defining an optional intro video"outroVideo"
is for defining an optional outro video"videoRim"
is for the Rim around the optional video (default is INTRORIM)
Scenario description
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/Epilog
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
}
Start options and bonuses
None start option
If startOptions
is none
, bonuses
field will be ignored
Bonus start option
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
, wherecommon
is both wood and ore,rare
means 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
Crossover start option
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
Hero start option
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
Regions description
Predefined campaign regions are located in file campaign_regions.json
{
"background": "ownRegionBackground.png",
"suffix": ["Enabled", "Selected", "Conquered"],
"prefix": "G3",
"colorSuffixLength": 1,
"desc": [
{ "infix": "A", "x": 289, "y": 376, "labelPos": { "x": 98, "y": 112 } },
{ "infix": "B", "x": 60, "y": 147, "labelPos": { "x": 98, "y": 112 } },
{ "infix": "C", "x": 131, "y": 202, "labelPos": { "x": 98, "y": 112 } }
]
},
"background"
optional - use own image name for background instead of adding "_BG" to the prefix as name"prefix"
used to identify all images related to campaign. In this example (if background parameter wouldn't exists), background picture will beG3_BG
"suffix"
optional - use other suffixes than the defaultEn
,Se
andCo
for the three different images"infix"
used to identify all images related to region. In this example, it will be pictures whose files names begin withG3A_..., G3B_..., G3C_..."
"labelPos"
optional - to add scenario name as label on map"colorSuffixLength"
identifies suffix length for region colourful frames. 0 is no color suffix (no colorisation), 1 is used forR, B, N, G, O, V, T, P
, value 2 is used forRe, Bl, Br, Gr, Or, Vi, Te, Pi
Packing campaign
After campaign scenarios and campaign description are ready, you should pack them into *.vcmp file. This file is a zip archive.
The scenarios should be named as in "map"
field from header. Subfolders are allowed.
Compatibility table
Version | Min VCMI | Max VCMI | Description |
---|---|---|---|
1 | 1.3 | Initial release |