hwkb: comparison LuaAPI.wiki

equal deleted inserted replaced

-:550b1afc9300
+:4ac63a5c0184
 === <tt>onGameStart()</tt> ===
 This function is called when the first round starts.
 Can be used to show the mission and for more setup, for example initial target spawning.
-=== <tt>onPreviewInit()</tt> (0.9.21) ===
+=== <tt>onPreviewInit()</tt> ===
 This function is called when the map preview in the frontend is initialized. This happens when the script is selected or you change a map generator parameter.
 It is useful for scripts which create their own maps (see `AddPoint` and `FlushPoints`). If you create a map in this function, a preview will be generated from this map and is exposed to the frontend.
-=== <tt>onParameters()</tt> (0.9.21) ===
+=== <tt>onParameters()</tt> ===
 This function is called when the script parameters (as specified in the game scheme) become available. The script parameter string is stored in the global variable `ScriptParam`.
 Please note that it is normally not safe to call many of the other functions inside this function, this function is called very early in the game, only use this to initialize variables and other internal stuff like that.
 *Tip*: If you use the Params library  (`/Scripts/Params.lua`), you can make the task of dissecting the string into useful values a bit easier, but it’s not required. (The Params library is not documented yet, however).
 This function is called at one of the earliest possible moment after the end of a turn. After this callback, Hedgewars then performs all the other stuff between turns. This includes things like: Applying poison or Sudden Death damage, calculating total hog damage, rising the water in Sudden Death, dropping a crate, checking victory, giving control to the next hog.
 Because this function is called *before* victories are checked, this is useful to set up your victory conditions here.
-=== <tt>onSuddenDeath()</tt> (0.9.22) ===
+=== <tt>onSuddenDeath()</tt> ===
 This function is called on the start of Sudden Death.
 === <tt>onGearAdd(gearUid)</tt> ===
 This function is called when a new gear is added. Useful in combination with `GetGearType(gearUid)`.
 If neither is set, the parameters passed are the team index and `-1`, and the function will be called once for each team.
 These indexes can be used to look up details of the clan/team/hedgehog prior to gear creation. Routines to do these lookups will be created as needed.
 If you add this hook, the expectation is that you will call SetAmmo appropriately. Any values from `onAmmoStoreInit` are ignored.
-=== <tt>onGearWaterSkip(gear)</tt> (0.9.21) ===
+=== <tt>onGearWaterSkip(gear)</tt> ===
 This function is called when the gear `gear` skips over water.
-=== <tt>onScreenResize()</tt> (0.9.16) ===
+=== <tt>onScreenResize()</tt> ===
 This function is called when you resize the screen. Useful place to put a redraw function for any `vgtHealthTags` you're using.
 === <tt>onAttack()</tt> ===
 This function is called when your Hedgehog attacks.
 === <tt>onUsedAmmo(ammoType)</tt> (0.9.23) ===
 Called after a weapon has been used completely, with `ammoType` as the used ammo type.
 For example, it is called right after a bazooka is fired, when both shots of a shotgun have been fired, when extra time is used, or when all 4 shots of a portable portal device have been fired. It is also called when using a multi-shot ammo has been aborted by changing the weapon selection mid-way, because this still uses up the ammo.
-=== <tt>onHogHide(gearUid)</tt> (0.9.16) ===
+=== <tt>onHogHide(gearUid)</tt> ===
 This function is called when a hedgehog with the gear ID `gearUid` is hidden (removed from the map).
-=== <tt>onHogRestore(gearUid)</tt> (0.9.16) ===
+=== <tt>onHogRestore(gearUid)</tt> ===
 This function is called when a hedgehog with the specified gear ID `gearUid` is restored (unhidden).
-=== <tt>onSpritePlacement(spriteId, centerX, centerY)</tt> (0.9.21) ===
+=== <tt>onSpritePlacement(spriteId, centerX, centerY)</tt> ===
 This function is called when a [Sprites Sprite] has been placed.
 `spriteID` is the type of the sprite, you find a list at [Sprites Sprites]. `centerX` and `centerY` are the coordinates of the center of the sprite.
-=== <tt>onGirderPlacement(frameIdx, centerX, centerY)</tt> (0.9.21) ===
+=== <tt>onGirderPlacement(frameIdx, centerX, centerY)</tt> ===
 This function is called when a girder has been placed.
 `frameIdx` is used for the length and orientation of the girder. The possible values are explained in `PlaceGirder`. `centerX` and `centerY` are the coordinates of the girder’s center.
-=== <tt>onRubberPlacement(frameIdx, centerX, centerY)</tt> (0.9.21) ===
+=== <tt>onRubberPlacement(frameIdx, centerX, centerY)</tt> ===
 This function is called when a rubber has been placed.
 `frameIdx` is used for the rubber orientation. The possible values are explained in `PlaceRubber`. `centerX` and `centerY` are the coordinates of the rubber’s center.
 === `onSpecialPoint(x, y, flags)` ===
 See `SetEffect` for further details.
 === <tt>!GetHogHat(gearUid)</tt> ===
 Returns the hat of the specified hedgehog gear.
-=== <tt>!GetHogFlag(gearUid)</tt> (0.9.22) ===
+=== <tt>!GetHogFlag(gearUid)</tt> ===
 Returns the name of the flag of the team of the specified hedgehog gear.
 === <tt>!GetHogFort(gearUid)</tt> (0.9.23) ===
 Returns the name of the fort of the team of the specified hedgehog gear.
-=== <tt>!GetHogGrave(gearUid)</tt> (0.9.22) ===
+=== <tt>!GetHogGrave(gearUid)</tt> ===
 Returns the name of the grave of the team of the specified hedgehog gear.
-=== <tt>!GetHogVoicepack(gearUid)</tt> (0.9.22) ===
+=== <tt>!GetHogVoicepack(gearUid)</tt> ===
 Returns the name of the voicepack of the team of the specified hedgehog gear.
-=== <tt>!GetAmmoCount(gearUid, ammoType)</tt> (0.9.16) ===
+=== <tt>!GetAmmoCount(gearUid, ammoType)</tt> ===
 Returns the ammo count of the specified ammo type for the specified hedgehog gear.
 === <tt>!IsHogLocal(gearUid)</tt> (0.9.23) ===
 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.
 This is perfect to hide certain captions like weapon messages from enemy eyes.
-=== <tt>!GetGearTarget(gearUid, x, y)  (0.9.16)</tt> ===
+=== <tt>!GetGearTarget(gearUid, x, y) </tt> ===
 Returns the x and y coordinate of target-based weapons/utilities.
 <b>Note:</b>: This can’t be used in `onGearAdd()` but must be called after gear creation.
 === <tt>GetX(gearUid)</tt> ===
 Returns x coordinate of the gear.
 === <tt>!GetGearPos(gearUid)</tt> ===
 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.
 *Important*: Pos is *not* related to the gear's position, use `GetGearPosition` for that.
-=== <tt>!GetGearValues(gearUid)</tt> (0.9.22) ===
+=== <tt>!GetGearValues(gearUid)</tt> ===
 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.
 This is returned (all variables are integers):
 `Angle, Power, WDTimer, Radius, Density, Karma, DirAngle, AdvBounce, ImpactSound, nImpactSounds, Tint, Damage, Boom`
-Boom is 0.9.23+
 A rough description of some of the parameters:
 * `Radius`: Effect or collision radius, most of the time
 * `ImpactSound`: Sound it makes on a collision (see [Sounds])
 * `Tint`: Used by some gear types to determine its colorization. The color is in RGBA format.
-* `Boom`: Used by most gears to determine the damage dealt. (0.9.23+)
+* `Boom`: Used by most gears to determine the damage dealt.
 Example:
 <code language="lua">
--- Get all values in a single line of code (omit Boom in 0.9.22) :
+-- Get all values in a single line of code:
 local Angle, Power, WDTimer, Radius, Density, Karma, DirAngle, AdvBounce, ImpactSound, nImpactSounds, Tint, Damage, Boom = GetGearValues(myGear)
 </code>
 === <tt>!GetVisualGearValues(vgUid)</tt> ===
 This returns the typically set visual gear values, useful if manipulating things like smoke or bubbles or circles. It returns the following values:
 Example:
 <code language="lua">    vgear = AddVisualGear(...)
 DeleteVisualGear(vgear) -- Delete the newly created visual gear.</code>
-=== <tt>!SetGearValues(gearUid, Angle, Power, WDTimer, Radius, Density, Karma, DirAngle, AdvBounce, ImpactSound, ImpactSounds, Tint, Damage, Boom)</tt> (0.9.22) ===
+=== <tt>!SetGearValues(gearUid, Angle, Power, WDTimer, Radius, Density, Karma, DirAngle, AdvBounce, ImpactSound, ImpactSounds, Tint, Damage, Boom)</tt> ===
-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.  Boom is 0.9.23+.
+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.
 Set `nil` for each value you do not want to change.
 Example:
 <code language="lua">
 SetVisualGearValues(circleUid, 1000, 1000)</code>
 <code language="lua">  -- set the tint of a visual gear to bright red.
 SetVisualGearValues(circleUid, nil, nil, nil, nil, nil, nil, nil, nil, nil, 0xff0000ff)</code>
-=== <tt>!FindPlace(gearUid, fall, left, right, tryHarder) (0.9.16)</tt> ===
+=== <tt>!FindPlace(gearUid, fall, left, right[, tryHarder])</tt> ===
-Finds a place for the specified gear between x=`left` and x=`right` and places it there. 0.9.16 adds an optional fifth parameter, `tryHarder`. Setting to `true`/`false` will determine whether the engine attempts to make additional passes, even attempting to place gears on top of each other.
+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.
 Example:
 <code language="lua">    gear = AddGear(...)
 FindPlace(gear, true, 0, LAND_WIDTH) -- places the gear randomly between 0 and LAND_WIDTH</code>
 === <tt>!HogSay(gearUid, text, manner [,vgState])</tt> ===
-Makes the specified gear say, think, or shout some text in a comic-style speech or thought bubble. In 0.9.21 `gearUid` is _not_ limited to hedgehogs, altough the function name suggests otherwise.
+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.
 The `manner` parameter specifies the type of the bubble and can have one of these values:
 || *Value of `manner`* || *Looks* ||
 || `SAY_THINK` || Thought bubble ||
 || `SAY_SAY` || Speech bubble ||
 || `SAY_SHOUT` || Exclamatory bubble (denotes shouting) ||
-As of 0.9.21, 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.
+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.
 || *Value of `vgState`* || *Effect* ||
 || `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. ||
 || `1` || The bubble is drawn translucent. ||
 || `2` || The bubble is drawn fully opaque. ||
 if (GetGearType(gear) == gtHedgehog) and (GetHogLevel(gear) > 0) then
 SetEffect(gear, hePoisoned, 1)
 end
 end</code>
-*Historic note*: prior to the ice-gun release, 0.9.19 (commit r10a0a31804f3) `effectState` was of boolean type (`true` = effect enabled, `false` = effect disabled)
 === <tt>CopyPV(gearUid, gearUid)</tt> ===
 This sets the position and velocity of the second gear to the first one.
 === <tt>!FollowGear(gearUid)</tt> ===
 Makes the game client follow the specifiec gear.
 <code language="lua">
 AddAmmo(CurrentHedgehog, amBazooka, 1) -- give the CurrentHedgehog a bazooka
 SetWeapon(amBazooka) -- select the Bazooka.</code>
-=== <tt>!SetNextWeapon()</tt> (0.9.21) ===
+=== <tt>!SetNextWeapon()</tt> ===
 This function makes the current hedgehog switch to the next weapon in list of available weapons. It can be used for example in trainings to pre-select a weapon.
 === <tt>!SetHogHat(gearUid, hat)</tt> ===
 Sets the hat of the specified hedgehog gear.
-=== <tt>!SetGearTarget(gearUid, x, y) (0.9.16)</tt> ===
+=== <tt>!SetGearTarget(gearUid, x, y)</tt> ===
 Sets the x and y coordinate of target-based weapons/utilities.
 *Note*: This can’t be used in onGearAdd() but must be called after gear creation.
 === <tt>!SetState(gearUid, state)</tt> ===
 Sets the state of the specified gear to the specified `state`. This is a bitmask made out of the variables as seen in [States].
 <code language="lua">
 SetGearAIHints(uselessHog, aihDoesntMatter)
 -- This makes AI hogs stop caring about attacking uselessHog</code>
-=== <tt>!SetGearPos(gearUid, value) (0.9.18-dev)</tt> ===
+=== <tt>!SetGearPos(gearUid, value)</tt> ===
 Sets the `Pos` value (not the position!) of the specified gear to specified value. See `GetGearPos` for more information.
 == Gameplay functions ==
 === `GameFlags` functions ===
 Sets the current wind in the range of -100 to 100 inclusive. Use together with `gfDisableWind` for full control.
 ==== <tt>!GetWind()</tt> (0.9.24) ====
 Returns current wind, expressed as a floating point number between -100 to 100 inclusive. Note there may be rounding errors.
-==== <tt>!SetMaxBuildDistance(distInPx)</tt> (0.9.22) ====
+==== <tt>!SetMaxBuildDistance(distInPx)</tt> ====
 Sets the maximum building distance for of girders and rubber bands in pixels to `distInPx`. If `distInPx` is `0`, the limit is disabled. If called without arguments, the distance will be reset to the default value.
 ==== `EndTurn([noTaunts])` (0.9.23) ====
 Ends the current turn.
 Example:
 <code language="lua">
 -- Appends a text to the ammo tooltip of the bazooka but leaves name and main description intact
 SetAmmoTexts(amBazooka, "This weapon deals double the damage than usually.")</code>
-==== <tt>!AddAmmo(gearUid, ammoType, ammoCount) (0.9.16) </tt> ====
+==== <tt>!AddAmmo(gearUid, ammoType, ammoCount)</tt> ====
 Adds `ammoType` to the specified gear. The amount added is determined by the arguments passed via `SetAmmo()` in the `onAmmoStoreInit()` event handler. `ammoCount` is an optional parameter. If this is set, the ammo will **not** be added, but instead set to `ammoCount`. A value of 0 will remove the weapon, a value of 100 will give infinite ammo.
 ==== <tt>!GetAmmoName(ammoType [, ignoreOverwrite ])</tt> (0.9.23) ====
 Returns the localized name for the specified `ammoType`, taking an ammo name overwritten by `SetAmmoTexts` into account. If `ignoreOverwrite` is `true`, this function will always return the original ammo name of the weapon and ignores names which may have been overwritten by `SetAmmoTexts`.
 === Map ===
 ==== <tt>!MapHasBorder()</tt> ====
 Returns `true`/`false` if the map has a border or not.
-==== <tt>!TestRectForObstacle(x1, y1, x2, y2, landOnly) (0.9.16) </tt> ====
+==== <tt>!TestRectForObstacle(x1, y1, x2, y2, landOnly)</tt> ====
 Checks the rectangle between the given coordinates for possible collisions. Set `landOnly` to `true` if you don’t want to check for collisions with gears (hedgehogs, etc.).
-==== <tt>!PlaceGirder(x, y, frameIdx)</tt> (0.9.16) ====
+==== <tt>!PlaceGirder(x, y, frameIdx)</tt> ====
 Attempts to place a girder with centre points `x`, `y` and a certain length and orientation, specified by `frameIdx`. The girder can only be placed in open space and must not collide with anything so this function may fail. It will return `true` on successful placement and `false` on failure.
 These are the accepted values for `frameIdx`:
 || *`frameIdx`* || *Length* || *Orientation* ||
 * `sprHHTelepMask`
 * `sprTurnsLeft`
 * `sprSpeechCorner`
 * `sprSpeechEdge`
 * `sprSpeechTail`
-* `sprTargetBee` (since 0.9.23)
+* `sprTargetBee`
 * `sprThoughtCorner`
 * `sprThoughtEdge`
 * `sprThoughtTail`
 * `sprShoutCorner`
 * `sprShoutEdge`
 <code language="lua">EraseSprite(2836, 634, sprAmGirder, 5)
 -- Removes the girder sprite at (2836, 634). The frameIdx 5 is for the long decreasing right girder.</code>
 <code language="lua">EraseSprite(1411, 625, sprAmRubber, 1, true, true, nil, nil, lfIndestructible)
 -- Removes indestructibility from a rubber band sprite at (2836, 634). The frameIdx 1 is for the decreasing right rubber band.</code>
-==== <tt>!AddPoint(x, y [, width [, erase] ])</tt> (0.9.21) ====
+==== <tt>!AddPoint(x, y [, width [, erase] ])</tt> ====
 This function is used to draw your own maps using Lua. The maps drawn with this are of type “hand-drawn”.
 The function takes a `x`,`y` location, a `width` (means start of a new line) and `erase` (if `false`, this function will draw normally, if `true`, this function will erase drawn stuff).
 This function must be called within `onGameInit`, where `MapGen` has been set to `mgDrawn`. You also should call `FlushPoints` when you are finished with drawing.
-==== <tt>!FlushPoints()</tt> (0.9.21) ====
+==== <tt>!FlushPoints()</tt> ====
 Makes sure that all the points/lines specified using `AddPoint` are actually applied to the map. This function must be called within `onGameInit`.
 === Current hedgehog ===
-==== <tt>!GetCurAmmoType()</tt> (0.9.16) ====
+==== <tt>!GetCurAmmoType()</tt> ====
 Returns the currently selected [AmmoTypes Ammo Type].
-==== <tt>!SwitchHog(gearUid)</tt> (0.9.16) ====
+==== <tt>!SwitchHog(gearUid)</tt> ====
 This function will switch to the hedgehog with the specifiedd `gearUid`.
 ==== <tt>!SetInputMask(mask)</tt> ====
 Masks specified player input. This means that Hedgewars ignores certain player inputs, such as walking or jumping.
 `caption` is the text displayed in the first line, `subcaption` is displayed in the second line and `text` is the text displayed in the third and following lines.
 `text` uses some special characters for formatting: `|` is used for a line break, and everything written before and including a `:` in a line is written in a lighter color.
-As of version 0.9.22, `icon` accepts the following values:
+`icon` accepts the following values:
 || *`icon`* || *What is shown* ||
 || _negative number_ || Icon of an ammo type. It is specified as the negative of an ammo type constant (see [AmmoTypes]), i.e. `-amBazooka` for the bazooka icon. ||
 || `0` || Golden crown ||
 || `1` || Target ||
 || `4` || Golden star ||
 || `5` || Utility crate ||
 || `6` || Health crate ||
 || `7` || Ammo crate ||
 || `8` || Barrel ||
-|| `9` || Dud mine (0.9.23) ||
+|| `9` || Dud mine ||
 Example:
 <code language="lua">
 ShowMission(loc("Nobody Laugh"), loc("User Challenge"), loc("Eliminate the enemy before the time runs out"), 0, 0)
 </code>
 <code language="lua">
 HedgewarsScriptLoad("/Scripts/Locale.lua")  -- loads locale library
 </code>
 == Stats functions ==
-=== <tt>!SendStat(TStatInfoType, statMessage[, teamName])</tt> (0.9.20) ===
+=== <tt>!SendStat(TStatInfoType, statMessage[, teamName])</tt> ===
 This function allows to change the details of the stats screen seen after the end of a game.
 `TStatInfoType` is the piece of information you want to manipulate. The result of this functions varies greatly for different `TStatInfoType`s. The parameter `statMessage` is mandatory and is a string used for the statistics, its meaning depends on the `TStatInfoType`. The parameter `teamName` contains the name of a team which is relevant to the chosen stat. This parameter is not always required, this also depends on `TStatInfoType`.
 * As the game engine send stats to the frontend at the end of the game one should send her stats when the game is going to finish and right before the call of `EndGame()`. (Note: Stats are sent from the engine in `CheckForWin`. If conditions are met (win or draw) then `SendStats(uStats)` is called.)
 * Calling just `EndGame()` won’t produce any stats.
 * If one would like to produce a custom graph see also `SendHealthStatsOff()`.
-=== <tt>!SendHealthStatsOff()</tt> (0.9.20) ===
+=== <tt>!SendHealthStatsOff()</tt> ===
 Prevents the engine of sending health stats to the frontend.
 If any health stats haven’t been sent before this will cause the health graph to the stats page to be hidden. Use this function in the Lua scripts to produce custom graphs by calling it inside `onGameStart()` and using the `SendStat()` function.
 === <tt>!SendAchievementsStatsOff()</tt> (0.9.23) ===

changeset 1232	4ac63a5c0184
parent 1231	550b1afc9300
child 1235	dae4580eca94