1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
|
# 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](#packing-campaign)
Basic structure of this file is here, each section is described in details below
```json
{
"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](#compatibility-table)
## Header properties
In header are parameters describing campaign properties
```json
...
"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](#regions-description) 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:
```json
{
"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](#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 are `0: 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 are `0: 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](#prologepilog) 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. [Description](#none-start-option)
- `bonus`: player chooses one of the predefined bonuses. [Description](#bonus-start-option)
- `crossover`: player will start with hero from previous scenario. [Description](#crossover-start-option)
- `hero` : player will start scenario with specified hero. [Description](#hero-start-option)
- `"playerColor"` defines color id of flag which player will play for. Possible values are `0: 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
```json
{
"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.
```json
{
"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 of `wood, ore, mercury, sulfur, crystal, gems, gold, common, rare`, where `common` 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
```json
{
"playerColor": 0,
"scenario": 0
},
```
- `"playerColor"` from what player color heroes shall be taken. Possible values are `0: 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
```json
{
"playerColor": 0,
"hero": "random"
}
```
- `"playerColor"` from what player color heroes shall be taken. Possible values are `0: 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`
```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 be `G3_BG`
- `"suffix"` optional - use other suffixes than the default `En`, `Se` and `Co` 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 with `G3A_..., 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 for `R, B, N, G, O, V, T, P`, value 2 is used for `Re, 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 |
|
