# HG changeset patch
# User nemo
# Date 1451490913 18000
# Node ID d9fc58ac04f2c39d6d25cf9d39591d0dcf08cbff
# Parent  fe70504acfc25e68f82ae6bb139d9d98f0ff3b9e
Update EraseSprite, PlaceSprite and Get/Set GearValues

diff -r fe70504acfc2 -r d9fc58ac04f2 LuaAPI.wiki
--- a/LuaAPI.wiki	Wed Dec 16 23:14:54 2015 +0000
+++ b/LuaAPI.wiki	Wed Dec 30 10:55:13 2015 -0500
@@ -553,18 +553,21 @@
 
 This is returned (all variables are integers):
 
-`Angle, Power, WDTimer, Radius, Density, Karma, DirAngle, AdvBounce, ImpactSound, nImpactSounds, Tint, Damage`
+`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+)
 
 Example:
 <code language="lua">
--- Get all values in a single line of code:
-local Angle, Power, WDTimer, Radius, Density, Karma, DirAngle, AdvBounce, ImpactSound, nImpactSounds, Tint, Damage = GetGearValues(myGear)
+-- Get all values in a single line of code (omit Boom in 0.9.22) :
+local Angle, Power, WDTimer, Radius, Density, Karma, DirAngle, AdvBounce, ImpactSound, nImpactSounds, Tint, Damage, Boom = GetGearValues(myGear)
 </code>
 
 === <tt>!GetVisualGearValues(vgUid)</tt> ===
@@ -623,8 +626,8 @@
 <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)</tt> (0.9.22) ===
-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.
+=== <tt>!SetGearValues(gearUid, Angle, Power, WDTimer, Radius, Density, Karma, DirAngle, AdvBounce, ImpactSound, ImpactSounds, Tint, Damage, Boom)</tt> (0.9.22) ===
+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+.
 
 Set `nil` for each value you do not want to change.
 
@@ -911,7 +914,7 @@
 || 6 || long || vertical ||
 || 7 || long || increasing right ||
 
-==== <tt>!PlaceSprite(x, y, sprite, frameIdx, ...)</tt> ====
+==== <tt>!PlaceSprite(x, y, sprite, frameIdx, tint, behind, flipHoriz, flipVert, [, landFlag, ...])</tt> ====
 Places a [Sprites sprite] at the specified position (`x`, `y`) on the map, it behaves like terrain then. `frameIdx` is the frame index starting by 0. This is used if the sprite consists of several sub-images. Only a subset of the sprites is currently supported by this function:
 
  * `sprAmGirder`
@@ -937,15 +940,30 @@
  * `sprCustom1`
  * `sprCustom2`
 
-The 5th and later arguments specify land flags (see the constants section) to be used for the newly created terrain. If omited, `lfNormal` is assumed.
+Tint is for an RGBA colouring to apply, this works about the same as Tint in gears.  Behind indicates the sprite should not replace existing land. flipHoriz and flipVert are for flipping the sprite vertically and horizontally before placing.
+The 9th and later arguments specify land flags (see the constants section) to be used for the newly created terrain. If omited, `lfNormal` is assumed.
 
 Example:
 
-<code language="lua">PlaceSprite(2836, 634, sprAmGirder, 5, lfNormal)
+<code language="lua">PlaceSprite(2836, 634, sprAmGirder, 5)
 -- Places the girder sprite as normal terrain at (2836, 634). The `frameIdx` 5 is for the long decreasing right girder.</code>
-<code language="lua">PlaceSprite(1411, 625, sprAmRubber, 1, lfBouncy)
+<code language="lua">PlaceSprite(1411, 625, sprAmRubber, 1, nil, nil, nil, nil, lfBouncy)
 -- Places the rubber band sprite as bouncy terrain at (2836, 634). The `frameIdx` 1 is for the decreasing right rubber band.</code>
 
+==== <tt>!EraseSprite(x, y, sprite, frameIdx, eraseOnLFMatch, onlyEraseLF, flipHoriz, flipVert, [, landFlag, ...])</tt> ====
+Erases a [Sprites sprite] at the specified position (`x`, `y`) on the map. `frameIdx` is the frame index starting by 0. sprite, frameIdx, flipHoriz and flipVert behave the same as in PlaceSprite.
+
+Set eraseOnLFMatch to true to erase all land for a pixel that matches any of the passed in land flags.  This is useful if, for example, an lfBouncy sprite was placed "behind" land using PlaceSprite and you want to remove it without destroying the non-bouncy terrain.
+
+Set onlyEraseLF to true to only remove specific land flags.  If for example a sprite consists of lfIndestructible and lfBouncy, and you call EraseSprite with onlyEraseLF and lfIndestructible set, the sprite will remain bouncy but can be destroyed.  You can use this to entirely remove all land flags from a sprite - at this point the sprite will be visual only, painted on the map but with no collision.
+
+Example:
+
+<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) ====
 This function is used to draw your own maps using Lua. The maps drawn with this are of type “hand-drawn”.
 
@@ -1214,4 +1232,4 @@
 
 
 === `WriteLnToConsole(string)` ===
-Writes `string` to the `Logs/game0.log`, found in the user data directory.
\ No newline at end of file
+Writes `string` to the `Logs/game0.log`, found in the user data directory.