1378
+ − 1
#summary Lua library documentation of !SimpleMission; for creating simple missions
1354
+ − 2
#labels !LuaLibrary
+ − 3
+ − 4
= Lua library: `SimpleMission` =
+ − 5
This is a simple library intended to make setting up simple missions an easy task for Lua scripters. The entire game logic and coding is abstracted away in a single function which you just need to feed a large definition table in which you define gears, goals, etc.
+ − 6
+ − 7
This is ideal for missions in which you set up the entire scenario from the start and don't need any complex in-mission events. BUT! This is *not* suited for missions with scripted events, cut-scenes, branching story, etc.
+ − 8
+ − 9
This library has the following features:
+ − 10
* Add teams, clans, hogs
+ − 11
* Spawn gears
+ − 12
* Sensible defaults for almost everything
+ − 13
* Set custom goals or use the default one (kill all enemies)
+ − 14
* Add non-goals to fail the mission
+ − 15
* Checks victory and failure automatically
+ − 16
+ − 17
To use this library, you first have to load it and to call `SimpleMission` once with the appropriate parameters.
+ − 18
+ − 19
== `SimpleMission(params)` ==
+ − 20
+ − 21
This function sets up the *entire* mission and needs one argument: params. The argument `params` is a table containing fields which describe the mission.
+ − 22
1357
+ − 23
This is the definition of the `params` table:
1356
+ − 24
1355
+ − 25
<code>
1933
+ − 26
Mandatory fields:
+ − 27
- teams: Table of teams. There must be 1-8 teams.
1354
+ − 28
1933
+ − 29
Optional fields
+ − 30
- ammoConfig Table containing basic ammo values (default: infinite skip only)
+ − 31
- initVars Table where you set up environment parameters such as MinesNum.
+ − 32
- wind If set, the wind will permanently set to this value (-100..100). Implies gfDisableWind
+ − 33
- gears: Table of objects.
+ − 34
- girders Table of girders
+ − 35
- rubbers Table of rubbers
1354
+ − 36
1933
+ − 37
AMMO
+ − 38
- ammoType ammo type
+ − 39
- delay delay (default: 0)
+ − 40
- numberInCrate ammo per crate (default: 1)
+ − 41
- count default starter ammo for everyone, 9 for infinite (default: 0)
+ − 42
- probability probability in crates (default: 0)
1354
+ − 43
1933
+ − 44
TEAM DATA
+ − 45
- isMissionTeam if true, this is the player's chosen team for this mission (default: false)
+ − 46
- hogs table of hedgehogs in this team (must contain at least 1 hog)
+ − 47
- clanID ID of the clan to which this team belongs to. Counting starts at 0.
+ − 48
By default, each team goes into its own clan.
+ − 49
Important: The clan of the player and allies MUST be 0.
+ − 50
Important: You MUST either set the clan ID explicitly for all teams or none of them.
+ − 51
These arguments will be ignored if this is a mission team:
+ − 52
- name team name
+ − 53
- flag flag name (default: hedgewars)
+ − 54
- grave grave name (has default grave for each team)
+ − 55
- fort fort name (default: Castle)
+ − 56
- voice voicepack (default: Default_qau)
1354
+ − 57
1933
+ − 58
HEDGEHOG DATA:
+ − 59
- id optional identifier for goals
+ − 60
- health hog health (default: 100)
+ − 61
- ammo table of ammo types
+ − 62
- x, y hog position (default: spawns randomly on land)
+ − 63
- poisoned if true, hedgehog starts poisoned with 5 poison damage. Set to a number for other poison damage (default: false)
+ − 64
- frozen if true, hedgehogs starts frozen (default: false)
+ − 65
- faceLeft initial facing direction. true=left, false=false (default: false)
+ − 66
These arguments will be ignored if the hog is in a mission team:
+ − 67
- name hog name
+ − 68
- botLevel 1-5: Bot level (lower=stronger). 0=human player (default: 0)
+ − 69
- hat hat name (default: NoHat)
1354
+ − 70
1933
+ − 71
GEAR TYPES:
+ − 72
- type gear type
+ − 73
ALL types:
+ − 74
id optional identifier for goals
+ − 75
x x coordinate of starting position (default: 0)
+ − 76
y y coordinate of starting position (default: 0)
+ − 77
dx initial x speed (default: 0)
+ − 78
dy initial y speed (default: 0)
+ − 79
- type=gtMine Mine
+ − 80
timer Mine timer (only for non-duds). Default: MinesTime
+ − 81
isDud Whether the mine is a dud. default: false
+ − 82
isFrozen Whether the mine is frozen. If true, it implies being a dud as well. Default: false
+ − 83
health Initial health of dud mines. Has no effect if isDud=false. Default: 36
+ − 84
- type=gtSMine Sticky mine
+ − 85
timer Timer. Default: 500
+ − 86
- type=gtAirMine Air mine
+ − 87
timer Timer. Default: (MinesTime/1000 * 250)
+ − 88
- type=gtExplosives Barrel
+ − 89
health Initial health. Default: 60
+ − 90
isFrozen Whether the barrel is frozen. Default: true with health > 60, false otherwise
+ − 91
isRolling Whether the barrel starts in “rolling” state. Default: false
+ − 92
- type=gtCase Crate
+ − 93
crateType "health": Health crate
+ − 94
"supply": Ammo or utility crate (select crate type automatically)
+ − 95
"supply_ammo_explicit": Ammo crate (not recommened)
+ − 96
"supply_utility_explicit": Utility crate (not recommededn)
+ − 97
ammoType Contained ammo (only for ammo and utility crates).
+ − 98
health Contained health (only for health crates). Default: HealthCaseAmount
+ − 99
isFrozen Whether the crate is frozen. Default: false
+ − 100
- type=gtKnife Cleaver
+ − 101
- type=gtTarget Target
1354
+ − 102
1933
+ − 103
GOALS:
+ − 104
Note: If there are at least two opposing teams, a default goal is used, which is to defeat all the enemies of the
+ − 105
player's team. If this is what you want, you can skip this section.
1354
+ − 106
1933
+ − 107
The default goal is overwritten as if customGoals has been set. Set customGoals and other related parameters for
+ − 108
defining your own special goals. In this case, the mission is won if all customGoals are completed.
+ − 109
Note the mission will always fail if the player's hedgehogs and all their allies have been defeated.
+ − 110
If there is only one team (for the player), there is no default goal and one must be set explicitly.
+ − 111
- customGoals Table of custom goals (see below). All of them must be met to win. Some goal types might fail,
+ − 112
rendering the mission unwinnable and leading to the loss of the mission. An example is
+ − 113
blowing up a crate which you should have collected.ed.
+ − 114
- customNonGoals Table of non-goals, the player loses if one of them is achieved
+ − 115
- customGoalCheck When to check goals and non-goals. Values: "instant" (default), "turnStart", "turnEnd"
1932
+ − 116
1933
+ − 117
- missionTitle: The name of the mission (highly recommended)
+ − 118
- missionIcon: Icon of the mission panel, see documentation of ShowMission in the Lua API
+ − 119
- goalText: A short string explaining the goal of the mission (use this if you set custom goals).
1354
+ − 120
1933
+ − 121
GOAL TYPES:
+ − 122
- type name of goal type
+ − 123
- failText Optional. For non-goals, this text will be shown in the stats if mission fails due to this non-goal
+ − 124
being completed. For goals which fail, this text will be displayed at failure. Note that
+ − 125
all normal goals have sensible default fail texts.
+ − 126
- type="destroy" Gear must be destroyed
+ − 127
- id Gear to destroy
+ − 128
- type="teamDefeat" Team must be defeated
+ − 129
- teamName Name of team to defeat
+ − 130
- type="collect" Crate must be collected
+ − 131
FAIL CONDITION: Crate taken by enemy, or destroyed
+ − 132
- id ID of crate gear to collect
+ − 133
- collectors Optional table of gear IDs, any one of which must collect the gear (but nobody else!).
+ − 134
By default, this is for the player's teams and allies.
+ − 135
- type="turns" Achieved when a number of turns has been played
+ − 136
- turns Number of played turns
+ − 137
- type="rounds" Achieved when a number of rounds has been played
+ − 138
- rounds Number of played rounds
+ − 139
- type="suddenDeath" Sudden Death has started
+ − 140
- type="inZone" A gear is within given coordinate bounds. Each of xMin, xMax, yMin and yMax is a sub-goal.
+ − 141
Each sub-goal is only checked if not nil.
+ − 142
You can use this to check if a gear left, right, above or below a given coordinate.
+ − 143
To check if the gear is within a rectangle, just set all 4 sub-goals.
+ − 144
FAIL CONDITION: Gear destroyed
+ − 145
- id Gear to watch
+ − 146
- xMin gear's X coordinate must be lower than this
+ − 147
- xMax gear's X coordinate must be higher than this
+ − 148
- yMin gear's Y coordinate must be lower than this
+ − 149
- yMax gear's Y coordinate must be higher than this
+ − 150
- type="distGearPos" Distance between a gear and a fixed position
+ − 151
FAIL CONDITION: Gear destroyed
+ − 152
- distance goal distance to compare to
+ − 153
- relationship "greaterThan" or "smallerThan"
+ − 154
- id gear to watch
+ − 155
- x x coordinate to reach
+ − 156
- y y coordinate to reach
+ − 157
- type="distGearGear" Distance between two gears
+ − 158
FAIL CONDITION: Any of both gears destroyed
+ − 159
- distance goal distance to compare to
+ − 160
- relationship "greaterThan" or "smallerThan"
+ − 161
- id1 first gear to compare
+ − 162
- id2 second gear to compare
+ − 163
- type="damage" Gear took damage or was destroyed
+ − 164
- id Gear to watch
+ − 165
- damage Minimum amount of damage to take at a single blow. Default: 1
+ − 166
- canDestroy If false, this goal will fail if the gear was destroyed without taking the required damage
+ − 167
- type="drown" Gear has drowned
+ − 168
FAIL CONDITION: Gear destroyed by other means
+ − 169
- id Gear to watch
+ − 170
- type="poison" Gear must be poisoned
+ − 171
FAIL CONDITION: Gear destroyed
+ − 172
- id Gear to be poisoned
+ − 173
- type="cure" Gear must exist and be free from poisoning
+ − 174
FAIL CONDITION: Gear destroyed
+ − 175
- id Gear to check
+ − 176
- type="freeze" Gear must exist and be frozen
+ − 177
FAIL CONDITION: Gear destroyed
+ − 178
- id Gear to be frozen
+ − 179
- type="melt" Gear must exist and be unfrozen
+ − 180
FAIL CONDITION: Gear destroyed
+ − 181
- id Gear to check
+ − 182
- type="waterSkip" Gear must have skipped over water
+ − 183
FAIL CONDITION: Gear destroyed before it reached the required number of skips
+ − 184
- id
1932
+ − 185
- skips Total number of water skips required at least (default: 1)
1355
+ − 186
</code>
1354
+ − 187
1356
+ − 188
Source: https://hg.hedgewars.org/hedgewars/raw-file/tip/share/hedgewars/Data/Scripts/SimpleMission.lua
+ − 189
1354
+ − 190
=== Examples ===
1356
+ − 191
A couple of scenarios are using `SimpleMission`. Look into `Data/Missions/Scenarios` of your Hedgewars installation. Check out the [https://hg.hedgewars.org/hedgewars/raw-file/tip/share/hedgewars/Data/Missions/Scenario/Bazooka_Battlefield.lua source code of the mission “Bazooka Battlefield”] for a typical mission created with this library.