Campaigns.wiki
author Wuzzy
Fri, 12 May 2023 14:37:17 +0000
changeset 2223 4e49d93377fd
parent 2101 a0a6ebfa2aab
permissions -rw-r--r--
LuaEvents: Rewrite onNewAmmoStore help
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
2070
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
     1
#summary How to create campaigns
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
     2
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
     3
= Campaigns =
2071
4580c5366698 Campaigns: add space
Wuzzy
parents: 2070
diff changeset
     4
2070
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
     5
== Introduction ==
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
     6
A campaign is a series of missions that tell a story. Campaigns are played in singleplayer mode only.
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
     7
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
     8
== Campaign files ==
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
     9
Campaigns are stored in `Data/Missions/Campaign/<CAMPAIGN NAME>`, with `<CAMPAIGN NAME>` being the campaign name.
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    10
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    11
In this directory, the following files are used:
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    12
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    13
 * `campaign.ini`: Campaign mission list
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    14
 * `*.lua`: A bunch of Lua scripts for the missions
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    15
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    16
=== `campaign.ini` ===
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    17
This is a file in the INI format. This lists the available missions.
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    18
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    19
 * No section:
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    20
  * `MissionNum`: Number of missions
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    21
  * `ResetRetry`: Unused
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    22
 * `[Mission X]`: Configuration for mission `X`, where X is the mission number. Mission 1 is the first mission.
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    23
  * `Name`: Human-readable mission name in English
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    24
  * `Script`: Name of Lua script file to load for this mission
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    25
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    26
=== The mission's Lua scripts ===
2072
72473075540c Campaigns: Mission vars
Wuzzy
parents: 2071
diff changeset
    27
There's one Lua script per mission. Scripting works basically like in singleplayer missons, see [Missions].
72473075540c Campaigns: Mission vars
Wuzzy
parents: 2071
diff changeset
    28
72473075540c Campaigns: Mission vars
Wuzzy
parents: 2071
diff changeset
    29
Exception: Campaign missions use campaign variables instead of mission variables to track progress.
2070
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    30
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    31
=== Preview image ===
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    32
The preview image is displayed in the menu when you have selected the mission.
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    33
It must be a PNG image of size 314px×260px.
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    34
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    35
The file must be saved in `Data/Graphics/Campaigns/<CAMPAIGN NAME>`. The file name must follow this pattern:
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    36
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    37
`<mission script name>@2x.png`
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    38
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    39
Where `<mission script name>` is name of the mission script without the file name suffix.
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    40
2101
a0a6ebfa2aab Campaigns: fix incorrect example
Wuzzy
parents: 2076
diff changeset
    41
For example, the preview image for the mission script `mission1.lua` must have the name `mission1@2x.png`.
2070
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    42
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    43
=== Localization ===
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    44
Campaign title, mission titles and mission descriptions menu must be edited in the missions files in `Data/Locale`. The file name is `campaigns_<language code>.txt`. There is one file per language. E.g. `campaigns_en.txt` for English. Note that these files are supposed to contain the titles and descriptions of *all* campaigns on your computer. This makes these files unsuitable for sharing or inclusion into [HWPFormat HWP files], for example.
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    45
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    46
This is the syntax:
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    47
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    48
{{{
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    49
<campaign dir name>.name="<campaign name>"
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    50
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    51
<campaign dir name>-<mission 1 script name>.name="<mission 1 name>"
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    52
<campaign dir name>-<mission 1 script name>.desc="<mission 1 description>"
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    53
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    54
<campaign dir name>-<mission 2 script name>.name="<mission 2 name>"
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    55
<campaign dir name>-<mission 2 script name>.desc="<mission 2 description>"
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    56
}}}
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    57
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    58
And so on.
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    59
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    60
 * `<campaign dir name>` is the directory name of the campaign. Replace spaces with underscores here.
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    61
 * `<campaign name>` is the human-readable campaign name.
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    62
 * `<mission x script name>` is the file name of the script of mission _x_ without file name suffix
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    63
 * `<mission x name>` is the human-readable name of mission _x_
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    64
 * `<mission x description>` is the description of mission _x_
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    65
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    66
If something is, the campaign menu will derive the title from the directory/file names instead and shows no description.
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    67
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    68
For more information about translating Hedgewars, see [Translations].
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    69
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    70
==== Example ====
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    71
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    72
Excerpt from `campaigns_en.txt`:
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    73
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    74
{{{
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    75
A_Classic_Fairytale.name="A Classic Fairytale"
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    76
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    77
A_Classic_Fairytale-first_blood.name="Mission 1: First Blood"
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    78
A_Classic_Fairytale-first_blood.desc="Help Leaks a Lot to complete his training and become a proper hedgehog warrior. You will be trained in the art of rope, parachute, shoryuken and desert eagle."
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    79
}}}
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    80
2075
05d4b420182a Campaigns: campaign variables
Wuzzy
parents: 2072
diff changeset
    81
== Campaign variables / campaign progress ==
05d4b420182a Campaigns: campaign variables
Wuzzy
parents: 2072
diff changeset
    82
Campaigns support campaign variables which allow to store arbitrary values about the campaign in the team file. Most importantly, the campaign progress is stored here. This uses the functions `SaveCampaignVar` and `GetCampaignVar`. Note that `SaveMissionVar` and `GetMissionVar` do *not* work in campaign missions.
05d4b420182a Campaigns: campaign variables
Wuzzy
parents: 2072
diff changeset
    83
05d4b420182a Campaigns: campaign variables
Wuzzy
parents: 2072
diff changeset
    84
Initially, only mission 1 is unlocked. To unlock more missions and to mark missions and the campaign as completed, you must set campaign variables. For linear campaigns, you can use this idiom:
2070
0705b1d3ed65 Add campaigns page
Wuzzy <almikes@aol.com>
parents:
diff changeset
    85
2075
05d4b420182a Campaigns: campaign variables
Wuzzy
parents: 2072
diff changeset
    86
{{{
05d4b420182a Campaigns: campaign variables
Wuzzy
parents: 2072
diff changeset
    87
-- To be called when mission 5 was won:
05d4b420182a Campaigns: campaign variables
Wuzzy
parents: 2072
diff changeset
    88
local progress = tonumber(GetCampaignVar("Progress"))
05d4b420182a Campaigns: campaign variables
Wuzzy
parents: 2072
diff changeset
    89
if progress == nil or progress < 5 then
05d4b420182a Campaigns: campaign variables
Wuzzy
parents: 2072
diff changeset
    90
    SaveCampaignVar("Progress", "5")
05d4b420182a Campaigns: campaign variables
Wuzzy
parents: 2072
diff changeset
    91
end
05d4b420182a Campaigns: campaign variables
Wuzzy
parents: 2072
diff changeset
    92
}}}
05d4b420182a Campaigns: campaign variables
Wuzzy
parents: 2072
diff changeset
    93
05d4b420182a Campaigns: campaign variables
Wuzzy
parents: 2072
diff changeset
    94
For non-linear campaigns, a more sophisticated unlocking is available.
05d4b420182a Campaigns: campaign variables
Wuzzy
parents: 2072
diff changeset
    95
05d4b420182a Campaigns: campaign variables
Wuzzy
parents: 2072
diff changeset
    96
Read [ConfigurationFiles] to learn how campaign variables work in detail.