1 #summary List of gear-related functions in the Lua API |
1 #summary List of gear-related functions in the Lua API |
2 |
2 |
3 = Lua API: Gear functions = |
3 = Lua API: Gear functions = |
4 This is a list of all functions in the [LuaAPI Lua API] that are related to gears and visual gears. Refer to [LuaGuide] for an introduction into gears. |
4 This is a list of all functions in the [LuaAPI Lua API] that are related to gears and visual gears. |
|
5 |
|
6 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. 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. |
|
7 |
|
8 Refer to [LuaGuide] for a more detailed introduction into gears. |
5 |
9 |
6 <wiki:toc max_depth="3"/> |
10 <wiki:toc max_depth="3"/> |
7 |
11 |
8 == Functions for creating gears == |
12 == Creation == |
9 |
13 |
10 === `AddGear(x, y, gearType, state, dx, dy, timer)` === |
14 === `AddGear(x, y, gearType, state, dx, dy, timer)` === |
11 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. |
15 This creates a new gear at position x,y (measured from top left) of kind `gearType` (see [GearTypes Gear Types]). |
12 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]. |
16 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]. `timer` is the initial timer value of the gear. If a particular gear value does not matter, use `0`. |
13 |
17 |
14 Example: |
18 Position, velocity, state and timer can be changed afterwards with the various setter functions. |
15 |
19 |
16 <code language="lua"> local gear = AddGear(0, 0, gtTarget, 0, 0, 0, 0) |
20 Note: If you want to create a hedgehog (`gtHedgehog`), you must call `AddHog` or `AddMissionHog` instead. If you want to spawn a crate (`gtCase`), you must call one of the several “Spawn*Crate” functions (e.g. `SpawnSupplyCrate`) below instead. |
|
21 |
|
22 Example: |
|
23 |
|
24 <code language="lua"> -- Spawn a target at (0,0) and place it randomly |
|
25 local gear = AddGear(0, 0, gtTarget, 0, 0, 0, 0) -- also use 0 for velocity. Also 0 for state and timer because they don't matter. |
17 FindPlace(gear, true, 0, LAND_WIDTH)</code> |
26 FindPlace(gear, true, 0, LAND_WIDTH)</code> |
18 |
27 |
19 === `AddVisualGear(x, y, visualGearType, state, critical [, layer])` === |
28 === `AddVisualGear(x, y, visualGearType, state, critical [, layer])` === |
20 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. |
29 This attempts to create a new visual gear at position x,y (measured from top left) of kind `visualGearType` (see [VisualGearTypes Visual Gear Types]). |
21 |
30 |
22 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`. |
31 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`. |
23 |
32 |
24 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). |
33 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). |
25 |
34 |
113 Same as `SpawnFakeAmmoCrate`, except the crate will look like a health crate. |
122 Same as `SpawnFakeAmmoCrate`, except the crate will look like a health crate. |
114 |
123 |
115 === `SpawnFakeUtilityCrate(x, y, explode, poison) ` === |
124 === `SpawnFakeUtilityCrate(x, y, explode, poison) ` === |
116 Same as `SpawnFakeAmmoCrate`, except the crate will look like an utility crate. |
125 Same as `SpawnFakeAmmoCrate`, except the crate will look like an utility crate. |
117 |
126 |
118 == Functions to get gear properties == |
127 == Position and velocity == |
|
128 === `GetGearPosition(gearUid)` === |
|
129 Returns x,y coordinates for the specified gear. Not to be confused with `GetGearPos`. |
|
130 |
|
131 === `GetX(gearUid)` === |
|
132 Returns x coordinate of the gear. |
|
133 |
|
134 === `GetY(gearUid)` === |
|
135 Returns y coordinate of the gear. |
|
136 |
|
137 === `SetGearPosition(gearUid, x, y)` === |
|
138 Places the specified gear exactly at the position (`x`,`y`). Not to be confused with `SetGearPos`. |
|
139 |
|
140 === `GetGearVelocity(gearUid)` === |
|
141 Returns a tuple of dx,dy values for the specified gear. |
|
142 |
|
143 === `SetGearVelocity(gearUid, dx, dy)` === |
|
144 Gives the specified gear the velocity of `dx`, `dy`. |
|
145 |
|
146 === `CopyPV(gearUid, gearUid)` === |
|
147 This sets the position and velocity of the second gear to the first one. |
|
148 |
|
149 === `FindPlace(gearUid, fall, left, right[, tryHarder])` === |
|
150 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. |
|
151 |
|
152 Example: |
|
153 |
|
154 <code language="lua"> gear = AddGear(...) |
|
155 FindPlace(gear, true, 0, LAND_WIDTH) -- places the gear randomly between 0 and LAND_WIDTH</code> |
|
156 |
|
157 == General gear properties == |
119 |
158 |
120 === `GetGearType(gearUid)` === |
159 === `GetGearType(gearUid)` === |
121 This function returns the [GearTypes gear type] for the specified gear, if it exists. If it doesn't exist, `nil` is returned. |
160 This function returns the [GearTypes gear type] for the specified gear, if it exists. If it doesn't exist, `nil` is returned. |
122 |
161 |
123 === `GetVisualGearType(vgUid)` (0.9.23) === |
162 === `GetVisualGearType(vgUid)` (0.9.23) === |
124 This function returns the [VisualGearTypes visual gear type] for the specified visual gear, if it exists. If it doesn't exist, `nil` is returned. |
163 This function returns the [VisualGearTypes visual gear type] for the specified visual gear, if it exists. If it doesn't exist, `nil` is returned. |
125 |
|
126 === `GetGearPosition(gearUid)` === |
|
127 Returns x,y coordinates for the specified gear. Not to be confused with `GetGearPos`. |
|
128 |
|
129 === `GetGearCollisionMask(gearUid)` === |
|
130 Returns the current collision mask of the given gear. See `SetGearCollisionMask` for an explanation of the mask. |
|
131 |
|
132 === `GetGearRadius(gearUid)` === |
|
133 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. |
|
134 |
|
135 To set the `Radius` value, use `SetGearValues`. |
|
136 |
|
137 === `GetGearVelocity(gearUid)` === |
|
138 Returns a tuple of dx,dy values for the specified gear. |
|
139 |
|
140 === `GetFlightTime(gearUid)` === |
|
141 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. |
|
142 |
|
143 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. |
|
144 |
|
145 === `GetGearElasticity(gearUid) ` === |
|
146 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. |
|
147 |
|
148 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. |
|
149 |
|
150 === `GetGearFriction(gearUid) ` === |
|
151 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. |
|
152 |
|
153 === `GetHogClan(gearUid)` === |
|
154 Returns the clan ID of the specified hedgehog gear. |
|
155 |
|
156 === `GetHogTeamName(gearUid)` === |
|
157 Returns the name of the specified gear’s team. `gearUid` can be a hedgehog or a grave. |
|
158 |
|
159 === `GetHogName(gearUid)` === |
|
160 Returns the name of the specified hedgehog gear. |
|
161 |
|
162 === `IsHogHidden(gearUid)` (0.9.25) === |
|
163 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. |
|
164 |
|
165 === `GetEffect(gearUid, effect)` === |
|
166 Returns the state of given effect for the given hedgehog gear. |
|
167 |
|
168 See `SetEffect` for further details. |
|
169 |
|
170 === `GetHogHat(gearUid)` === |
|
171 Returns the hat of the specified hedgehog gear. |
|
172 |
|
173 === `GetHogFlag(gearUid)` === |
|
174 Returns the name of the flag of the team of the specified hedgehog gear. |
|
175 |
|
176 === `GetHogFort(gearUid)` (0.9.23) === |
|
177 Returns the name of the fort of the team of the specified hedgehog gear. |
|
178 |
|
179 === `GetHogGrave(gearUid)` === |
|
180 Returns the name of the grave of the team of the specified hedgehog gear. |
|
181 |
|
182 === `GetHogVoicepack(gearUid)` === |
|
183 Returns the name of the voicepack of the team of the specified hedgehog gear. |
|
184 |
|
185 === `GetAmmoCount(gearUid, ammoType)` === |
|
186 Returns the ammo count of the specified ammo type for the specified hedgehog gear. If infinite, returns `AMMO_INFINITE`. |
|
187 |
|
188 === `GetAmmoTimer(gearUid, ammoType)` (0.9.25) === |
|
189 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. |
|
190 |
|
191 Example: |
|
192 <code lang="lua">GetAmmoTimer(CurrentHedgehog, amGrenade) |
|
193 -- May return 1000, 2000, 3000, 4000 or 5000</code> |
|
194 |
|
195 === `IsHogLocal(gearUid)` (0.9.23) === |
|
196 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. |
|
197 |
|
198 This is perfect to hide certain captions like weapon messages from enemy eyes. |
|
199 |
|
200 === `GetGearTarget(gearUid, x, y) ` === |
|
201 Returns the x and y coordinate of target-based weapons/utilities. |
|
202 <b>Note:</b>: This can’t be used in `onGearAdd()` but must be called after gear creation. |
|
203 |
|
204 === `GetX(gearUid)` === |
|
205 Returns x coordinate of the gear. |
|
206 |
|
207 === `GetY(gearUid)` === |
|
208 Returns y coordinate of the gear. |
|
209 |
164 |
210 === `GetState(gearUid)` === |
165 === `GetState(gearUid)` === |
211 Returns the state of the gear. The gear state is a bitmask which is built out of the variables as shown in [States]. |
166 Returns the state of the gear. The gear state is a bitmask which is built out of the variables as shown in [States]. |
212 |
167 |
213 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. |
168 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. |
254 -- Now colorTag stores the tag of ball (in this case a number denoting its color) |
232 -- Now colorTag stores the tag of ball (in this case a number denoting its color) |
255 </code> |
233 </code> |
256 |
234 |
257 The meaning of tags are described in [GearTypes]. |
235 The meaning of tags are described in [GearTypes]. |
258 |
236 |
259 === `GetFollowGear()` === |
237 === `SetTag(gearUid, tag)` === |
260 Returns the uid of the gear that is currently being followed. |
238 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. |
|
239 |
|
240 Note that the word “tag” here does _not_ refer to the name and health tags you see above hedgehogs, this is something different. |
|
241 |
|
242 <code language="lua"> |
|
243 -- This adds a ball (the one from the ballgun) at (123, 456): |
|
244 ball = AddGear(123, 456, gtBall, 0, 0, 0, 0) |
|
245 -- This sets the tag of the gear. For gtBall, the tag specified the color. “8” is the color white. |
|
246 SetTag(ball, 8) -- |
|
247 </code> |
|
248 |
|
249 The meaning of tags are described in [GearTypes]. |
261 |
250 |
262 === `GetTimer(gearUid)` === |
251 === `GetTimer(gearUid)` === |
263 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. |
252 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. |
264 |
253 |
|
254 === `SetTimer(gearUid, timer)` === |
|
255 Sets the timer of the specified gear. Also see `GetTimer`. |
|
256 |
265 === `GetHealth(gearUid)` === |
257 === `GetHealth(gearUid)` === |
266 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. |
258 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. |
267 |
|
268 === `GetHogLevel(gearUid)` === |
|
269 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. |
|
270 |
|
271 === `GetGearPos(gearUid)` === |
|
272 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. |
|
273 |
|
274 *Important*: Pos is *not* related to the gear's position, use `GetGearPosition` for that. |
|
275 |
|
276 === `GetGearValues(gearUid)` === |
|
277 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. |
|
278 |
|
279 This is returned (all variables are integers): |
|
280 |
|
281 `Angle, Power, WDTimer, Radius, Density, Karma, DirAngle, AdvBounce, ImpactSound, nImpactSounds, Tint, Damage, Boom` |
|
282 |
|
283 A rough description of some of the parameters: |
|
284 |
|
285 * `Radius`: Effect or collision radius, most of the time |
|
286 * `ImpactSound`: Sound it makes on a collision (see [Sounds]) |
|
287 * `Tint`: Used by some gear types to determine its colorization. The color is in RGBA format. |
|
288 * `Boom`: Used by most gears to determine the damage dealt. |
|
289 |
|
290 Example: |
|
291 <code language="lua"> |
|
292 -- Get all values in a single line of code: |
|
293 local Angle, Power, WDTimer, Radius, Density, Karma, DirAngle, AdvBounce, ImpactSound, nImpactSounds, Tint, Damage, Boom, Scale = GetGearValues(myGear) |
|
294 </code> |
|
295 |
|
296 === `GetVisualGearValues(vgUid)` === |
|
297 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: |
|
298 |
|
299 `X, Y, dX, dY, Angle, Frame, FrameTicks, State, Timer, Tint, Scale` |
|
300 |
|
301 The meaning of these values is the same as in `SetVisualGearValues`. |
|
302 |
|
303 If the visual gear does not exist, `nil` is returned. Always check the result for `nil` before you plug in the values anywhere. |
|
304 |
|
305 Most visual gears require little to no modification of parameters. |
|
306 |
|
307 Example: |
|
308 |
|
309 <code language="lua">-- Return visual gear values |
|
310 local X, Y, dX, dY, Angle, Frame, FrameTicks, State, Timer, Tint, Scale = GetVisualGearValues(vgUid) |
|
311 </code> |
|
312 |
|
313 == Functions to change position and velocity == |
|
314 === `SetGearPosition(gearUid, x, y)` === |
|
315 Places the specified gear exactly at the position (`x`,`y`). Not to be confused with `SetGearPos`. |
|
316 |
|
317 === `SetGearVelocity(gearUid, dx, dy)` === |
|
318 Gives the specified gear the velocity of `dx`, `dy`. |
|
319 |
|
320 === `CopyPV(gearUid, gearUid)` === |
|
321 This sets the position and velocity of the second gear to the first one. |
|
322 |
|
323 === `FindPlace(gearUid, fall, left, right[, tryHarder])` === |
|
324 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. |
|
325 |
|
326 Example: |
|
327 |
|
328 <code language="lua"> gear = AddGear(...) |
|
329 FindPlace(gear, true, 0, LAND_WIDTH) -- places the gear randomly between 0 and LAND_WIDTH</code> |
|
330 |
|
331 == Functions to modify gears == |
|
332 === `SetGearValues(gearUid, Angle, Power, WDTimer, Radius, Density, Karma, DirAngle, AdvBounce, ImpactSound, ImpactSounds, Tint, Damage, Boom)` === |
|
333 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. |
|
334 |
|
335 Set `nil` for each value you do not want to change. |
|
336 |
|
337 Example: |
|
338 <code language="lua"> |
|
339 -- Paints all RC planes into a white color |
|
340 function onGearAdd(gear) |
|
341 if GetGearType(gear) == gtRCPlane then |
|
342 SetGearValues(gear, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, 0xFFFFFFFF) |
|
343 end |
|
344 end |
|
345 </code> |
|
346 |
|
347 === `SetVisualGearValues(vgUid, X, Y, dX, dY, Angle, Frame, !FrameTicks, State, Timer, Tint, Scale)` === |
|
348 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. |
|
349 |
|
350 All visual gear values are numbers. Each visual gear may be using these parameters differently, but the *usual* meaning of these is the following: |
|
351 |
|
352 * `X`, `Y`: Position |
|
353 * `dX`, `dY`: Speed along the X and Y axis |
|
354 * `Angle`: Current rotation |
|
355 * `Frame`: Image frame, if using a sprite sheet |
|
356 * `FrameTicks` is usually an animation counter |
|
357 * `State`: Helper value to save some internal state |
|
358 * `Timer`: Time in milliseconds until it expires |
|
359 * `Tint`: RGBA color |
|
360 * `Scale` is a scale factor (not used by all visual gears) |
|
361 |
|
362 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. |
|
363 |
|
364 Note that most visual gears require little to no modification of their values. |
|
365 |
|
366 *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. |
|
367 |
|
368 Example 1: |
|
369 |
|
370 <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. |
|
371 SetVisualGearValues(circleUid, 1000,1000, 20, 200, 0, 0, 100, 50, 3, 0xff0000ff)</code> |
|
372 |
|
373 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. |
|
374 |
|
375 Example 2: |
|
376 |
|
377 <code language="lua"> -- set a visual gear to position 1000,1000 |
|
378 SetVisualGearValues(circleUid, 1000, 1000)</code> |
|
379 <code language="lua"> -- set the tint of a visual gear to bright red. |
|
380 SetVisualGearValues(circleUid, nil, nil, nil, nil, nil, nil, nil, nil, nil, 0xff0000ff)</code> |
|
381 |
|
382 === `SetGearCollisionMask(gearUid, mask)` === |
|
383 Set the collision mask of the given gear with `gearUid`. |
|
384 The collision mask defines with which gears and terrain types the gear can collide. |
|
385 |
|
386 `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: |
|
387 |
|
388 || *Identifier* || *Collision with …* || |
|
389 || `lfLandMask` || Terrain || |
|
390 || `lfCurHogCrate` || Current hedgehog, and crates || |
|
391 || `lfHHMask` || Any hedgehogs || |
|
392 || `lfNotHHObjMask` || Objects, not hogs (e.g. mines, explosives) || |
|
393 || `lfAllObjMask` || Hedgehogs and objects || |
|
394 |
|
395 Beware, the collision mask is often set by the engine as well. |
|
396 |
|
397 Examples: |
|
398 <code language="lua">SetGearCollisionMask(gear, bnot(lfCurHogCrate)) |
|
399 -- Ignore collision with current hedgehog</code> |
|
400 |
|
401 <code language="lua">SetGearCollisionMask(gear, 0xFFFF) |
|
402 -- Collide with everything</code> |
|
403 |
|
404 <code language="lua">SetGearCollisionMask(gear, lfAllObjMask) |
|
405 -- Collide with hedgehogs and objects</code> |
|
406 |
|
407 <code language="lua">SetGearCollisionMask(gear, 0x0000) |
|
408 -- Collide with nothing</code> |
|
409 |
|
410 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): |
|
411 |
|
412 [https://hg.hedgewars.org/hedgewars/file/default/hedgewars/uConsts.pas#l112] |
|
413 |
|
414 === `SetFlightTime(gearUid, flighttime)` === |
|
415 Sets the `FlightTime` of the given gear to `flighttime`. The meaning of `FlightTime` is explained in the section `GetFlightTime`. |
|
416 |
|
417 === `SetGearElasticity(gearUid, Elasticity) ` === |
|
418 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`. |
|
419 |
|
420 === `SetGearFriction(gearUid, Friction) ` === |
|
421 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. |
|
422 |
259 |
423 === `SetHealth(gearUid, health)` === |
260 === `SetHealth(gearUid, health)` === |
424 Sets the health of the specified gear. The “health” of a gear can refer to many things, depending on the gear type. |
261 Sets the health of the specified gear. The “health” of a gear can refer to many things, depending on the gear type. |
425 |
262 |
426 *Hint*: If you like to increase the health of a hedgehog with nice visual effects, consider using `HealHog` instead. |
263 *Hint*: If you like to increase the health of a hedgehog with nice visual effects, consider using `HealHog` instead. |
452 -- Turn mine into dud |
289 -- Turn mine into dud |
453 SetHealth(gear, 0) |
290 SetHealth(gear, 0) |
454 end |
291 end |
455 end</code> |
292 end</code> |
456 |
293 |
457 === `HealHog(gearUid, healthBoost[, showMessage[, tint]])` (0.9.24) === |
294 |
458 Convenience function to increase the health of a hedgehog with default visual effects. |
295 === `GetGearPos(gearUid)` === |
459 |
296 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. |
460 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. |
297 |
461 |
298 *Important*: Pos is *not* related to the gear's position, use `GetGearPosition` for that. |
462 If `showMessage` is false, no message is shown. With `tint` you can set the RGBA color of the particles (default: `0x00FF00FF`). |
299 |
463 |
300 === `SetGearPos(gearUid, value)` === |
464 This function does not affect the poison state, however (see `SetEffect`). |
301 Sets the `Pos` value (not the position!) of the specified gear to specified value. See `GetGearPos` for more information. |
|
302 |
|
303 === `GetGearCollisionMask(gearUid)` === |
|
304 Returns the current collision mask of the given gear. See `SetGearCollisionMask` for an explanation of the mask. |
|
305 |
|
306 === `SetGearCollisionMask(gearUid, mask)` === |
|
307 Set the collision mask of the given gear with `gearUid`. |
|
308 The collision mask defines with which gears and terrain types the gear can collide. |
|
309 |
|
310 `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: |
|
311 |
|
312 || *Identifier* || *Collision with …* || |
|
313 || `lfLandMask` || Terrain || |
|
314 || `lfCurHogCrate` || Current hedgehog, and crates || |
|
315 || `lfHHMask` || Any hedgehogs || |
|
316 || `lfNotHHObjMask` || Objects, not hogs (e.g. mines, explosives) || |
|
317 || `lfAllObjMask` || Hedgehogs and objects || |
|
318 |
|
319 Beware, the collision mask is often set by the engine as well. |
|
320 |
|
321 Examples: |
|
322 <code language="lua">SetGearCollisionMask(gear, bnot(lfCurHogCrate)) |
|
323 -- Ignore collision with current hedgehog</code> |
|
324 |
|
325 <code language="lua">SetGearCollisionMask(gear, 0xFFFF) |
|
326 -- Collide with everything</code> |
|
327 |
|
328 <code language="lua">SetGearCollisionMask(gear, lfAllObjMask) |
|
329 -- Collide with hedgehogs and objects</code> |
|
330 |
|
331 <code language="lua">SetGearCollisionMask(gear, 0x0000) |
|
332 -- Collide with nothing</code> |
|
333 |
|
334 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): |
|
335 |
|
336 [https://hg.hedgewars.org/hedgewars/file/default/hedgewars/uConsts.pas#l112] |
|
337 |
|
338 === `GetGearRadius(gearUid)` === |
|
339 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. |
|
340 |
|
341 To set the `Radius` value, use `SetGearValues`. |
|
342 |
|
343 === `GetFlightTime(gearUid)` === |
|
344 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. |
|
345 |
|
346 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. |
|
347 |
|
348 === `SetFlightTime(gearUid, flighttime)` === |
|
349 Sets the `FlightTime` of the given gear to `flighttime`. The meaning of `FlightTime` is explained in the section `GetFlightTime`. |
|
350 |
|
351 === `GetGearElasticity(gearUid) ` === |
|
352 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. |
|
353 |
|
354 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. |
|
355 |
|
356 === `SetGearElasticity(gearUid, Elasticity) ` === |
|
357 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`. |
|
358 |
|
359 === `GetGearFriction(gearUid) ` === |
|
360 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. |
|
361 |
|
362 === `SetGearFriction(gearUid, Friction) ` === |
|
363 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. |
|
364 |
|
365 === `GetGearTarget(gearUid, x, y) ` === |
|
366 Returns the x and y coordinate of target-based weapons/utilities. |
|
367 <b>Note:</b>: This can’t be used in `onGearAdd()` but must be called after gear creation. |
|
368 |
|
369 === `SetGearTarget(gearUid, x, y)` === |
|
370 Sets the x and y coordinate of target-based weapons/utilities. |
|
371 *Note*: This can’t be used in onGearAdd() but must be called after gear creation. |
|
372 |
|
373 === `GetGearValues(gearUid)` === |
|
374 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. |
|
375 |
|
376 This is returned (all variables are integers): |
|
377 |
|
378 `Angle, Power, WDTimer, Radius, Density, Karma, DirAngle, AdvBounce, ImpactSound, nImpactSounds, Tint, Damage, Boom` |
|
379 |
|
380 A rough description of some of the parameters: |
|
381 |
|
382 * `Radius`: Effect or collision radius, most of the time |
|
383 * `ImpactSound`: Sound it makes on a collision (see [Sounds]) |
|
384 * `Tint`: Used by some gear types to determine its colorization. The color is in RGBA format. |
|
385 * `Boom`: Used by most gears to determine the damage dealt. |
|
386 |
|
387 Example: |
|
388 <code language="lua"> |
|
389 -- Get all values in a single line of code: |
|
390 local Angle, Power, WDTimer, Radius, Density, Karma, DirAngle, AdvBounce, ImpactSound, nImpactSounds, Tint, Damage, Boom, Scale = GetGearValues(myGear) |
|
391 </code> |
|
392 |
|
393 === `SetGearValues(gearUid, Angle, Power, WDTimer, Radius, Density, Karma, DirAngle, AdvBounce, ImpactSound, ImpactSounds, Tint, Damage, Boom)` === |
|
394 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. |
|
395 |
|
396 Set `nil` for each value you do not want to change. |
|
397 |
|
398 Example: |
|
399 <code language="lua"> |
|
400 -- Paints all RC planes into a white color |
|
401 function onGearAdd(gear) |
|
402 if GetGearType(gear) == gtRCPlane then |
|
403 SetGearValues(gear, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, 0xFFFFFFFF) |
|
404 end |
|
405 end |
|
406 </code> |
|
407 |
|
408 === `GetVisualGearValues(vgUid)` === |
|
409 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: |
|
410 |
|
411 `X, Y, dX, dY, Angle, Frame, FrameTicks, State, Timer, Tint, Scale` |
|
412 |
|
413 The meaning of these values is the same as in `SetVisualGearValues`. |
|
414 |
|
415 If the visual gear does not exist, `nil` is returned. Always check the result for `nil` before you plug in the values anywhere. |
|
416 |
|
417 Most visual gears require little to no modification of parameters. |
|
418 |
|
419 Example: |
|
420 |
|
421 <code language="lua">-- Return visual gear values |
|
422 local X, Y, dX, dY, Angle, Frame, FrameTicks, State, Timer, Tint, Scale = GetVisualGearValues(vgUid) |
|
423 </code> |
|
424 |
|
425 === `SetVisualGearValues(vgUid, X, Y, dX, dY, Angle, Frame, !FrameTicks, State, Timer, Tint, Scale)` === |
|
426 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. |
|
427 |
|
428 All visual gear values are numbers. Each visual gear may be using these parameters differently, but the *usual* meaning of these is the following: |
|
429 |
|
430 * `X`, `Y`: Position |
|
431 * `dX`, `dY`: Speed along the X and Y axis |
|
432 * `Angle`: Current rotation |
|
433 * `Frame`: Image frame, if using a sprite sheet |
|
434 * `FrameTicks` is usually an animation counter |
|
435 * `State`: Helper value to save some internal state |
|
436 * `Timer`: Time in milliseconds until it expires |
|
437 * `Tint`: RGBA color |
|
438 * `Scale` is a scale factor (not used by all visual gears) |
|
439 |
|
440 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. |
|
441 |
|
442 Note that most visual gears require little to no modification of their values. |
|
443 |
|
444 *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. |
|
445 |
|
446 Example 1: |
|
447 |
|
448 <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. |
|
449 SetVisualGearValues(circleUid, 1000,1000, 20, 200, 0, 0, 100, 50, 3, 0xff0000ff)</code> |
|
450 |
|
451 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. |
|
452 |
|
453 Example 2: |
|
454 |
|
455 <code language="lua"> -- set a visual gear to position 1000,1000 |
|
456 SetVisualGearValues(circleUid, 1000, 1000)</code> |
|
457 <code language="lua"> -- set the tint of a visual gear to bright red. |
|
458 SetVisualGearValues(circleUid, nil, nil, nil, nil, nil, nil, nil, nil, nil, 0xff0000ff)</code> |
|
459 |
|
460 === `SetGearAIHints(gearUid, aiHint)` === |
|
461 Set some behaviour hints for computer-controlled hedgehogs for any given gear with `gearUid`. |
|
462 |
|
463 Set `aiHint` to either of: |
|
464 |
|
465 * `aihUsualProcessing`: AI hogs treat this gear the usual way. This is the default. |
|
466 * `aihDoesntMatter`: AI hogs don't bother attacking this gear intentionally. |
|
467 |
|
468 Example: |
|
469 |
|
470 <code language="lua"> |
|
471 SetGearAIHints(uselessHog, aihDoesntMatter) |
|
472 -- This makes AI hogs stop caring about attacking uselessHog</code> |
|
473 |
|
474 == Hedgehog-specific gear properties == |
|
475 === `GetHogName(gearUid)` === |
|
476 Returns the name of the specified hedgehog gear. |
|
477 |
|
478 === `SetHogName(gearUid, name)` === |
|
479 Sets the name of the specified hedgehog gear. |
|
480 |
|
481 === `GetHogTeamName(gearUid)` === |
|
482 Returns the name of the specified gear’s team. `gearUid` can be a hedgehog or a grave. |
|
483 |
|
484 === `SetHogTeamName(gearUid, name)` === |
|
485 Sets the team name of the specified gear. The gear can be a hedgehog or grave. |
|
486 |
|
487 === `GetHogClan(gearUid)` === |
|
488 Returns the clan ID of the specified hedgehog gear. |
|
489 |
|
490 === `GetHogLevel(gearUid)` === |
|
491 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. |
|
492 |
|
493 === `SetHogLevel(gearUid, level)` === |
|
494 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. |
|
495 |
|
496 === `GetEffect(gearUid, effect)` === |
|
497 Returns the state of given effect for the given hedgehog gear. |
|
498 |
|
499 See `SetEffect` for further details. |
465 |
500 |
466 === `SetEffect(gearUid, effect, effectState)` === |
501 === `SetEffect(gearUid, effect, effectState)` === |
467 Sets the state for one of the effects `heInvulnerable, heResurrectable, hePoisoned, heResurrected, heFrozen` for the specified hedgehog gear. |
502 Sets the state for one of the effects `heInvulnerable, heResurrectable, hePoisoned, heResurrected, heFrozen` for the specified hedgehog gear. |
468 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. |
503 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. |
469 |
504 |
481 if (GetGearType(gear) == gtHedgehog) and (GetHogLevel(gear) > 0) then |
516 if (GetGearType(gear) == gtHedgehog) and (GetHogLevel(gear) > 0) then |
482 SetEffect(gear, hePoisoned, 1) |
517 SetEffect(gear, hePoisoned, 1) |
483 end |
518 end |
484 end</code> |
519 end</code> |
485 |
520 |
486 === `SetHogName(gearUid, name)` === |
521 === `GetHogHat(gearUid)` === |
487 Sets the name of the specified hedgehog gear. |
522 Returns the hat of the specified hedgehog gear. |
488 |
|
489 === `SetHogTeamName(gearUid, name)` === |
|
490 Sets the team name of the specified gear. The gear can be a hedgehog or grave. |
|
491 |
523 |
492 === `SetHogHat(gearUid, hat)` === |
524 === `SetHogHat(gearUid, hat)` === |
493 Sets the hat of the specified hedgehog gear. |
525 Sets the hat of the specified hedgehog gear. |
494 |
526 |
|
527 === `GetHogFlag(gearUid)` === |
|
528 Returns the name of the flag of the team of the specified hedgehog gear. |
|
529 |
|
530 === `GetHogFort(gearUid)` (0.9.23) === |
|
531 Returns the name of the fort of the team of the specified hedgehog gear. |
|
532 |
|
533 === `GetHogGrave(gearUid)` === |
|
534 Returns the name of the grave of the team of the specified hedgehog gear. |
|
535 |
|
536 === `GetHogVoicepack(gearUid)` === |
|
537 Returns the name of the voicepack of the team of the specified hedgehog gear. |
|
538 |
|
539 === `GetAmmoCount(gearUid, ammoType)` === |
|
540 Returns the ammo count of the specified ammo type for the specified hedgehog gear. If infinite, returns `AMMO_INFINITE`. |
|
541 |
|
542 === `GetAmmoTimer(gearUid, ammoType)` (0.9.25) === |
|
543 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. |
|
544 |
|
545 Example: |
|
546 <code lang="lua">GetAmmoTimer(CurrentHedgehog, amGrenade) |
|
547 -- May return 1000, 2000, 3000, 4000 or 5000</code> |
|
548 |
|
549 === `HealHog(gearUid, healthBoost[, showMessage[, tint]])` (0.9.24) === |
|
550 Convenience function to increase the health of a hedgehog with default visual effects. |
|
551 |
|
552 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. |
|
553 |
|
554 If `showMessage` is false, no message is shown. With `tint` you can set the RGBA color of the particles (default: `0x00FF00FF`). |
|
555 |
|
556 This function does not affect the poison state, however (see `SetEffect`). |
|
557 |
495 === `HogTurnLeft(gearUid, boolean)` === |
558 === `HogTurnLeft(gearUid, boolean)` === |
496 Faces the specified hog left or right. |
559 Faces the specified hog left or right. |
497 |
560 |
498 Example: |
561 Example: |
499 |
562 |
500 <code language="lua"> HogTurnLeft(CurrentHedgehog, true) -- turns CurrentHedgehog left |
563 <code language="lua"> HogTurnLeft(CurrentHedgehog, true) -- turns CurrentHedgehog left |
501 HogTurnLeft(CurrentHedgehog, false) -- turns CurrentHedgehog right</code> |
564 HogTurnLeft(CurrentHedgehog, false) -- turns CurrentHedgehog right</code> |
502 |
565 |
503 === `SetGearTarget(gearUid, x, y)` === |
566 === `IsHogHidden(gearUid)` (0.9.25) === |
504 Sets the x and y coordinate of target-based weapons/utilities. |
567 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. |
505 *Note*: This can’t be used in onGearAdd() but must be called after gear creation. |
|
506 |
|
507 === `SetState(gearUid, state)` === |
|
508 Sets the state of the specified gear to the specified `state`. This is a bitmask made out of the variables as seen in [States]. |
|
509 |
|
510 This function is often used together with `GetState` and the bitmask utility functions `band` and `bnot` in order to manipulate a single flag. |
|
511 |
|
512 Examples: |
|
513 <code language="lua"> |
|
514 SetState(CurrentHedgehog, bor(GetState(CurrentHedgehog), gstInvisible)) |
|
515 --[[ first the state bitmask of CurrentHedgehog is bitwise ORed with |
|
516 the gstInvisible flag, thus making the bit responsible for |
|
517 invisiblity to become 1. Then the new bitmask is applied to |
|
518 CurrentHedgehog, thus making it invisible. ]] |
|
519 </code> |
|
520 |
|
521 <code language="lua"> |
|
522 SetState(CurrentHedgehog, band(GetState(CurrentHedgehog), bnot(gstInvisible))) |
|
523 --[[ The reverse of the above: This function toggles CurrentHedgehog’s |
|
524 gstInvisible flag off, thus making it visible again. ]] |
|
525 </code> |
|
526 |
|
527 === `SetGearMessage(gearUid, message)` === |
|
528 Sets the gear messages of the specified gear. `message` is a bitmask built out of flags seen in [GearMessages]. |
|
529 |
|
530 === `SetTag(gearUid, tag)` === |
|
531 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. |
|
532 |
|
533 Note that the word “tag” here does _not_ refer to the name and health tags you see above hedgehogs, this is something different. |
|
534 |
|
535 <code language="lua"> |
|
536 -- This adds a ball (the one from the ballgun) at (123, 456): |
|
537 ball = AddGear(123, 456, gtBall, 0, 0, 0, 0) |
|
538 -- This sets the tag of the gear. For gtBall, the tag specified the color. “8” is the color white. |
|
539 SetTag(ball, 8) -- |
|
540 </code> |
|
541 |
|
542 The meaning of tags are described in [GearTypes]. |
|
543 |
|
544 === `SetTimer(gearUid, timer)` === |
|
545 Sets the timer of the specified gear. Also see `GetTimer`. |
|
546 |
|
547 === `SetHogLevel(gearUid, level)` === |
|
548 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. |
|
549 |
|
550 === `SetGearAIHints(gearUid, aiHint)` === |
|
551 Set some behaviour hints for computer-controlled hedgehogs for any given gear with `gearUid`. |
|
552 |
|
553 Set `aiHint` to either of: |
|
554 |
|
555 * `aihUsualProcessing`: AI hogs treat this gear the usual way. This is the default. |
|
556 * `aihDoesntMatter`: AI hogs don't bother attacking this gear intentionally. |
|
557 |
|
558 Example: |
|
559 |
|
560 <code language="lua"> |
|
561 SetGearAIHints(uselessHog, aihDoesntMatter) |
|
562 -- This makes AI hogs stop caring about attacking uselessHog</code> |
|
563 |
|
564 === `SetGearPos(gearUid, value)` === |
|
565 Sets the `Pos` value (not the position!) of the specified gear to specified value. See `GetGearPos` for more information. |
|
566 |
568 |
567 === `HideHog(gearUid)` === |
569 === `HideHog(gearUid)` === |
568 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). |
570 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). |
569 |
571 |
570 Example: |
572 Example: |