1
0
mirror of https://github.com/vcmi/vcmi.git synced 2024-12-24 22:14:36 +02:00
vcmi/docs/modders/Campaign_Format.md

226 lines
9.6 KiB
Markdown
Raw Normal View History

2024-07-16 20:29:20 +02:00
# Campaign Format
## Introduction
2023-08-12 23:26:58 +02:00
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`)
2023-08-12 23:26:58 +02:00
2024-08-10 13:36:31 +02:00
To start making campaign, create file named `header.json`. See also [Packing campaign](#packing-campaign)
2023-08-12 23:26:58 +02:00
Basic structure of this file is here, each section is described in details below
2023-08-12 23:26:58 +02:00
```js
{
"version" : 1,
<header properties>
"scenarios" : [
{
//scenario 1
<scenario properties>
},
{
//scenario 2
<scenario properties>
}
]
}
```
2023-09-01 00:30:26 +02:00
`"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)
2023-08-12 23:26:58 +02:00
2024-07-16 20:29:20 +02:00
## Header properties
2023-08-12 23:26:58 +02:00
In header are parameters describing campaign properties
2023-08-12 23:26:58 +02:00
```js
...
"regions": {...},
"name": "Campaign name",
"description": "Campaign description",
2024-06-29 14:01:25 +02:00
"author": "Author",
"authorContact": "Author contact",
"campaignVersion": "Campaign version",
"creationDateTime": "Creation date and time",
2023-08-12 23:26:58 +02:00
"allowDifficultySelection": true,
```
2023-09-01 00:30:26 +02:00
- `"regions"` contains information about background and regions. See section [campaign regions](#regions-description) for more information
2023-08-12 23:26:58 +02:00
- `"name"` is a human readable title of campaign
- `"description"` is a human readable description of campaign
2024-06-29 14:01:25 +02:00
- `"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
2023-08-12 23:26:58 +02:00
- `"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
2024-08-31 17:57:27 +02:00
- `"introVideo"` is for defining an optional intro video
2024-09-05 21:32:44 +02:00
- `"outroVideo"` is for defining an optional outro video
2024-09-05 21:31:17 +02:00
- `"videoRim"` is for the Rim around the optional video (default is INTRORIM)
2023-08-12 23:26:58 +02:00
2024-07-16 20:29:20 +02:00
## Scenario description
2023-08-12 23:26:58 +02:00
Scenario description looks like follow:
2023-08-12 23:26:58 +02:00
```js
{
"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)
2023-08-12 23:26:58 +02:00
- `"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
2023-09-01 00:30:26 +02:00
- `"prolog"`/`"epilog"` optional, defines prolog/epilog for scenario. See [prolog/epilog](#prologepilog) section for more information
2023-08-12 23:26:58 +02:00
- `"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"`
2023-09-01 00:30:26 +02:00
- `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)
2023-08-12 23:26:58 +02:00
- `"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
2024-07-16 20:29:20 +02:00
### Prolog/Epilog
2023-08-12 23:26:58 +02:00
Prolog and epilog properties are optional
2023-08-12 23:26:58 +02:00
```js
{
"video": "NEUTRALA.smk", //video to show
"music": "musicFile.ogg", //music to play, should be located in music directory
2023-09-18 13:03:43 +02:00
"voice": "musicFile.wav", //voice to play, should be located in sounds directory
2023-08-12 23:26:58 +02:00
"text": "some long text" //text to be shown
}
```
2024-07-16 20:29:20 +02:00
### Start options and bonuses
2023-08-12 23:26:58 +02:00
2024-07-16 20:29:20 +02:00
#### None start option
2023-08-12 23:26:58 +02:00
If `startOptions` is `none`, `bonuses` field will be ignored
2024-07-16 20:29:20 +02:00
#### Bonus start option
2023-08-12 23:26:58 +02:00
If `startOptions` is `bonus`, bonus format may vary depending on its type.
```js
{
"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`
2024-07-16 20:29:20 +02:00
#### Crossover start option
2023-08-12 23:26:58 +02:00
If `startOptions` is `crossover`, heroes from specific scenario will be moved to this scenario. Bonus format is following
```js
{
"playerColor": 0,
"scenario": 0
},
```
2023-08-12 23:26:58 +02:00
- `"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
2024-07-16 20:29:20 +02:00
#### Hero start option
2023-08-12 23:26:58 +02:00
If `startOptions` is `hero`, hero can be chosen as a starting bonus. Bonus format is following
2023-08-12 23:26:58 +02:00
```js
{
"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`
2024-07-16 20:29:20 +02:00
### Regions description
2023-08-12 23:26:58 +02:00
Predefined campaign regions are located in file `campaign_regions.json`
```js
{
2024-08-12 17:57:34 +02:00
"background": "ownRegionBackground.png",
2024-08-12 00:01:09 +02:00
"suffix": ["Enabled", "Selected", "Conquered"],
2023-08-12 23:26:58 +02:00
"prefix": "G3",
2024-08-12 17:57:34 +02:00
"colorSuffixLength": 1,
2023-08-12 23:26:58 +02:00
"desc": [
2024-09-24 11:23:10 +02:00
{ "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 } }
2023-08-12 23:26:58 +02:00
]
},
```
2024-08-12 00:01:09 +02:00
- `"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_..."`
2024-09-24 11:23:10 +02:00
- `"labelPos"` optional - to add scenario name as label on map
2024-08-12 17:57:34 +02:00
- `"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`
2023-08-12 23:26:58 +02:00
2024-07-16 20:29:20 +02:00
## Packing campaign
2023-08-12 23:26:58 +02:00
After campaign scenarios and campaign description are ready, you should pack them into *.vcmp file.
2024-08-10 13:36:31 +02:00
This file is a zip archive.
2023-08-12 23:26:58 +02:00
2024-08-10 13:36:31 +02:00
The scenarios should be named as in `"map"` field from header. Subfolders are allowed.
2023-08-12 23:26:58 +02:00
2024-07-16 20:29:20 +02:00
## Compatibility table
2023-08-12 23:26:58 +02:00
| Version | Min VCMI | Max VCMI | Description |
|---------|----------|----------|-------------|
| 1 | 1.3 | | Initial release |