|
1 #Summary List of gear-related functions in the Lua API |
|
2 |
|
3 = Lua API: Gear functions = |
|
4 This is a list of all functions in the [LuaAPI Lua API] that are related to gears. Refer to [LuaGuide] for an introduction into gears. |
|
5 |
|
6 == Functions for creating gears == |
|
7 |
|
8 === <tt>!AddGear(x, y, gearType, state, dx, dy, timer)</tt> === |
|
9 This creates a new gear at position x,y (measured from top left) of kind `gearType` (see [GearTypes Gear Types]). Gears are dynamic objects or events in the world that affect the gameplay, including hedgehogs, projectiles, weapons, land objects, active utilities and a few more esoteric things. |
|
10 The initial velocities are `dx` and `dy`. All arguments are numbers. The function returns the `uid` of the gear created. Gears can have multple states at once: `state` is a bitmask, the flag variables can be found in [States]. |
|
11 |
|
12 Example: |
|
13 |
|
14 <code language="lua"> local gear = AddGear(0, 0, gtTarget, 0, 0, 0, 0) |
|
15 FindPlace(gear, true, 0, LAND_WIDTH)</code> |
|
16 |
|
17 === <tt>!AddVisualGear(x, y, visualGearType, state, critical [, layer])</tt> === |
|
18 This attempts to create a new visual gear at position x,y (measured from top left) of kind `visualGearType` (see [VisualGearTypes Visual Gear Types]). Visual gears are decorational objects which are usually used for purely decorational graphical effects. They have no effect on gameplay. Visual gears are not the same as gears, but they share some similarities. |
|
19 |
|
20 The function returns the `uid` of the visual gear created or `nil` if creation failed. There is no guarantee that a visual gear will spawn. *IMPORTANT: Do not rely on visual gears to spawn*. *Always* be prepared for this function to return `nil`. |
|
21 |
|
22 Set `critical` to `true` if the visual gear is crucial to gameplay and must always be spawned when in-game. Use `false` if it is just an effect or eye-candy, and its creation can be skipped when in fast-forward mode (such as when joining a room). |
|
23 |
|
24 You can set an optional `layer` to specify which visual gears get drawn on top. |
|
25 |
|
26 Most visual gears delete themselves eventually. |
|
27 |
|
28 *NOTE:* Visual gears *must* only be used for decorational/informational/rendering purposes. *Never* use the visual gear's internal state to manipulate anything gameplay-related. Visual gears are not safe for reliable storage and using them as that would lead to strange bugs. |
|
29 |
|
30 *NOTE:* Since 0.9.25, visual gears will never spawn when Hedgewars is run in a testing mode (i.e. not as the real game), so don't rely for visual gears to spawn even if they're critical. |
|
31 |
|
32 Example: |
|
33 |
|
34 <code language="lua"> -- adds an non-critical explosion at position 1000,1000. Returns 0 if it was not created. |
|
35 local vgear = AddVisualGear(1000, 1000, vgtExplosion, 0, false) |
|
36 </code> |
|
37 |
|
38 === <tt>!SpawnHealthCrate(x, y, [, health])</tt> === |
|
39 Spawns a health crate at the specified position. If `x` and `y` are set to 0, the crate will spawn on a random position (but always on land). Set `health` for the initial health contained in the health crate. If not set, the default health (`HealthCaseAmount`) is used. Do not use a negative value for `health`. |
|
40 |
|
41 === <tt>!SpawnSupplyCrate(x, y, ammoType [, amount])</tt> (0.9.24) === |
|
42 Spawns an ammo or utility crate at the specified position with the given ammo type and an optional amount (default: 1). The crate type is chosen automatically based on the ammo type. |
|
43 Otherwise, this function behaves like `SpawnAmmoCrate`. |
|
44 |
|
45 === <tt>!SpawnAmmoCrate(x, y, ammoType [, amount])</tt> === |
|
46 Spawns an ammo crate at the specified position with content of `ammoType` (see [AmmoTypes Ammo Types]). Any `ammoType` is permitted, an ammo crate is spawned even if the ammo is normally defined as an utility. |
|
47 If `ammoType` is set to `amNothing`, a random weapon (out of the available weapons from the weapon scheme) will be selected. If `x` and `y` are set to 0, the crate will spawn on a random position (but always on land). The `amount` parameter specifies the amount of ammo contained in the crate. If `amount` is `nil` or `0`, the value set by `SetAmmo` is used, or if `SetAmmo` has not been used, it falls back to the weapon scheme's value. If `amount` is equal to or greater than `AMMO_INFINITE`, the amount is infinite. |
|
48 |
|
49 Note that in Lua missions, the default number of ammo in crates is 0, so it has to be set to at least 1 with `SetAmmo` first, see the example: |
|
50 |
|
51 Example: |
|
52 |
|
53 <code language="lua"> SetAmmo(amGrenade, 0, 0, 0, 1) -- grenade ammo crates now contain 1 grenade each |
|
54 SpawnAmmoCrate(0, 0, amGrenade) -- spawn grenade ammo crate at random position</code> |
|
55 |
|
56 === <tt>!SpawnUtilityCrate(x, y, ammoType [, amount])</tt> === |
|
57 Spawns an utility crate with some ammo at the specified position. The function behaves almost like `SpawnAmmoCrate`, the differences are 1) the crate looks different and 2) if `ammoType` is set to `amNothing`, a random utility out of the set of available utilities from the weapon scheme is chosen as content. |
|
58 |
|
59 Example: |
|
60 |
|
61 <code language="lua"> SetAmmo(amLaserSight, 0, 0, 0, 1) |
|
62 SpawnUtilityCrate(0, 0, amLaserSight)</code> |
|
63 |
|
64 === <tt>!SpawnFakeAmmoCrate(x, y, explode, poison) </tt> === |
|
65 Spawns a crate at the specified coordinates which looks exactly like a real ammo crate but contains not any ammo. It can be use useful for scripted events or to create a trap. If `x` and `y` are set to 0, the crate will spawn on a random position (but always on land). |
|
66 `explode` and `poison` are booleans. |
|
67 If `explode` is `true`, the crate will explode when collected. |
|
68 If `poison` is `true`, the collector will be poisoned. |
|
69 |
|
70 Example: |
|
71 |
|
72 <code language="lua">SpawnFakeAmmoCrate(500, 432, false, false) -- Spawns a fake ammo crate at the coordinates (500, 434) without explosion and poison. |
|
73 </code> |
|
74 |
|
75 === <tt>!SpawnFakeHealthCrate(x, y, explode, poison) </tt> === |
|
76 Same as `SpawnFakeAmmoCrate`, except the crate will look like a health crate. |
|
77 |
|
78 === <tt>!SpawnFakeUtilityCrate(x, y, explode, poison) </tt> === |
|
79 Same as `SpawnFakeAmmoCrate`, except the crate will look like an utility crate. |
|
80 |
|
81 === <tt>!AddHog(hogname, botlevel, health, hat)</tt> === |
|
82 Adds a new hedgehog for current team (last created one with the `AddTeam` function), with a bot level, an initial health and a hat. |
|
83 |
|
84 `botlevel` ranges from `0` to `5`, where `0` denotes a human player and `1` to `5` denote the skill level of a bot, where `1` is strongest and `5` is the weakest. Note that this is the reverse order of how the bot level is displayed in the game. Note that mixing human-controlled and computer-controlled hedgehogs in the same team is not permitted, but it is permitted to use different computer difficulty levels in the same team. |
|
85 |
|
86 Returns the gear ID. |
|
87 |
|
88 *Warning*: This only works in singleplayer mode (e.g. missions). Also, Hedgewars only supports up to 64 hedgehogs in a game. |
|
89 |
|
90 Example: |
|
91 |
|
92 <code language="lua"> local player = AddHog("HH 1", 0, 100, "NoHat") -- botlevel 0 means human player |
|
93 SetGearPosition(player, 1500, 1000) |
|
94 -- hint: If you don't call `SetGearPosition`, the hog spawns randomly</code> |
|
95 |
|
96 === <tt>!AddMissionHog(health)</tt> (0.9.25) === |
|
97 Add a hedgehog for the current team, using the player-chosen team identity when playing in singleplayer missions. The “current team” is the last team that was added with `AddMissionTeam` or `AddTeam`. |
|
98 |
|
99 The name and hat match the player's team definition. The hog is also always player-controlled. |
|
100 |
|
101 Examples: |
|
102 <code language="lua">-- Add player team with 3 hogs |
|
103 AddMissionTeam(-1) |
|
104 AddMissionHog(100) |
|
105 AddMissionHog(100) |
|
106 AddMissionHog(100)</code> |
|
107 |
|
108 <code language="lua">-- You can also mix mission hogs with “hardcoded” hogs. |
|
109 -- This adds a player team with 2 hogs taken from the player team and 1 hog with a hardcoded name, botlevel and hat. |
|
110 AddMissionTeam(-2) |
|
111 AddMissionHog(100) |
|
112 AddMissionHog(100) |
|
113 AddHog("My Hardcoded Hog", 0, 100, "NoHat") |
|
114 </code> |
|
115 |
|
116 == Functions to get gear properties == |
|
117 |
|
118 === <tt>!GetGearType(gearUid)</tt> === |
|
119 This function returns the [GearTypes gear type] for the specified gear, if it exists. If it doesn't exist, `nil` is returned. |
|
120 |
|
121 === <tt>!GetVisualGearType(vgUid)</tt> (0.9.23) === |
|
122 This function returns the [VisualGearTypes visual gear type] for the specified visual gear, if it exists. If it doesn't exist, `nil` is returned. |
|
123 |
|
124 === <tt>!GetGearPosition(gearUid)</tt> === |
|
125 Returns x,y coordinates for the specified gear. Not to be confused with `GetGearPos`. |
|
126 |
|
127 === <tt>GetGearCollisionMask(gearUid)</tt> === |
|
128 Returns the current collision mask of the given gear. See `SetGearCollisionMask` for an explanation of the mask. |
|
129 |
|
130 === <tt>!GetGearRadius(gearUid)</tt> === |
|
131 Returns the `Radius` value for the specified gear. For most [GearTypes gear types] for “projectile” gears (like `gtShell` or `gtGrenade`), the radius refers to the gear's collision radius. This is an invisible circle around the center of the gear which is used for the collision checks. For a few gear types, its radius means something different, see [GearTypes] for a full list. |
|
132 |
|
133 To set the `Radius` value, use `SetGearValues`. |
|
134 |
|
135 === <tt>!GetGearVelocity(gearUid)</tt> === |
|
136 Returns a tuple of dx,dy values for the specified gear. |
|
137 |
|
138 === <tt>!GetFlightTime(gearUid)</tt> === |
|
139 Returns the `FlightTime` of the specified gear. The `FlightTime` is a gear varialbe used to store a general time interval. The precise meaning of the `FlightTime` depends on the gear type. |
|
140 |
|
141 For example: The `FlightTime` of a hedgehog (`gtHedgehog`) is the time since they last have stood on solid ground. For most projectile gear types (i.e. `gtShell`), it stores the time after it has been launched. |
|
142 |
|
143 === <tt>!GetGearElasticity(gearUid) </tt> === |
|
144 Returns the elasticity of the specified gear. The elasticity normally determines how strong the gear will bounce after collisions, where higher elasticity is for stronger bounces. |
|
145 |
|
146 This is also useful for determining if a hog is on a rope or not. If a hog is attached to a rope, or is busy firing one, the elasticity of the rope will be a non-zero number. |
|
147 |
|
148 === <tt>!GetGearFriction(gearUid) </tt> === |
|
149 Returns the friction of the specified gear. The friction normally determines how well the gear will slide on terrain. Higher values are for increased sliding properties. |
|
150 |
|
151 === <tt>!GetHogClan(gearUid)</tt> === |
|
152 Returns the clan ID of the specified hedgehog gear. |
|
153 |
|
154 === <tt>!GetHogTeamName(gearUid)</tt> === |
|
155 Returns the name of the specified gear’s team. `gearUid` can be a hedgehog or a grave. |
|
156 |
|
157 === <tt>!GetHogName(gearUid)</tt> === |
|
158 Returns the name of the specified hedgehog gear. |
|
159 |
|
160 === <tt>!IsHogHidden(gearUid)</tt> (0.9.25) === |
|
161 Returns true if hedgehog gear is hidden (e.g. via `HideHog` or the !TimeBox), false if it isn't, nil if that hedgehog never existed. |
|
162 |
|
163 === <tt>!GetEffect(gearUid, effect)</tt> === |
|
164 Returns the state of given effect for the given hedgehog gear. |
|
165 |
|
166 See `SetEffect` for further details. |
|
167 |
|
168 === <tt>!GetHogHat(gearUid)</tt> === |
|
169 Returns the hat of the specified hedgehog gear. |
|
170 |
|
171 === <tt>!GetHogFlag(gearUid)</tt> === |
|
172 Returns the name of the flag of the team of the specified hedgehog gear. |
|
173 |
|
174 === <tt>!GetHogFort(gearUid)</tt> (0.9.23) === |
|
175 Returns the name of the fort of the team of the specified hedgehog gear. |
|
176 |
|
177 === <tt>!GetHogGrave(gearUid)</tt> === |
|
178 Returns the name of the grave of the team of the specified hedgehog gear. |
|
179 |
|
180 === <tt>!GetHogVoicepack(gearUid)</tt> === |
|
181 Returns the name of the voicepack of the team of the specified hedgehog gear. |
|
182 |
|
183 === <tt>!GetAmmoCount(gearUid, ammoType)</tt> === |
|
184 Returns the ammo count of the specified ammo type for the specified hedgehog gear. If infinite, returns `AMMO_INFINITE`. |
|
185 |
|
186 === <tt>!GetAmmoTimer(gearUid, ammoType)</tt> (0.9.25) === |
|
187 Returns the currently configured ammo timer (in milliseconds) for the given hedgehog gear and specified ammo type. This is the timer which is set by the player by using the timer keys (1-5). For ammo types for which the timer cannot be changed, `nil` is returned. |
|
188 |
|
189 Example: |
|
190 <code lang="lua">GetAmmoTimer(CurrentHedgehog, amGrenade) |
|
191 -- May return 1000, 2000, 3000, 4000 or 5000</code> |
|
192 |
|
193 === <tt>!IsHogLocal(gearUid)</tt> (0.9.23) === |
|
194 Returns `true` if the specified hedgehog gear is controlled by a human player on the computer on which Hedgewars runs on (i.e. not over a computer over the network). Also returns `true` if the hog is a member of any of the local clans. Returns `false` otherwise. Returns `nil` if `gearUid` is invalid. |
|
195 |
|
196 This is perfect to hide certain captions like weapon messages from enemy eyes. |
|
197 |
|
198 === <tt>!GetGearTarget(gearUid, x, y) </tt> === |
|
199 Returns the x and y coordinate of target-based weapons/utilities. |
|
200 <b>Note:</b>: This can’t be used in `onGearAdd()` but must be called after gear creation. |
|
201 |
|
202 === <tt>GetX(gearUid)</tt> === |
|
203 Returns x coordinate of the gear. |
|
204 |
|
205 === <tt>GetY(gearUid)</tt> === |
|
206 Returns y coordinate of the gear. |
|
207 |
|
208 === <tt>!GetState(gearUid)</tt> === |
|
209 Returns the state of the gear. The gear state is a bitmask which is built out of the variables as shown in [States]. |
|
210 |
|
211 This function is usually used in combination with `band` to extract the truth value of a single flag. It is also used together with `SetState` and `bor` in order to activate a single flag. |
|
212 |
|
213 Examples: |
|
214 <code language="lua"> |
|
215 local state = GetState(gear) |
|
216 --[[ Stores the full raw bitmask of gear in state. Usually |
|
217 useless on its own. ]] |
|
218 </code> |
|
219 |
|
220 <code language="lua"> |
|
221 isDrowning = band(GetState(CurrentHedgehog),gstDrowning) ~= 0 |
|
222 --[[ GetState(CurrentHedgehog) returns the state bitmask of |
|
223 CurrentHedgehog, gstDrowning is a bitmask where only the |
|
224 “drowning” bit is set. band does a bitwise AND on both, if |
|
225 it returns a non-zero value, the hedgehog is drowning.]] |
|
226 </code> |
|
227 |
|
228 <code language="lua"> |
|
229 SetState(CurrentHedgehog, bor(GetState(CurrentHedgehog), gstInvisible)) |
|
230 --[[ first the state bitmask of CurrentHedgehog is bitwise ORed with |
|
231 the gstInvisible flag, thus making the bit responsible for |
|
232 invisiblity to become 1. Then the new bitmask is applied to |
|
233 CurrentHedgehog, thus making it invisible.]] |
|
234 </code> |
|
235 |
|
236 |
|
237 === <tt>!GetGearMessage(gearUid)</tt> === |
|
238 Returns the message of the gear. This is a bitmask built out of flags seen in [GearMessages]. |
|
239 |
|
240 === <tt>!GetTag(gearUid)</tt> === |
|
241 Returns the tag of the specified gear (by `gearUid`). |
|
242 |
|
243 The `Tag` of a gear is just another arbitrary variable to hold the gear's state. The meaning of a tag depends on the gear type. For example, for `gtBall` gears, it specifies the ball color, for `gtAirAttack` gears (airplane) it specifies the direction of the plane, etc. See [GearTypes] for a full list. The returned value will be an integer. |
|
244 |
|
245 Note that the word “tag” here does _not_ refer to the name and health tags you see above hedgehogs, this is something different. |
|
246 |
|
247 <code language="lua"> |
|
248 -- This adds a ball (the one from the ballgun) at (123, 456): |
|
249 ball = AddGear(123, 456, gtBall, 0, 0, 0, 0) |
|
250 -- The tag of a ball defines its color. It will automatically chosen at random when created. |
|
251 colorTag = GetTag(ball) |
|
252 -- Now colorTag stores the tag of ball (in this case a number denoting its color) |
|
253 </code> |
|
254 |
|
255 The meaning of tags are described in [GearTypes]. |
|
256 |
|
257 === <tt>!GetFollowGear()</tt> === |
|
258 Returns the uid of the gear that is currently being followed. |
|
259 |
|
260 === <tt>!GetTimer(gearUid)</tt> === |
|
261 Returns the timer of the gear. This is for example the time it takes for watermelon, mine, etc. to explode. This is also the time used to specify the blowtorch or RC plane time. See [GearTypes] for a full list. |
|
262 |
|
263 === <tt>!GetHealth(gearUid)</tt> === |
|
264 Returns the health of the gear. Depending on the gear type, the gear's “health” can also refer to other things, see [GearTypes] for a full list. |
|
265 |
|
266 === <tt>!GetHogLevel(gearUid)</tt> === |
|
267 Returns the bot level ranging from `0` to `5`. `1` is the strongest bot level and `5` is the weakest one (this is the reverse of what players see). `0` is for human player. |
|
268 |
|
269 === <tt>!GetGearPos(gearUid)</tt> === |
|
270 Get the `Pos` value of the specified gear. `Pos` is just another arbitrary value to hold the state of the gear, such as `Tag` and `Health`, the meaning depends on the gear type. See [GearTypes] for the conrete meaning of a gear's `Pos` value. |
|
271 |
|
272 *Important*: Pos is *not* related to the gear's position, use `GetGearPosition` for that. |
|
273 |
|
274 === <tt>!GetGearValues(gearUid)</tt> === |
|
275 This returns a bunch of values associated with the gear, their meaning is often depending on the gear type and many values might be unused for certain gear types. |
|
276 |
|
277 This is returned (all variables are integers): |
|
278 |
|
279 `Angle, Power, WDTimer, Radius, Density, Karma, DirAngle, AdvBounce, ImpactSound, nImpactSounds, Tint, Damage, Boom` |
|
280 |
|
281 A rough description of some of the parameters: |
|
282 |
|
283 * `Radius`: Effect or collision radius, most of the time |
|
284 * `ImpactSound`: Sound it makes on a collision (see [Sounds]) |
|
285 * `Tint`: Used by some gear types to determine its colorization. The color is in RGBA format. |
|
286 * `Boom`: Used by most gears to determine the damage dealt. |
|
287 |
|
288 Example: |
|
289 <code language="lua"> |
|
290 -- Get all values in a single line of code: |
|
291 local Angle, Power, WDTimer, Radius, Density, Karma, DirAngle, AdvBounce, ImpactSound, nImpactSounds, Tint, Damage, Boom, Scale = GetGearValues(myGear) |
|
292 </code> |
|
293 |
|
294 === <tt>!GetVisualGearValues(vgUid)</tt> === |
|
295 This returns the typically set visual gear values for the specified visual gear `vgUid`, useful if manipulating things like smoke, bubbles or circles. On success, it returns the following values: |
|
296 |
|
297 `X, Y, dX, dY, Angle, Frame, FrameTicks, State, Timer, Tint, Scale` |
|
298 |
|
299 The meaning of these values is the same as in `SetVisualGearValues`. |
|
300 |
|
301 If the visual gear does not exist, `nil` is returned. Always check the result for `nil` before you plug in the values anywhere. |
|
302 |
|
303 Most visual gears require little to no modification of parameters. |
|
304 |
|
305 Example: |
|
306 |
|
307 <code language="lua">-- Return visual gear values |
|
308 local X, Y, dX, dY, Angle, Frame, FrameTicks, State, Timer, Tint, Scale = GetVisualGearValues(vgUid) |
|
309 </code> |
|
310 |
|
311 == Functions to modify gears == |
|
312 |
|
313 === <tt>!HideHog(gearUid)</tt> === |
|
314 Removes a hedgehog from the map. The hidden hedgehog can be restored with `RestoreHog(gearUid)`. Since 0.9.23, returns `true` on success and `false` on failure (if gear does not exist / hog is already hidden). |
|
315 |
|
316 Example: |
|
317 |
|
318 <code language="lua"> gear = AddGear(...) |
|
319 HideHog(gear) -- Hide the newly created gear.</code> |
|
320 |
|
321 === <tt>!RestoreHog(gearUid)</tt> === |
|
322 Restores a previously hidden hedgehog. Nothing happens if the hedgehog does not exist or is not hidden. |
|
323 |
|
324 Example: |
|
325 |
|
326 <code language="lua"> gear = AddGear(...) |
|
327 HideHog(gear) -- Hide the newly created gear. |
|
328 RestoreHog(gear) -- Restore the newly hidden gear.</code> |
|
329 |
|
330 === <tt>!DeleteGear(gearUid)</tt> === |
|
331 Deletes a gear. If the specified gear did not exist, nothing happens. |
|
332 |
|
333 Example: |
|
334 |
|
335 <code language="lua"> gear = AddGear(...) |
|
336 DeleteGear(gear) -- Delete the newly created gear.</code> |
|
337 |
|
338 === <tt>!DeleteVisualGear(vgUid)</tt> === |
|
339 Deletes a visual gear. If it does not exist, nothing happens. |
|
340 |
|
341 Note, most visual gears delete themselves after a while. |
|
342 |
|
343 |
|
344 |
|
345 Example: |
|
346 |
|
347 <code language="lua"> vgear = AddVisualGear(...) |
|
348 DeleteVisualGear(vgear) -- Delete the newly created visual gear.</code> |
|
349 |
|
350 === <tt>!SetGearValues(gearUid, Angle, Power, WDTimer, Radius, Density, Karma, DirAngle, AdvBounce, ImpactSound, ImpactSounds, Tint, Damage, Boom)</tt> === |
|
351 Sets various gear value for the specified gear (`gearUid`). The meaining of each value often depends on the gear type. See the documentation on !GetGearValues for a brief description of the gear values. If `gearUid` is invalid or the gear does not exist, nothing happens. |
|
352 |
|
353 Set `nil` for each value you do not want to change. |
|
354 |
|
355 Example: |
|
356 <code language="lua"> |
|
357 -- Paints all RC planes into a white color |
|
358 function onGearAdd(gear) |
|
359 if GetGearType(gear) == gtRCPlane then |
|
360 SetGearValues(gear, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, 0xFFFFFFFF) |
|
361 end |
|
362 end |
|
363 </code> |
|
364 |
|
365 === <tt>!SetVisualGearValues(vgUid, X, Y, dX, dY, Angle, Frame, !FrameTicks, State, Timer, Tint, Scale)</tt> === |
|
366 This allows manipulation of the internal state of the visual gear `vgUid`. If `vgUid` is invalid or the `vgUid` does not refer to an existing visual gear, the function does nothing. Thus, you can safely call this function even if you are not sure if the visual gear actually exists. |
|
367 |
|
368 All visual gear values are numbers. Each visual gear may be using these parameters differently, but the *usual* meaning of these is the following: |
|
369 |
|
370 * `X`, `Y`: Position |
|
371 * `dX`, `dY`: Speed along the X and Y axis |
|
372 * `Angle`: Current rotation |
|
373 * `Frame`: Image frame, if using a sprite sheet |
|
374 * `FrameTicks` is usually an animation counter |
|
375 * `State`: Helper value to save some internal state |
|
376 * `Timer`: Time in milliseconds until it expires |
|
377 * `Tint`: RGBA color |
|
378 * `Scale` is a scale factor (not used by all visual gears) |
|
379 |
|
380 Some visual gears interpret these values differently, just like normal gears. See [VisualGearTypes] for details. Also, most visual gears are not using all possible values, while some values are just ignored. |
|
381 |
|
382 Note that most visual gears require little to no modification of their values. |
|
383 |
|
384 *NOTE*: *Never* use the visual gear's internal state to manipulate/store anything gameplay-related. Visual gears are not safe for reliable storage and using them as that would lead to strange bugs. |
|
385 |
|
386 Example 1: |
|
387 |
|
388 <code language="lua"> -- set a circle to position 1000,1000 pulsing from opacity 20 to 200 (8%-78%), radius of 50, 3px thickness, bright red. |
|
389 SetVisualGearValues(circleUid, 1000,1000, 20, 200, 0, 0, 100, 50, 3, 0xff0000ff)</code> |
|
390 |
|
391 Only the first argument is required. Everything else is optional. Any such argument which is declared as `nil` will not overwrite the corresponding value of the visual gear. |
|
392 |
|
393 Example 2: |
|
394 |
|
395 <code language="lua"> -- set a visual gear to position 1000,1000 |
|
396 SetVisualGearValues(circleUid, 1000, 1000)</code> |
|
397 <code language="lua"> -- set the tint of a visual gear to bright red. |
|
398 SetVisualGearValues(circleUid, nil, nil, nil, nil, nil, nil, nil, nil, nil, 0xff0000ff)</code> |
|
399 |
|
400 |
|
401 === <tt>!FindPlace(gearUid, fall, left, right[, tryHarder])</tt> === |
|
402 Finds a place for the specified gear between x=`left` and x=`right` and places it there. `tryHarder` is optional, setting it to `true`/`false` will determine whether the engine attempts to make additional passes, even attempting to place gears on top of each other. |
|
403 |
|
404 Example: |
|
405 |
|
406 <code language="lua"> gear = AddGear(...) |
|
407 FindPlace(gear, true, 0, LAND_WIDTH) -- places the gear randomly between 0 and LAND_WIDTH</code> |
|
408 === <tt>HogSay(gearUid, text, manner [,vgState])</tt> === |
|
409 Makes the specified gear say, think, or shout some text in a comic-style speech or thought bubble. `gearUid` is _not_ limited to hedgehogs, altough the function name suggests otherwise. |
|
410 |
|
411 The `manner` parameter specifies the type of the bubble and can have one of these values: |
|
412 |
|
413 || *Value of `manner`* || *Looks* || |
|
414 || `SAY_THINK` || Thought bubble || |
|
415 || `SAY_SAY` || Speech bubble || |
|
416 || `SAY_SHOUT` || Exclamatory bubble (denotes shouting) || |
|
417 |
|
418 There is a optional 4th parameter `vgState`, it defines wheather the speechbubble is drawn fully opaque or semi-transparent. The value `0` is the default value. |
|
419 |
|
420 || *Value of `vgState`* || *Effect* || |
|
421 || `0` || If the specified gear is a hedgehog, and it’s the turn of the hedgehog’s team, the bubble is drawn fully opaque.<br>If the gear is a hedgehog, and it’s another team’s turn, the bubble is drawn translucent.<br>If the gear is not a hedgehog, the bubble is drawn fully opaque. || |
|
422 || `1` || The bubble is drawn translucent. || |
|
423 || `2` || The bubble is drawn fully opaque. || |
|
424 |
|
425 Examples: |
|
426 |
|
427 <code language="lua">HogSay(CurrentHedgehog, "I wonder what to do …", SAY_THINK) -- thought bubble with text “I wonder what to do …”</code> |
|
428 <code language="lua">HogSay(CurrentHedgehog, "I'm hungry.", SAY_SAY) -- speech bubble with text “I’m hungry.”</code> |
|
429 <code language="lua">HogSay(CurrentHedgehog, "I smell CAKE!", SAY_SHOUT) -- exclamatory bubble with text “I smell CAKE!”</code> |
|
430 === <tt>!HogTurnLeft(gearUid, boolean)</tt> === |
|
431 Faces the specified hog left or right. |
|
432 |
|
433 Example: |
|
434 |
|
435 <code language="lua"> HogTurnLeft(CurrentHedgehog, true) -- turns CurrentHedgehog left |
|
436 HogTurnLeft(CurrentHedgehog, false) -- turns CurrentHedgehog right</code> |
|
437 === <tt>!SetGearPosition(gearUid, x, y)</tt> === |
|
438 Places the specified gear exactly at the position (`x`,`y`). Not to be confused with `SetGearPos`. |
|
439 |
|
440 === <tt>SetGearCollisionMask(gearUid, mask)</tt> === |
|
441 Set the collision mask of the given gear with `gearUid`. |
|
442 The collision mask defines with which gears and terrain types the gear can collide. |
|
443 |
|
444 `mask` is a number between `0x0000` and `0xFFFF` and used as a bitfield, which means you can combine these flags with `bor`. These are the available flags: |
|
445 |
|
446 || *Identifier* || *Collision with …* || |
|
447 || `lfLandMask` || Terrain || |
|
448 || `lfCurHogCrate` || Current hedgehog, and crates || |
|
449 || `lfHHMask` || Any hedgehogs || |
|
450 || `lfNotHHObjMask` || Objects, not hogs (e.g. mines, explosives) || |
|
451 || `lfAllObjMask` || Hedgehogs and objects || |
|
452 |
|
453 Beware, the collision mask is often set by the engine as well. |
|
454 |
|
455 Examples: |
|
456 <code language="lua">SetGearCollisionMask(gear, bnot(lfCurHogCrate)) |
|
457 -- Ignore collision with current hedgehog</code> |
|
458 |
|
459 <code language="lua">SetGearCollisionMask(gear, 0xFFFF) |
|
460 -- Collide with everything</code> |
|
461 |
|
462 <code language="lua">SetGearCollisionMask(gear, lfAllObjMask) |
|
463 -- Collide with hedgehogs and objects</code> |
|
464 |
|
465 <code language="lua">SetGearCollisionMask(gear, 0x0000) |
|
466 -- Collide with nothing</code> |
|
467 |
|
468 There are actual more flags availbable, but they are not as useful for use in Lua and their constants have not been exposed to Lua. You can find the full range of flags in the engine source code (in Pascal): |
|
469 |
|
470 [https://hg.hedgewars.org/hedgewars/file/default/hedgewars/uConsts.pas#l112] |
|
471 |
|
472 === <tt>!SetGearVelocity(gearUid, dx, dy)</tt> === |
|
473 Gives the specified gear the velocity of `dx`, `dy`. |
|
474 |
|
475 === <tt>!SetFlightTime(gearUid, flighttime)</tt> === |
|
476 Sets the `FlightTime` of the given gear to `flighttime`. The meaning of `FlightTime` is explained in the section `GetFlightTime`. |
|
477 |
|
478 === <tt>!SetGearElasticity(gearUid, Elasticity) </tt> === |
|
479 Sets the elasticity of the specified gear. For most gears, the elasticity determines how strong the gear will bounce after collisions, where higher elasticity is for stronger bounces. Recommended are values between `0` and `9999`. |
|
480 |
|
481 === <tt>!SetGearFriction(gearUid, Friction) </tt> === |
|
482 Sets the friction of the specified gear. The friction normally determines how well the gear will slide on terrain. Higher values are for increased sliding properties. `0` is for no sliding whatsoever, where `9999` is for very long slides, greater values are not recommended. |
|
483 |
|
484 === <tt>!SetHealth(gearUid, health)</tt> === |
|
485 Sets the health of the specified gear. The “health” of a gear can refer to many things, depending on the gear type. |
|
486 |
|
487 *Hint*: If you like to increase the health of a hedgehog with nice visual effects, consider using `HealHog` instead. |
|
488 |
|
489 Use cases: |
|
490 |
|
491 * Setting the health of a hedgehog (`gtHedgehog`) to 99 |
|
492 * Starting the RC Plane (`gtRCPlane`) with 10 bombs |
|
493 * Starting flying saucer (`gtJetpack`) with only 50% fuel |
|
494 * Setting all the mines (`gtMine`) to duds |
|
495 * And more! |
|
496 |
|
497 See [GearTypes] for a full description. |
|
498 |
|
499 <code language="lua"> function onGearAdd(gear) |
|
500 if (GetGearType(gear) == gtHedgehog) then |
|
501 -- Set hedgehog health to 99 |
|
502 SetHealth(gear, 99) |
|
503 end |
|
504 if (GetGearType(gear) == gtRCPlaane) then |
|
505 -- Give the plane 10 bombs |
|
506 SetHealth(gear, 10) |
|
507 end |
|
508 if (GetGearType(gear) == gtJetpack) then |
|
509 -- Set fuel to 50% only |
|
510 SetHealth(gear, 1000) |
|
511 end |
|
512 if (GetGearType(gear) == gtMine) then |
|
513 -- Turn mine into dud |
|
514 SetHealth(gear, 0) |
|
515 end |
|
516 end</code> |
|
517 |
|
518 === <tt>HealHog(gearUid, healthBoost[, showMessage[, tint]])</tt> (0.9.24) === |
|
519 Convenience function to increase the health of a hedgehog with default visual effects. |
|
520 |
|
521 Specifically, this increases the health of the hedgehog gear with the given ID `gearUid` by `healthBoost`, displays some healing particles at the hedgehog and shows the health increae as a message. This is similar to the behavour after taking a health crate, or getting a health boost from vampirism. |
|
522 |
|
523 If `showMessage` is false, no message is shown. With `tint` you can set the RGBA color of the particles (default: `0x00FF00FF`). |
|
524 |
|
525 This function does not affect the poison state, however (see `SetEffect`). |
|
526 |
|
527 === <tt>!SetEffect(gearUid, effect, effectState)</tt> === |
|
528 Sets the state for one of the effects <tt>heInvulnerable, heResurrectable, hePoisoned, heResurrected, heFrozen</tt> for the specified hedgehog gear. |
|
529 A value of 0 usually means the effect is disabled, values other than that indicate that it is enabled and in some cases specify e.g. the remaining time of that effect. |
|
530 |
|
531 || *`effect`* || *Description* || *`effectState`* || |
|
532 || `heInvulnerable` || Wether hog is invulnerable || Any non-zero value turns on invulnerability. `0` turns it off. || |
|
533 || `hePoisoned` || Poison damage, damages hog each turn. || Amount of damage per turn. Use `0` to disable poisoning. || |
|
534 || `heResurrectable` || Whether to resurrect the hog on death || With a non-zero value, the hedgehog will be resurrected and teleported to a random location on death. `0` disables this. || |
|
535 || `heResurrected` || Whether the hedgehog has been resurrected once. This is only a subtle graphical effect. || With a non-zero value, the hedgehog was resurrected, `0` otherwise. || |
|
536 || `heFrozen` || Freeze level. Frozen hedgehogs skip turn, are heavy and take half damage || The hog is considered frozen if the value is `256` or higher, otherwise not. A number of `256` or higher denotes “how frozen” the hedgehog is, i.e. how long it takes to melt. The freezer sets this to `199999` initially. The value will be reduced by `50000` each round. Being hit by a flame reduces this number by `1000`. The values `0` to `255` are used for the freeze/melt animations. || |
|
537 || `heArtillery` || If enabled, the hedgehog can't walk (since 0.9.24). || `0` = disabled. `1` = permanently enabled. `2` = temporarily enabled (used by sniper rifle between shots) || |
|
538 |
|
539 Example (sets all bots poisoned with poison damage of 1): |
|
540 |
|
541 <code language="lua"> function onGearAdd(gear) |
|
542 if (GetGearType(gear) == gtHedgehog) and (GetHogLevel(gear) > 0) then |
|
543 SetEffect(gear, hePoisoned, 1) |
|
544 end |
|
545 end</code> |
|
546 |
|
547 === <tt>CopyPV(gearUid, gearUid)</tt> === |
|
548 This sets the position and velocity of the second gear to the first one. |
|
549 |
|
550 === <tt>!FollowGear(gearUid)</tt> === |
|
551 Makes the game client follow the specifiec gear (if it exists). Does not work for visual gears. |
|
552 |
|
553 === <tt>!SetHogName(gearUid, name)</tt> === |
|
554 Sets the name of the specified hedgehog gear. |
|
555 |
|
556 === <tt>!SetHogTeamName(gearUid, name)</tt> === |
|
557 Sets the team name of the specified gear. The gear can be a hedgehog or grave. |
|
558 |
|
559 === <tt>!SetHogHat(gearUid, hat)</tt> === |
|
560 Sets the hat of the specified hedgehog gear. |
|
561 |
|
562 === <tt>!SetGearTarget(gearUid, x, y)</tt> === |
|
563 Sets the x and y coordinate of target-based weapons/utilities. |
|
564 *Note*: This can’t be used in onGearAdd() but must be called after gear creation. |
|
565 |
|
566 === <tt>!SetState(gearUid, state)</tt> === |
|
567 Sets the state of the specified gear to the specified `state`. This is a bitmask made out of the variables as seen in [States]. |
|
568 |
|
569 This function is often used together with `GetState` and the bitmask utility functions `band` and `bnot` in order to manipulate a single flag. |
|
570 |
|
571 Examples: |
|
572 <code language="lua"> |
|
573 SetState(CurrentHedgehog, bor(GetState(CurrentHedgehog), gstInvisible)) |
|
574 --[[ first the state bitmask of CurrentHedgehog is bitwise ORed with |
|
575 the gstInvisible flag, thus making the bit responsible for |
|
576 invisiblity to become 1. Then the new bitmask is applied to |
|
577 CurrentHedgehog, thus making it invisible. ]] |
|
578 </code> |
|
579 |
|
580 <code language="lua"> |
|
581 SetState(CurrentHedgehog, band(GetState(CurrentHedgehog), bnot(gstInvisible))) |
|
582 --[[ The reverse of the above: This function toggles CurrentHedgehog’s |
|
583 gstInvisible flag off, thus making it visible again. ]] |
|
584 </code> |
|
585 |
|
586 === <tt>!SetGearMessage(gearUid, message)</tt> === |
|
587 Sets the gear messages of the specified gear. `message` is a bitmask built out of flags seen in [GearMessages]. |
|
588 |
|
589 === <tt>!SetTag(gearUid, tag)</tt> === |
|
590 Sets the `Tag` value of the specified gear (by `gearUid`). The `Tag` value of a gear is simply an extra variable to modify misc. things. The meaning of a tag depends on the gear type. For example, for `gtBall` gears, it specifies the ball color, for `gtAirAttack` gears (airplane) it specifies the direction of the plane, etc. See [GearTypes] for a full list. `tag` has to be an integer. |
|
591 |
|
592 Note that the word “tag” here does _not_ refer to the name and health tags you see above hedgehogs, this is something different. |
|
593 |
|
594 <code language="lua"> |
|
595 -- This adds a ball (the one from the ballgun) at (123, 456): |
|
596 ball = AddGear(123, 456, gtBall, 0, 0, 0, 0) |
|
597 -- This sets the tag of the gear. For gtBall, the tag specified the color. “8” is the color white. |
|
598 SetTag(ball, 8) -- |
|
599 </code> |
|
600 |
|
601 The meaning of tags are described in [GearTypes]. |
|
602 |
|
603 === <tt>!SetTimer(gearUid, timer)</tt> === |
|
604 Sets the timer of the specified gear. Also see `GetTimer`. |
|
605 |
|
606 === <tt>!SetHogLevel(gearUid, level)</tt> === |
|
607 Sets the bot level from 0 to 5. `1` is the strongest bot level and `5` is the weakest one (this is the reverse of what players see). `0` means human player. |
|
608 |
|
609 === <tt>SetGearAIHints(gearUid, aiHint)</tt> === |
|
610 Set some behaviour hints for computer-controlled hedgehogs for any given gear with `gearUid`. |
|
611 |
|
612 Set `aiHint` to either of: |
|
613 |
|
614 * `aihUsualProcessing`: AI hogs treat this gear the usual way. This is the default. |
|
615 * `aihDoesntMatter`: AI hogs don't bother attacking this gear intentionally. |
|
616 |
|
617 Example: |
|
618 |
|
619 <code language="lua"> |
|
620 SetGearAIHints(uselessHog, aihDoesntMatter) |
|
621 -- This makes AI hogs stop caring about attacking uselessHog</code> |
|
622 |
|
623 === <tt>!SetGearPos(gearUid, value)</tt> === |
|
624 Sets the `Pos` value (not the position!) of the specified gear to specified value. See `GetGearPos` for more information. |
|
625 |
|
626 |