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