Missions.wiki
author nemo
Thu, 27 Jan 2022 17:26:11 -0500
changeset 2219 12e5f8732e54
parent 2073 f02fee463bf9
permissions -rw-r--r--
latest on 1.0.0 branch is better
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
566
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
     1
#summary How to create singleplayer missions
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
     2
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
     3
= Missions =
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
     4
== Introduction ==
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
     5
Missions can be played in singleplayer mode and are selected from the single player menu in the mission menu (the hedgehog at the blackboard).
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
     6
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
     7
== Mission files ==
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
     8
Only the Lua script is needed, the other files/data are optional. But it is still recommended to create them.
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
     9
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    10
=== The mission's Lua script ===
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    11
This is the heart of your mission. Here you will set up the mission and define the entire game logic of the mission.
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    12
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    13
See [LuaGuide], [LuaAPI] and [LuaLibraries] for more information about scripting.
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    14
1686
ad2641650d35 Missions: Add mission type
Wuzzy
parents: 1685
diff changeset
    15
This file needs to be saved in `Data/Missions/<MISSION TYPE>`, with `<MISSION TYPE>` being one of `Training`, `Challenge` or `Scenario`. The file name must end with “`.lua`”. Remember the file name, you will need it for the other files.
ad2641650d35 Missions: Add mission type
Wuzzy
parents: 1685
diff changeset
    16
ad2641650d35 Missions: Add mission type
Wuzzy
parents: 1685
diff changeset
    17
These are the mission types:
ad2641650d35 Missions: Add mission type
Wuzzy
parents: 1685
diff changeset
    18
ad2641650d35 Missions: Add mission type
Wuzzy
parents: 1685
diff changeset
    19
 * Training: Tutorial-like mission that teaches the player a skill or is for practice. You can't lose
ad2641650d35 Missions: Add mission type
Wuzzy
parents: 1685
diff changeset
    20
 * Challenge: Player must master a particular skill in order to reach a high score
ad2641650d35 Missions: Add mission type
Wuzzy
parents: 1685
diff changeset
    21
 * Scenario: Player has to complete a predefined goal
566
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    22
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    23
==== Hints ====
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    24
In mission scripting, some patterns appear often, so here are some hints for your convenience (Refer to [LuaAPI] for a full documentation):
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    25
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    26
 * Start with `onGameInit` to set up the most basic environment parameters, teams, hedgehogs, etc.
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    27
 * Important set up functions: `AddTeam`, `AddHog`, `AddGear`, `SetGearPosition`.
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    28
 * You probably almost always want to call `ShowMission` at the beginning of the game (`onGameStart`) to show the objectives of your mission.
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    29
 * Enable the game flag `gfOneClanMode` if you need only one clan for your mission.
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    30
 * Normally, the game ends when all hedgehogs are dead or one clan is remaining (unless `gfOneClanMode` is set). You can call `EndGame` to end the game manually.
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    31
 * Call `SendStat` to customize the statistics screen.
1684
a15513ab7e2b Missions: update link
Wuzzy
parents: 566
diff changeset
    32
 * Use the [LuaLibraryLocale Locale] library to make your mission translatable.
566
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    33
 * When making your mission translatable, use Lua's `string.format` to insert numbers and other strings instead of just concatenating everything together.
1685
2e6f3bfcb26b Missions: anim lib
Wuzzy
parents: 1684
diff changeset
    34
 * If you want to create complex animations and/or cinematics, include and use the [LuaLibraryAnimate Animate] library.
566
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    35
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    36
=== Preview image ===
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    37
The preview image is displayed in the mission menu when you have selected the mission.
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    38
It must be a PNG image of size 314px×260px.
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    39
1686
ad2641650d35 Missions: Add mission type
Wuzzy
parents: 1685
diff changeset
    40
The file must be saved in `Data/Graphics/Missions/<MISSION TYPE>`. The file name must follow this pattern:
566
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    41
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    42
`<mission name>@2x.png`
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    43
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    44
Where `<mission name>` is name of the mission script without the file name suffix.
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    45
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    46
For example, the preview image for the mission script `User_Mission_-_Teamwork.lua` must have the name `User_Mission_-_Teamwork@2x.png`.
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    47
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    48
=== Mission title and description ===
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    49
The mission title and its description as shown in the mission menu must be edited in the missions files in `Data/Locale`. The file name is `missions_<language code>.txt`. There is one file per language. I.e. `missions_en.txt` for English, `missions_de.txt` for German, etc. Note that these files are supposed to contain the titles and descriptions of *all* missions on your computer. This makes these files unsuitable for sharing or inclusion into [HWPFormat HWP files], for example.
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    50
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    51
To add the title an description for your mission, just add these 2 lines into the file according to this syntax:
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    52
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    53
{{{
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    54
<mission name>.name=<mission title>
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    55
<mission name>.desc=<mission description>
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    56
}}}
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    57
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    58
 * `<mission name>` is the file name of the mission script without the file suffix.
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    59
 * `<mission title>` is the mission title as shown in the mission menu.
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    60
 * `<mission description>` is a short description of the mission, also only shown in the mission menu.
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    61
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    62
You can optionally enclose `<mission title>` and `<mission description>` in quotation marks (they will be removed by the game).
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    63
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    64
If the mission title and description are missing, the mission menu will derive the title from the file name of the Lua script instead and shows no description.
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    65
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    66
For more information about translating Hedgewars, see [Translations].
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    67
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    68
==== Example ====
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    69
Here are the English title and description of the mission “Bamboo Thicket” (file name of script: “`User_Mission_-_Bamboo_Thicket.lua`”):
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    70
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    71
{{{
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    72
User_Mission_-_Bamboo_Thicket.name=Mission: Bamboo Thicket
dc9a1250fe28 Created how-to guide about singleplayer missions.
almikes@aol.com
parents:
diff changeset
    73
User_Mission_-_Bamboo_Thicket.desc="Death comes from above."
2073
f02fee463bf9 Missions: mission vars
Wuzzy
parents: 1686
diff changeset
    74
}}}
f02fee463bf9 Missions: mission vars
Wuzzy
parents: 1686
diff changeset
    75
f02fee463bf9 Missions: mission vars
Wuzzy
parents: 1686
diff changeset
    76
== Mission variables ==
f02fee463bf9 Missions: mission vars
Wuzzy
parents: 1686
diff changeset
    77
Mission variables are used to store arbitrary values about the mission in the team file. Most commonly, victory and highscores are saved here. Mission variables are set and read with `SaveMissionVariable` and `GetMissionVariable`.
f02fee463bf9 Missions: mission vars
Wuzzy
parents: 1686
diff changeset
    78
f02fee463bf9 Missions: mission vars
Wuzzy
parents: 1686
diff changeset
    79
To mark a mission as won, call `SaveMissionVariable("Won", "true"). For challenge missions, you can also use mission variables to store highscores.
f02fee463bf9 Missions: mission vars
Wuzzy
parents: 1686
diff changeset
    80
f02fee463bf9 Missions: mission vars
Wuzzy
parents: 1686
diff changeset
    81
For a complete list, see [ConfigurationFiles].