You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: doc/AddingCustomCampaign.md
+33-28Lines changed: 33 additions & 28 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,17 +11,16 @@ We will now create an example campaign `garden`.
11
11
12
12
## Location for adding a new campaign
13
13
14
-
To add a new custom campaign you have to create a new subfolder with your campaign name under `RTTR/campaigns/` in the install directory or under `<RTTR_USERDATA>/campaigns/`.
15
-
`<RTTR_USERDATA>` is the placeholder for the RttR folder in your user dir, e.g. `~/.s25rttr` on Linux or "Saved Games" on Windows.
14
+
To add a new custom campaign you have to create a new subfolder with your campaign name under `RTTR/campaigns/` in the installation directory or under `<RTTR_USERDATA>/campaigns/`.
15
+
`<RTTR_USERDATA>` is the placeholder for the RttR folder in your user directory, e.g. `~/.s25rttr` on Linux or "Saved Games" on Windows.
16
16
This subfolder will be filled with all the needed data for the campaign.
17
17
We create the subfolder `RTTR/campaigns/garden` for our new example campaign.
18
18
19
-
20
19
## Lua campaign description file
21
20
22
21
First we have to add a `campaign.lua` file to our campaign folder `RTTR/campaigns/garden`. This file describes the settings and needed stuff for our new campaign `garden`.
23
22
24
-
```
23
+
```lua
25
24
functiongetRequiredLuaVersion()
26
25
return1
27
26
end
@@ -64,63 +63,70 @@ campaign = {
64
63
}
65
64
```
66
65
67
-
## Explaination of the semantic of the campaign.lua file
66
+
## Explanation of the semantic of the campaign Lua file
68
67
69
-
The `rttr:RegisterTranslations` function is used for the possibility of providing translation support for the texts displayed in the rttr campaign selection screen. If you do not want to provide any translation you can delete this function from the lua file and write your text directly in the specific fields below.
70
-
The `campaign` dict describes your campaign. The `getRequiredLuaVersion` function returns the version of the lua campaign interface.
68
+
The `rttr:RegisterTranslations` function is used for the possibility of providing translation support for the texts displayed in the RttR campaign selection screen.
69
+
If you do not want to provide any translation you can delete this function from the Lua file and write your text directly in the specific fields below.
70
+
The `campaign` dict describes your campaign. The `getRequiredLuaVersion` function returns the version of the Lua campaign interface.
71
71
72
72
### Versioning
73
73
74
-
The lua campaign interface is versioned using a major version. Everytime a feature is added or a breaking change is made (e.g. a function is removed or changes behavior considerably) the major version is increased.
74
+
The Lua campaign interface is versioned using a major version. Every time a feature is added, or a breaking change is made (e.g. a function is removed or changes behavior considerably) the major version is increased.
75
75
76
76
Every map script must have 1 function:
77
-
getRequiredLuaVersion()
77
+
`getRequiredLuaVersion()`
78
78
You need to implement this and return the version your script works with. If it does not match the current version an error will be shown and the script will not be used.
79
79
80
80
### Explanation of the campaign table fields
81
81
82
-
If you want a field to be translated you have to add the translation as described above and set the variable to _"<key>". The _"..." will translate the text during application execution depending on your language settings.
82
+
If you want a field to be translated you have to add the translation as described above and set the variable to `_"<key>"`. The `_"..."` will translate the text during application execution depending on your language settings.
83
83
84
84
1.`version`: Simple a number for versioning of the campaign
85
85
2.`author`: Human readable string of the campaign creator
86
86
3.`name`: The name of the campaign
87
-
4.`shortDescription`: Short description of the campaign (like a head line to get a rough imagination of the campaign)
87
+
4.`shortDescription`: Short description of the campaign (like a headline to get a rough imagination of the campaign)
88
88
5.`longDescription`: Extended description describing the campaign in detail. Will be shown in the campaign selection screen, when the campaign is selected.
89
89
6.`image`: Path to an image displayed in the campaign selection screen. You can omit this if you do no want to provide an image.
90
90
7.`maxHumanPlayers`: For now this is always 1 until we support multiplayer campaigns
91
-
8.`difficulty`: Difficulty of the campaign. Should be one of the valus easy, medium or hard.
92
-
9.`mapFolder` and `luaFolder`: Path to the folder containing the campaign maps and associated lua files. Usually your campaign folder or a subfolder of it.
93
-
10.`maps`: List of the names of the files of the campaigns mission maps
91
+
8.`difficulty`: Difficulty of the campaign. Should be one of the values easy, medium or hard.
92
+
9.`mapFolder` and `luaFolder`: Path to the folder containing the campaign maps and associated Lua files. Usually your campaign folder or a subfolder of it.
93
+
10.`maps`: List of the names of the files of the campaigns' mission maps
94
94
11.`selectionMap`: Optional parameter. See [map selection screen](#selection-map) for detailed explanations.
95
95
96
96
Hints:
97
-
- To work on case sensitive os (like linux) the file name of the lua file must have the same case as the map file name. This applies to the map names in the campaign.lua file too.
98
-
For example: `MISS01.WLD, MISS01.lua` is correct and `MISS01.WLD, miss01.lua` will not work on linux
99
-
- The lua file of a map must have the same name as the map itself but with the extension `.lua` to be found.
100
-
- The lua and the map file don't need to be in the same folder because the path can be specified separately.
101
-
- If `mapFolder` is not specified or empty it defaults to the folder containing the campaign lua file.
102
-
- If `luaFolder` is not specified it defaults to the `mapFolder`.
103
-
- Both paths can start with placeholders like `<RTTR_GAME>`, otherwise they need to be only the name of a folder relative to the folder containing the campaign lua file. I.e. multiple levels are not supported.
97
+
98
+
- To work on case-sensitive OS (like Linux) the file name of the Lua file must have the same case as the map file name. This applies to the map names in the campaign.lua file too.
99
+
For example: `MISS01.WLD, MISS01.lua` is correct and `MISS01.WLD, miss01.lua` will not work on Linux
100
+
- The Lua file of a map must have the same name as the map itself but with the extension `.lua` to be found.
101
+
- The Lua and the map file don't need to be in the same folder because the path can be specified separately.
102
+
- If `luaFolder` is not specified it defaults to the `mapFolder`, which defaults to an empty value.
103
+
- Both paths can start with placeholders like `<RTTR_GAME>`,
104
+
otherwise they must be (only) the name of a folder relative to the folder containing the campaign Lua file.
105
+
I.e. multiple levels are not supported.
106
+
In particular an empty value refers to the folder containing the campaign Lua file itself.
This parameter is optional and can be obmitted in the lua campaign file. If this parameter is specified the selection screen for the missions of a campaign is replaced by a selection map. Like the one used in the original settler 2 world campaign.
110
+
This parameter is optional and can be omitted in the Lua campaign file. If this parameter is specified the selection screen for the missions of a campaign is replaced by a selection map. Like the one used in the original settlers 2 world campaign.
108
111
109
112
We have the following parameters:
113
+
110
114
1.`background` background image for the selection map
111
115
2.`map` the map image itself
112
116
3.`missionMapMask` this image is a mask that describes the mission areas of the `map` image. It must be the same size as the `map` image where the color of each pixel determines the mission it belongs to. Each mission must have a unique color (specified in the `missionSelectionInfos`). Any other color is treated as neutral area and ignored.
113
117
4.`marker` the marker image shown when a mission is selected
114
118
5.`conquered` the image shown when a mission is already finished
115
119
6.`backgroundOffset` offset of the `map` image and `missionMapMask` image relative to the `background` image. Can be (0,0) if no offset exists.
116
120
7.`disabledColor` color for drawing missions not playable yet. Usually this should be a partly transparent color
117
-
8.`missionSelectionInfos` contains an entry for each mission and must be the same order as specified in `maps`lua parameter. Each entry consists of three elements. The first is the `maskAreaColor` and the two following are the `ankerPos` x and y position. The `ankerPos` is the position the `conquered` image and the `cursor` image, if mission is selected, are displayed for this mission. The offset is always counted from the origin of the `map` image. The `maskAreaColor` is the color for the mission used in the `missionMapMask`.
121
+
8.`missionSelectionInfos` contains an entry for each mission and must be the same order as specified in `maps`Lua parameter. Each entry consists of three elements. The first is the `maskAreaColor` and the two following are the `ankerPos` x and y position. The `ankerPos` is the position the `conquered` image and the `cursor` image, if mission is selected, are displayed for this mission. The offset is always counted from the origin of the `map` image. The `maskAreaColor` is the color for the mission used in the `missionMapMask`.
118
122
119
-
Hints:
120
-
- All the images are described by the path to the image file and an index parameter. Usually the index parameter is zero. For special image formats containing multiple images in an archive this is the index of the image to use.
123
+
Hint:
124
+
All the images are described by the path to the image file and an index parameter. Usually the index parameter is zero.
125
+
For special image formats containing multiple images in an archive this is the index of the image to use.
121
126
122
127
## Final view of the example garden campaign folder
0 commit comments