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>
|
1354
|
26 |
Mandatory fields:
|
|
27 |
- teams: Table of teams. There must be 1-8 teams.
|
|
28 |
|
|
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
|
|
36 |
|
|
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)
|
|
43 |
|
|
44 |
TEAM DATA
|
|
45 |
- hogs table of hedgehogs in this team (must contain at least 1 hog)
|
|
46 |
- name team name
|
|
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 |
- flag flag name (default: hedgewars)
|
|
52 |
- grave grave name (has default grave for each team)
|
|
53 |
- fort fort name (default: Castle)
|
|
54 |
|
|
55 |
HEDGEHOG DATA:
|
|
56 |
- id optional identifier for goals
|
|
57 |
- name hog name
|
|
58 |
- x, y hog position (default: spawns randomly on land)
|
|
59 |
- botLevel 1-5: Bot level (lower=stronger). 0=human player (default: 0)
|
|
60 |
- hat hat name (default: NoHat)
|
|
61 |
- health hog health (default: 100)
|
|
62 |
- poisoned if true, hedgehog starts poisoned with 5 poison damage. Set to a number for other poison damage (default: false)
|
|
63 |
- frozen if true, hedgehogs starts frozen (default: false)
|
|
64 |
- faceLeft initial facing direction. true=left, false=false (default: false)
|
|
65 |
- ammo table of ammo types
|
|
66 |
|
|
67 |
GEAR TYPES:
|
|
68 |
- type gear type
|
|
69 |
ALL types:
|
|
70 |
id optional identifier for goals
|
|
71 |
x x coordinate of starting position (default: 0)
|
|
72 |
y y coordinate of starting position (default: 0)
|
|
73 |
dx initial x speed (default: 0)
|
|
74 |
dy initial y speed (default: 0)
|
|
75 |
- type=gtMine Mine
|
|
76 |
timer Mine timer (only for non-duds). Default: MinesTime
|
|
77 |
isDud Whether the mine is a dud. default: false
|
|
78 |
isFrozen Whether the mine is frozen. If true, it implies being a dud as well. Default: false
|
|
79 |
health Initial health of dud mines. Has no effect if isDud=false. Default: 36
|
|
80 |
- type=gtSMine Sticky mine
|
|
81 |
timer Timer. Default: 500
|
|
82 |
- type=gtAirMine Air mine
|
|
83 |
timer Timer. Default: (MinesTime/1000 * 250)
|
|
84 |
- type=gtExplosives Barrel
|
|
85 |
health Initial health. Default: 60
|
|
86 |
isFrozen Whether the barrel is frozen. Default: true with health > 60, false otherwise
|
|
87 |
isRolling Whether the barrel starts in “rolling” state. Default: false
|
|
88 |
- type=gtCase Crate
|
|
89 |
crateType "health": Health crate
|
|
90 |
"supply": Ammo or utility crate (select crate type automatically)
|
|
91 |
"supply_ammo_explicit": Ammo crate (not recommened)
|
|
92 |
"supply_utility_explicit": Utility crate (not recommededn)
|
|
93 |
ammoType Contained ammo (only for ammo and utility crates).
|
|
94 |
health Contained health (only for health crates). Default: HealthCaseAmount
|
|
95 |
isFrozen Whether the crate is frozen. Default: false
|
|
96 |
- type=gtKnife Cleaver
|
|
97 |
- type=gtTarget Target
|
|
98 |
|
|
99 |
GOALS:
|
|
100 |
Note: If there are at least two opposing teams, a default goal is used, which is to defeat all the enemies of the
|
|
101 |
player's team. If this is what you want, you can skip this section.
|
|
102 |
|
|
103 |
The default goal is overwritten as if customGoals has been set. Set customGoals and other related parameters for
|
|
104 |
defining your own special goals. In this case, the mission is won if all customGoals are completed.
|
|
105 |
Note the mission will always fail if the player's hedgehogs and all their allies have been defeated.
|
|
106 |
If there is only one team (for the player), there is no default goal and one must be set explicitly.
|
|
107 |
- customGoals Table of custom goals (see below). All of them must be met to win. Some goal types might fail,
|
|
108 |
rendering the mission unwinnable and leading to the loss of the mission. An example is
|
|
109 |
blowing up a crate which you should have collected.ed.
|
|
110 |
- customNonGoals Table of non-goals, the player loses if one of them is achieved
|
|
111 |
- customGoalCheck When to check goals and non-goals. Values: "instant" (default), "turnStart", "turnEnd"
|
|
112 |
|
|
113 |
- missionTitle: The name of the mission (highly recommended)
|
|
114 |
- missionIcon: Icon of the mission panel, see documentation of ShowMission in the Lua API
|
|
115 |
- goalText: A short string explaining the goal of the mission (use this if you set custom goals).
|
|
116 |
|
|
117 |
GOAL TYPES:
|
|
118 |
- type name of goal type
|
|
119 |
- failText Optional. For non-goals, this text will be shown in the stats if mission fails due to this non-goal
|
|
120 |
being completed. For goals which fail, this text will be displayed at failure. Note that
|
|
121 |
all normal goals have sensible default fail texts.
|
|
122 |
- type="destroy" Gear must be destroyed
|
|
123 |
- id Gear to destroy
|
|
124 |
- type="teamDefeat" Team must be defeated
|
|
125 |
- teamName Name of team to defeat
|
|
126 |
- type="collect" Crate must be collected
|
|
127 |
FAIL CONDITION: Crate taken by enemy, or destroyed
|
|
128 |
- id ID of crate gear to collect
|
|
129 |
- collectors Optional table of gear IDs, any one of which must collect the gear (but nobody else!).
|
|
130 |
By default, this is for the player's teams and allies.
|
|
131 |
- type="turns" Achieved when a number of turns has been played
|
|
132 |
- turns Number of played turns
|
|
133 |
- type="rounds" Achieved when a number of rounds has been played
|
|
134 |
- rounds Number of played rounds
|
|
135 |
- type="suddenDeath" Sudden Death has started
|
|
136 |
- type="inZone" A gear is within given coordinate bounds. Each of xMin, xMax, yMin and yMax is a sub-goal.
|
|
137 |
Each sub-goal is only checked if not nil.
|
|
138 |
You can use this to check if a gear left, right, above or below a given coordinate.
|
|
139 |
To check if the gear is within a rectangle, just set all 4 sub-goals.
|
|
140 |
FAIL CONDITION: Gear destroyed
|
|
141 |
- id Gear to watch
|
|
142 |
- xMin gear's X coordinate must be lower than this
|
|
143 |
- xMax gear's X coordinate must be higher than this
|
|
144 |
- yMin gear's Y coordinate must be lower than this
|
|
145 |
- yMax gear's Y coordinate must be higher than this
|
|
146 |
- type="distGearPos" Distance between a gear and a fixed position
|
|
147 |
FAIL CONDITION: Gear destroyed
|
|
148 |
- distance goal distance to compare to
|
|
149 |
- relationship "greaterThan" or "lowerThan"
|
|
150 |
- id gear to watch
|
|
151 |
- x x coordinate to reach
|
|
152 |
- y y coordinate to reach
|
|
153 |
- type="distGearGear" Distance between two gears
|
|
154 |
FAIL CONDITION: Any of both gears destroyed
|
|
155 |
- distance goal distance to compare to
|
|
156 |
- relationship "greaterThan" or "lowerThan"
|
|
157 |
- id1 first gear to compare
|
|
158 |
- id2 second gear to compare
|
|
159 |
- type="damage" Gear took damage or was destroyed
|
|
160 |
- id Gear to watch
|
|
161 |
- damage Minimum amount of damage to take at a single blow. Default: 1
|
|
162 |
- canDestroy If false, this goal will fail if the gear was destroyed without taking the required damage
|
|
163 |
- type="drown" Gear has drowned
|
|
164 |
FAIL CONDITION: Gear destroyed by other means
|
|
165 |
- id Gear to watch
|
|
166 |
- type="poison" Gear must be poisoned
|
|
167 |
FAIL CONDITION: Gear destroyed
|
|
168 |
- id Gear to be poisoned
|
|
169 |
- type="cure" Gear must exist and be free from poisoning
|
|
170 |
FAIL CONDITION: Gear destroyed
|
|
171 |
- id Gear to check
|
|
172 |
- type="freeze" Gear must exist and be frozen
|
|
173 |
FAIL CONDITION: Gear destroyed
|
|
174 |
- id Gear to be frozen
|
|
175 |
- type="melt" Gear must exist and be unfrozen
|
|
176 |
FAIL CONDITION: Gear destroyed
|
|
177 |
- id Gear to check
|
|
178 |
- type="waterSkip" Gear must have skipped over water
|
|
179 |
FAIL CONDITION: Gear destroyed before it reached the required number of skips
|
|
180 |
- id
|
|
181 |
- skips Total number of water skips required at least (default: 1)
|
1355
|
182 |
</code>
|
1354
|
183 |
|
1356
|
184 |
Source: https://hg.hedgewars.org/hedgewars/raw-file/tip/share/hedgewars/Data/Scripts/SimpleMission.lua
|
|
185 |
|
1354
|
186 |
=== Examples ===
|
1356
|
187 |
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.
|