Multi Theft Auto: Wiki - User contributions [en]

Resource:Bone attach

2019-05-28T09:49:09Z

LuXorioN: Fixed available bone IDs being incorrect

{{Resource page}}
__NOTOC__
This resource lets you attach elements to players/peds bones using its exported functions.
Download can be found at the [https://community.multitheftauto.com/index.php?p=resources&s=details&id=2540 MTA community page].<br>
Resource developed by: [https://community.multitheftauto.com/index.php?p=profile&id=5138 Devan_LT] (also known as [https://forum.mtasa.com/profile/1985-crystalmv/ CrystalMV])

==Exported functions/events==
<section name="Server or Client" class="both" show="true">
This function attaches element to the bone of the ped or player.
<syntaxhighlight lang="lua">
bool attachElementToBone (element theElement, element theAttachToPed, int theBone[, float xPosOffset = 0, float yPosOffset = 0, float zPosOffset = 0, float xRotOffset = 0, float yRotOffset = 0, float zRotOffset = 0])
</syntaxhighlight>
====Required Arguments====
*'''theElement:''' Element which you want to attach..
*'''theAttachToPed:''' The ped or player which you want to attach element to.
*'''theBone:''' The number of the ped or player's bone which you want to attach element to.
[[Image:Bones.jpg|thumb|Bone numbers]]
<div style="border: 3px red solid; margin-bottom:3px; padding-left:5px;">

*'''1:''' head
*'''2:''' neck
*'''3:''' spine
*'''4:''' pelvis
*'''5:''' left clavicle
*'''6:''' right clavicle
*'''7:''' left shoulder
*'''8:''' right shoulder
*'''9:''' left elbow
*'''10:''' right elbow
*'''11:''' left hand
*'''12:''' right hand
*'''13:''' left hip
*'''14:''' right hip
*'''15:''' left knee
*'''16:''' right knee
*'''17:''' left ankle
*'''18:''' right ankle
*'''19:''' left foot
*'''20:''' right foot
</div>
====Optional arguments====
{{OptionalArg}}
*'''xPosOffset:''' The x offset, if you want the elements to be a certain distance from one another (default 0).
*'''yPosOffset:''' The y offset (default 0).
*'''zPosOffset:''' The z offset (default 0).
*'''xRotOffset:''' The x rotation offset (default 0).
*'''yRotOffset:''' The y rotation offset (default 0).
*'''zRotOffset:''' The z rotation offset (default 0).
====Returns====
Returns true if element was successfully attached, false otherwise.

----

This function detaches element from the bone of the ped.
<syntaxhighlight lang="lua">
bool detachElementFromBone (element theElement)
</syntaxhighlight>
====Required Arguments====
*'''theElement:''' Element which you want to detach.
====Returns====
Returns true if element was successfully detached, false otherwise.

----

This function checks if element is attached to a bone.
<syntaxhighlight lang="lua">
bool isElementAttachedToBone (element theElement)
</syntaxhighlight>
====Required Arguments====
*'''theElement:''' Element which you want to check.
====Returns====
Returns true if element is attached to a bone, false otherwise.

----

This function gets ped, bone and offset details of attached element.
<syntaxhighlight lang="lua">
bool getElementBoneAttachmentDetails (element theElement)
</syntaxhighlight>
====Required Arguments====
*'''theElement:''' Element which you want to get attachment details of.
====Returns====
Returns ped, bone, x, y, z, rx, ry, rz used in attachElementToBone if element is attached, false otherwise.

----

This function changes position offset of attached element.
<syntaxhighlight lang="lua">
bool setElementBonePositionOffset (element theElement, float xPosOffset, float yPosOffset, float zPosOffset)
</syntaxhighlight>
====Required Arguments====
*'''theElement:''' Element which you want to change offset of.
*'''xPosOffset:''' New x position offset.
*'''yPosOffset:''' New y position offset.
*'''zPosOffset:''' New z position offset.
====Returns====
Returns true if position set successfully, false otherwise.

----

This function changes rotation offset of attached element.
<syntaxhighlight lang="lua">
bool setElementBoneRotationOffset (element theElement, float xRotOffset, float yRotOffset, float zRotOffset)
</syntaxhighlight>
====Required Arguments====
*'''theElement:''' Element which you want to change offset of.
*'''xRotOffset:''' New x rotation offset.
*'''yRotOffset:''' New y rotation offset.
*'''zRotOffset:''' New z rotation offset.
====Returns====
Returns true if rotation set successfully, false otherwise.
</section>
<section name="Client-Only" class="client" show="true">
This function gets position and rotation of the ped bone.
<syntaxhighlight lang="lua">
bool getBonePositionAndRotation (element theAttachToPed, int theBone)
</syntaxhighlight>
====Required Arguments====
*'''theAttachToPed:''' The ped or player which bone you want to get position.
*'''theBone:''' The number of the ped or player's bone which you want to get position.
====Returns====
Returns bone x, y, z position and rotation if ped is streamed in and bone number is valid, false otherwise.
</section>

==Example==
<section name="Example 1" class="server" show="true">
This example makes the player carry a money bag when they type 'getbag':
<syntaxhighlight lang="lua">
-- this function is called whenever someone types 'getbag' in the console:
function attachCash (thePlayer)
local x, y, z = getElementPosition (thePlayer)
setPedAnimation (thePlayer, "ROB_BANK", "CAT_Safe_Rob", -1, true, false, false)
local objPick = createObject (1550, x, y, z)
setTimer (function (thePlayer)
setPedAnimation (thePlayer, nil)
exports.bone_attach:attachElementToBone (objPick, thePlayer, 4, -0.3, 0.2, 0, -125, 0, 0)
end, 1000, 1, thePlayer)
end
addCommandHandler ("getbag", attachCash)
</syntaxhighlight>
</section>

Template:Connection functions

2014-12-19T00:08:36Z

LuXorioN: Created page with "* create * query * exec <noinclude>Category:Functions templates</noinclude>"

* [[create]]
* [[query]]
* [[exec]]
<noinclude>[[Category:Functions templates]]</noinclude>

Element/Connection

2014-12-19T00:04:56Z

LuXorioN: Created page with "==Related scripting functions== ===Server=== {{connection functions}} Category:Scripting Concepts"

==Related scripting functions==
===Server===
{{connection functions}}
[[Category:Scripting Concepts]]

MTA Classes

2014-12-19T00:01:45Z

LuXorioN:

In order to perform operations on MTA objects via scripting, pointers to internal classes are exported to scripts as Lua userdata. Each of these classes has a number of exported scripting functions associated to them.

Elements that have a physical representation in the game are also known as [[entity|Entities]].

The complete list of classes to be found in scripts follows:

* [[account|Account]]
* [[acl|ACL]]
* [[aclgroup|ACL group]]
* [[Ban]]
* [[element|Element]]
<ul>{{Elements}}</ul>
* [[resource|Resource]]
* [[textdisplay|Text display]]
* [[textitem|Text item]]
* [[timer|Timer]]
* [[xmlnode|XML node]]
* [[connection|Connection]]
[[Category:Scripting Concepts]]
[[es:Clases MTA]]
[[it:Classi di MTA]]
[[ru:Классы MTA]]

DxSetShaderTransform

2014-11-18T08:36:28Z

LuXorioN: Fixxed Bot Section

{{Client function}}
{{Needs_Example}}
__NOTOC__
This function applies a 3D transformation to a [[shader]] element when it is drawn with [[dxDrawImage]].

==Syntax==
<syntaxhighlight lang="lua">
bool dxSetShaderTransform ( element theShader, float rotationX, float rotationY, float rotationZ, [ float rotationCenterOffsetX = 0, float rotationCenterOffsetY = 0, float rotationCenterOffsetZ = 0, bool bRotationCenterOffsetOriginIsScreen = false, float perspectiveCenterOffsetX = 0, float perspectiveCenterOffsetY = 0, bool bPerspectiveCenterOffsetOriginIsScreen = false ] )
</syntaxhighlight>

===Required Arguments===
*'''theShader:''' The shader element whose transformation is to be changed
*'''rotationX:''' Rotation angle in degrees around the X axis (Left,right). This will make the shader rotate along its width.
*'''rotationY:''' Rotation angle in degrees around the Y axis (Up,down). This will make the shader rotate along its height.
*'''rotationZ:''' Rotation angle in degrees around the Z axis (In,out). This will make the shader rotate in a similar way to the rotation argument in [[dxDrawImage]].

===Optional Arguments===
*'''rotationCenterOffsetX :''' The center of rotation offset X position in screen relative units.
*'''rotationCenterOffsetY :''' The center of rotation offset Y position in screen relative units.
*'''rotationCenterOffsetZ :''' The center of rotation offset Z position in screen relative units.
*'''bRotationCenterOffsetOriginIsScreen :''' Set to [[boolean|true]] if the center of rotation origin should be the center of the screen rather than the center of the image.
*'''perspectiveCenterOffsetX :''' The center of perspective offset X position in screen relative units.
*'''perspectiveCenterOffsetY :''' The center of perspective offset Y position in screen relative units.
*'''bPerspectiveCenterOffsetOriginIsScreen :''' Set to [[boolean|true]] if the center of perspective origin should be the center of the screen rather than the center of the image.

To convert screen relative units into screen pixel coordinates, ''multiply'' by the screen size. Conversely, to convert screen pixel coordinates to screen relative units, '''''divide''''' by the screen size.

===Returns===
Returns ''true'' if the shader element's transform was successfully changed, ''false'' otherwise.

==Example==
<syntaxhighlight lang="lua">
</syntaxhighlight>

==Requirements==
{{Requirements|n/a|1.2.0-9.03618|}}

==See Also==
{{Drawing_functions}}

DxDrawMaterialSectionLine3D

2014-11-18T08:35:32Z

LuXorioN: Fixxed Bot Section

__NOTOC__
{{Client function}}
This function draws a textured 3D line between two points in the 3D world - rendered for one frame. This should be used in conjunction with [[onClientPreRender]] in order to display continuously.

The 3D line with a large width value effectively becomes a rectangle, so it it possible to construct basic shapes such as boxes with several large width lines and the appropriate values for 'faceToward'.

==Syntax==
<syntaxhighlight lang="lua">
bool dxDrawMaterialSectionLine3D ( float startX, float startY, float startZ, float endX, float endY, float endZ, float u, float v, float usize, float vsize, element material, int width [, int color = white, float faceTowardX, float faceTowardY, float faceTowardZ ] )
</syntaxhighlight>

===Required Arguments===
* '''startX/Y/Z:''' The start position of the 3D line, representing a coordinate in the GTA world.
* '''endX/Y/Z:''' The end position of the 3D line, representing a coordinate in the GTA world.
*'''u:''' the absolute X coordinate of the top left corner of the section
*'''v:''' the absolute Y coordinate of the top left corner of the section
*'''usize:''' the absolute width of the section
*'''vsize:''' the absolute height of the section
* '''material:''' A [[material]] to draw the line with.
* '''width:''' The width/thickness of the line in GTA world units. (This is 1/75th of the width used in dxDrawLine3D)

==Optional Arguments==
* '''color:''' An integer of the hex color, produced using [[tocolor]] or 0xAARRGGBB (AA = alpha, RR = red, GG = green, BB = blue).
* '''faceTowardX/Y/Z:''' The direction the front of the line should face towards. If this is not set, the front of the line always faces toward the camera.

===Returns===
Returns a ''true'' if the operation was successful, ''false'' otherwise.

==Example==
This example draws corona like effects near the player
<syntaxhighlight lang="lua">
coronaTexture = dxCreateTexture("corona.png")
red = tocolor(255,0,0)
green = tocolor(0,255,0)
blue = tocolor(0,0,255)

addEventHandler("onClientPreRender",root,
function()
local x,y,z = getElementPosition(localPlayer)

dxSetBlendMode("add") -- Add blend mode looks best for corona effects
drawCorona( x+2, y+2, z+1, 1, red )
drawCorona( x+1, y+3, z+2, 1, green )
drawCorona( x-1, y+2, z+3, 1, blue )
dxSetBlendMode("blend") -- Restore default
end
)

-- Draw the corona texture
function drawCorona( x, y, z, size, color )
dxDrawMaterialSectionLine3D ( x, y, z+size,
x, y, z-size,
0,0,1,1, coronaTexture, size, color)
end

</syntaxhighlight>

==Requirements==
{{Requirements|n/a|1.3.0-9.03931|}}

==See Also==
{{Drawing_functions}}

DxDrawText

2014-11-18T08:34:27Z

LuXorioN: Fixxed Bot Section

__NOTOC__
{{Client function}}

Draws a string of text on the screen for one frame. In order for the text to stay visible continuously, you need to call this function with the same parameters on each frame update (see [[onClientRender]]).

==Syntax==
<syntaxhighlight lang="lua">
bool dxDrawText ( string text, float left, float top [, float right=left, float bottom=top, int color=white, float scale=1, mixed font="default", string alignX="left", string alignY="top", bool clip=false, bool wordBreak=false, bool postGUI=false, bool colorCoded=false, bool subPixelPositioning=false, float fRotation=0, float fRotationCenterX=0, float fRotationCenterY=0 ] )
</syntaxhighlight>

===Required Arguments===
*'''text:''' the text to draw
*'''left:''' the absolute X coordinate of the top left corner of the text
*'''top:''' the absolute Y coordinate of the top left corner of the text

===Optional Arguments===
*'''right:''' the absolute X coordinate of the right side of the text bounding box. Used for text aligning, clipping and word breaking.
*'''bottom:''' the absolute Y coordinate of the bottom side of the text bounding box. Used for text aligning, clipping and word breaking.
*'''color:''' the color of the text, a value produced by [[tocolor]] or 0xAARRGGBB (AA = alpha, RR = red, GG = green, BB = blue).
*'''scale:''' the size of the text.{{New feature|3.0110|1.1|'''scale:''' can (optionally) be specified as two floats. i.e. '''scaleX, scaleY'''}}
*'''font:''' Either a custom [[DX font]] element or the name of a built-in DX font:
{{DxFonts}}
*'''alignX:''' horizontal alignment of the text within the bounding box. Can be '''"left"''', '''"center"''' or '''"right"'''.
*'''alignY:''' vertical alignment of the text within the bounding box. Can be '''"top"''', '''"center"''' or '''"bottom"'''.
*'''clip:''' if set to ''true'', the parts of the text that don't fit within the bounding box will be cut off.
*'''wordBreak:''' if set to ''true'', the text will wrap to a new line whenever it reaches the right side of the bounding box. If ''false'', the text will always be completely on one line.
* '''postGUI:''' A bool representing whether the text should be drawn on top of or behind any ingame GUI (rendered by CEGUI).
{{New feature/item|9.03986|1.3.0|3986|
*'''colorCoded:''' Set to true to enable embedded #FFFFFF color codes. '''Note: clip and wordBreak are forced false if this is set.'''
*'''subPixelPositioning:''' A bool representing whether the text can be positioned sub-pixel-ly. Looks nicer for moving/scaling animations.
}}
{{New feature/item|9.06054|1.3.5|6054|
*'''fRotation:''' Rotation'''
*'''fRotationCenterX:''' Rotation Origin X'''
*'''fRotationCenterY:''' Rotation Origin Y'''
}}

===Returns===
Returns ''true'' if successful, ''false'' otherwise.

==Example==
This example code will add the current zone name in the lower left corner of the players' screens.
<syntaxhighlight lang="lua">
local screenWidth, screenHeight = guiGetScreenSize ( ) -- Get the screen resolution (width and height)

function createText ( )
local playerX, playerY, playerZ = getElementPosition ( localPlayer ) -- Get our player's coordinates.
local playerZoneName = getZoneName ( playerX, playerY, playerZ ) -- Get name of the zone the player is in.

-- Draw zone name text's shadow.
dxDrawText ( playerZoneName, 44, screenHeight - 41, screenWidth, screenHeight, tocolor ( 0, 0, 0, 255 ), 1.02, "pricedown" )
-- Draw zone name text.
dxDrawText ( playerZoneName, 44, screenHeight - 43, screenWidth, screenHeight, tocolor ( 255, 255, 255, 255 ), 1, "pricedown" )
end

function HandleTheRendering ( )
addEventHandler ( "onClientRender", root, createText ) -- keep the text visible with onClientRender.
end

addEventHandler ( "onClientResourceStart", resourceRoot, HandleTheRendering )
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.03986|Added colorCoded and subPixelPositioning arguments}}
{{ChangelogItem|1.3.5-9.06054|Added fRotation, fRotationCenterX and fRotationCenterY arguments}}

==See Also==
{{Drawing_functions}}

DxDrawImageSection

2014-11-18T08:33:16Z

LuXorioN: Fixxed Bot Section

__NOTOC__
{{Client function}}
Differing from [[dxDrawImage]], this function only draws a part of an image on the screen for a single frame. In order for the image to stay visible continuously, you need to call this function with the same parameters on each frame update (see [[onClientRender]]).

==Syntax==
<syntaxhighlight lang="lua">
bool dxDrawImageSection ( float posX, float posY, float width, float height, float u, float v, float usize, float vsize, mixed image, [ float rotation = 0, float rotationCenterOffsetX = 0, float rotationCenterOffsetY = 0, int color = white, bool postGUI = false ] )
</syntaxhighlight>

===Required Arguments===
*'''posX:''' the absolute X coordinate of the top left corner of the image
*'''posY:''' the absolute Y coordinate of the top left corner of the image
*'''width:''' the absolute width of the image
*'''height:''' the absolute height of the image
*'''u:''' the absolute X coordinate of the top left corner of the section which should be drawn from image
*'''v:''' the absolute Y coordinate of the top left corner of the section which should be drawn from image
*'''usize:''' the absolute width of the image section
*'''vsize:''' the absolute height of the image section
*'''image:''' Either a [[material]] element or a [[filepath]] of the image which is going to be drawn. (.dds images are also supported). Image files should ideally have dimensions that are a power of two, to prevent possible blurring.

===Optional Arguments===
*'''rotation:''' the rotation, in degrees for the image.
*'''rotationCenterOffsetX:''' the absolute X offset from the image center for which to rotate the image from.
*'''rotationCenterOffsetY:''' the absolute Y offset from the image center for which to rotate the image from.
*'''color:''' the color of the image, a value produced by [[tocolor]] or hexadecimal number in format: 0xAARRGGBB (AA = alpha, RR = red, GG = green, BB = blue).
*'''postgui :''' A bool representing whether the image should be drawn on top of or behind any ingame GUI (rendered by CEGUI).

===Returns===
Returns ''true'' if successful, ''false'' otherwise.

==Example==
The example draws a section of an image. (You can use [http://i1325.photobucket.com/albums/u630/Tourmalinelisa2/128x128.jpg this] image to test.)
<syntaxhighlight lang="lua">
addEventHandler('onClientRender', root, function()
dxDrawImageSection(400, 200, 64, 64, 0, 0, 64, 64, 'img.jpg') -- Draw a certain section
dxDrawImage(400, 300, 128, 128, 'img.jpg') -- Draw the whole image to be able to identify the difference
end)
</syntaxhighlight>

==See Also==
{{Drawing_functions}}

DxDrawMaterialLine3D

2014-11-18T08:32:16Z

LuXorioN: Fixxed Bot Section

__NOTOC__
{{Client function}}
This function draws a textured 3D line between two points in the 3D world - rendered for one frame. This should be used in conjunction with [[onClientPreRender]] in order to display continuously.

The 3D line with a large width value effectively becomes a rectangle, so it it possible to construct basic shapes such as boxes with several large width lines and the appropriate values for 'faceToward'.

3D lines are drawn at a particular place in the [[Game_Processing_Order|game processing order]], so use [[onClientPreRender]] for drawing if you are attaching them to world elements.

==Syntax==
<syntaxhighlight lang="lua">
bool dxDrawMaterialLine3D ( float startX, float startY, float startZ, float endX, float endY, float endZ, element material, int width, [, int color = white, float faceTowardX, float faceTowardY, float faceTowardZ ] )
</syntaxhighlight>

===Required Arguments===
* '''startX/Y/Z:''' The start position of the 3D line, representing a coordinate in the GTA world.
* '''endX/Y/Z:''' The end position of the 3D line, representing a coordinate in the GTA world.
* '''material:''' A [[material]] to draw the line with.
* '''width:''' The width/thickness of the line in GTA world units. (This is 1/75th of the width used in dxDrawLine3D)

==Optional Arguments==
{{OptionalArg}}
* '''color:''' An [[int|integer]] of the hex color, produced using [[tocolor]] or 0xAARRGGBB (AA = alpha, RR = red, GG = green, BB = blue).
* '''faceTowardX/Y/Z:''' The direction the front of the line should face towards. If this is not set, the front of the line always faces toward the camera.

===Returns===
Returns a ''true'' if the operation was successful, ''false'' otherwise.

==Example==
<section name="Client" class="client" show="true">
Draws an Image ( "test.png" Download : [http://i.epvpimg.com/dwsTe.png test.png] ) from the Position 0,0,3 to 0,0,15
<syntaxhighlight lang="lua">local img = dxCreateTexture("test.png")
addEventHandler("onClientRender", root,
function() -- x,y,z, targetx,targety,targetz,texture,width,color
dxDrawMaterialLine3D (0,0,3,0,0,15,img, 7, tocolor(255,255,255,255))
end)
</syntaxhighlight>
</section>

==Requirements==
{{Requirements|n/a|1.3.0-9.03931|}}

==See Also==
{{Drawing_functions}}

DxCreateTexture

2014-11-18T08:31:31Z

LuXorioN: Fixxed Bot Section

{{Client function}}
__NOTOC__
This function creates a [[texture]] element that can be used in the dxDraw functions.

It is possible to use dxCreateTexture to load cubemaps and volume textures, but these will only be useable as inputs for a shader. The Microsoft utility [http://nightly.mtasa.com/files/shaders/DxTex.zip DxTex] can view and change cubemaps and volume textures. DxTex can also convert standard textures into DXT1/3/5 compressed .dds which should reduce file sizes.
==Syntax==
<syntaxhighlight lang="lua">
element dxCreateTexture ( string filepath [, string textureFormat = "argb", bool mipmaps = true, string textureEdge = "wrap" ] )
</syntaxhighlight>
<syntaxhighlight lang="lua">
element dxCreateTexture ( string pixels [, string textureFormat = "argb", bool mipmaps = true, string textureEdge = "wrap" ] )
</syntaxhighlight>
<syntaxhighlight lang="lua">
element dxCreateTexture ( int width, int height [, string textureFormat = "argb", string textureEdge = "wrap", string textureType = "2d", int depth = 1 ] )
</syntaxhighlight>

===Required Arguments===
*'''filepath:''' The filepath of the image. (.bmp, .dds, .jpg, .png, and .tga images are supported). Image files should ideally have dimensions that are a power of two, to prevent possible blurring.
or
*'''pixels:''' [[Texture_pixels|Pixels]] containing image data. ('plain', 'jpeg' or 'png' pixels can be used here)
or
*'''width:''' Desired width (Must be a power of two. e.g. 128, 256)
*'''height :''' Desired height (Must be a power of two. e.g. 128, 256)

===Optional Arguments===
*'''textureFormat :''' A string representing the desired texture format, which can be one of:
**'''"argb"''' : ARGB uncompressed 32 bit color (default)
**'''"dxt1"''' : DXT1 compressed - Can take a fraction of a second longer to load (unless the file is already a DXT1 .dds). Uses 8 times less video memory than ARGB and can '''speed up drawing'''. Quality not as good as ARGB and does not support alpha blending.
**'''"dxt3"''' : DXT3 compressed - Can take a fraction of a second longer to load (unless the file is already a DXT3 .dds). Uses 4 times less video memory than ARGB and can '''speed up drawing'''. Quality slightly better than DXT1 and supports smooth alpha blending.
**'''"dxt5"''' : DXT5 compressed - Can take a fraction of a second longer to load (unless the file is already a DXT5 .dds). Uses 4 times less video memory than ARGB and can '''speed up drawing'''. Quality slightly better than DXT1 and supports crisp alpha blending.
*'''mipmaps :''' True to create a mip-map chain so the texture looks good when drawn at various sizes.
*'''textureEdge :''' A string representing the desired texture edge handling, which can be one of:
**'''"wrap"''' : Wrap the texture at the edges (default)
**'''"clamp"''' : Clamp the texture at the edges. This may help avoid edge artifacts.
*'''textureType :''' A string representing the desired texture type, which can be one of:
**'''"2d"''' : Standard texture (default)
**'''"3d"''' : Volume texture
**'''"cube"''' : Cube map
*'''depth:''' Desired number of slices when creating a volume texture

==Returns==
Returns a [[texture]] if successful, ''false'' if invalid arguments were passed to the function.

==Example==
<syntaxhighlight lang="lua">
addEventHandler( "onClientRender", root,
function()
if myImage then
dxDrawImage( 100, 350, 300, 350, myImage )
end
end
)

-- Use 'toggle' command to switch image on and off
addCommandHandler( "toggle",
function()
if not myImage then
myImage = dxCreateTexture( "moonpig.png" ) -- Create texture
else
destroyElement( myImage ) -- Destroy texture
myImage = nil
end
end
)
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.04021|Added textureType and depth argument}}
{{ChangelogItem|1.3.0-9.04035|Added textureEdge argument}}

==See Also==
{{Drawing_functions}}

GetWaterLevel

2014-11-18T08:30:33Z

LuXorioN: Fixxed Bot Section

__NOTOC__
{{Client function}}
This function allows you to retrieve the water level from a certain location. The water level is 0 in most places though it can vary (e.g. it's higher near the dam).
{{Note|Some small water areas within parts of the city do not count as water to be used with this function. For example, the shallow water area in Northwest San Fierro.}}

==Syntax==
<syntaxhighlight lang="lua">
float getWaterLevel ( float posX, float posY, float posZ [ , bool bCheckWaves = false ] )
</syntaxhighlight>
<syntaxhighlight lang="lua">
float getWaterLevel ( water theWater )
</syntaxhighlight>

===Required Arguments===
*'''x:''' The X axis position
*'''y:''' The Y axis position
*'''z:''' The Z axis position

''or:''
*'''theWater:''' the water element

===Optional Arguments===
*'''bCheckWaves''' Include the water levels of waves in the ocean, lakes and ...

===Returns===
Returns an ''integer'' of the water level if the [[localPlayer]]/position is near the water (-3 to 20 on the Z coordinate) else ''false'' if there's no water near the [[localPlayer]]/position.

==Example==
This example will tell you what's the water level where the specified player is located.
<syntaxhighlight lang="lua">
function scriptGetLevel ( command, playername ) --when getlevel is called
local thePlayer = getPlayerFromName ( playername ) --get the player from nickname
if ( thePlayer ~= false ) then --if there is a player from the nickname
local x, y, z = getElementPosition ( thePlayer ) -- get his position
local level = getWaterLevel ( x, y, z )
if level then -- if it's not false
level = z - level -- calculate how far away is he from the water
outputChatBox( "You are " .. level .. " units away from the water!", source )
else outputChatBox ( "There's no sign of water" )
end
else outputChatBox ( "Player does not exist" )
end
end
addCommandHandler( "getlevel", scriptGetLevel ) -- add a command "getloc" which
</syntaxhighlight>

==See Also==
{{Client water functions}}

DxDrawImage

2014-11-18T08:29:54Z

LuXorioN: Fixxed Bot Section

__NOTOC__
{{Client function}}

Draws an image on the screen for a single frame. In order for the image to stay visible continuously, you need to call this function with the same parameters on each frame update (see [[onClientRender]]).<br/>
Image files should ideally have dimensions that are a power of two, to prevent possible blurring.<br/>
<b>Power of two: 2px, 4px, 8px, 16px, 32px, 64px, 128px, 256px, 512px, 1024px...</b>
{{Note|To help prevent edge artifacts when drawing textures, set '''textureEdge''' to '''"clamp"''' when calling [[dxCreateTexture]]}}
==Syntax==
<syntaxhighlight lang="lua">
bool dxDrawImage ( float posX, float posY, float width, float height, mixed image [, float rotation = 0, float rotationCenterOffsetX = 0, float rotationCenterOffsetY = 0, int color = tocolor(255,255,255,255), bool postGUI = false ] )
</syntaxhighlight>

===Required Arguments===
*'''posX:''' the absolute X coordinate of the top left corner of the image
*'''posY:''' the absolute Y coordinate of the top left corner of the image
*'''width:''' the absolute width of the image
*'''height:''' the absolute height of the image
*'''image:''' Either a [[material]] element or a [[filepath]] of the image which is going to be drawn. (.dds images are also supported). Image files should ideally have dimensions that are a power of two, to prevent possible blurring.

===Optional Arguments===
*'''rotation:''' the rotation, in degrees for the image.
*'''rotationCenterOffsetX:''' the absolute X offset from the image center for which to rotate the image from.
*'''rotationCenterOffsetY:''' the absolute Y offset from the image center for which to rotate the image from.
*'''color:''' Tints the image with a value produced by [[tocolor]] or hexadecimal number in format: 0xAARRGGBB (RR = red, GG = green, BB = blue, AA = alpha).
*'''postgui :''' A bool representing whether the image should be drawn on top of or behind any ingame GUI (rendered by CEGUI).

===Returns===
Returns ''true'' if successful, ''false'' otherwise.

==Example==
Example of a pendulum swinging from the top of the screen, made using dxDrawImage.
<syntaxhighlight lang="lua">
local screenWidth,screenHeight = guiGetScreenSize() -- Get screen resolution.

function renderDisplay ( )
local seconds = getTickCount() / 1000
local angle = math.sin(seconds) * 80
-- This will draw the graphic file 'arrow.png' at the top middle of the screen
-- using the size of 100 pixels wide, and 240 pixels high.
-- The center of rotation is at the top of the image.
dxDrawImage ( screenWidth/2 - 50, 0, 100, 240, 'arrow.png', angle, 0, -120 )
end

function HandleTheRendering ( )
addEventHandler("onClientRender", getRootElement(), renderDisplay) -- Keep everything visible with onClientRender.
end
addEventHandler("onClientResourceStart",resourceRoot, HandleTheRendering)
</syntaxhighlight>

==See Also==
{{Drawing_functions}}

FxAddSparks

2014-11-18T08:29:27Z

LuXorioN: Fixxed Bot Section

__NOTOC__
{{Client function}}
[[Image:Fxsparks.png|thumb|200px|Sparks]]
Creates a number of sparks originating from a point or along a line.

==Syntax==
<syntaxhighlight lang="lua">
bool fxAddSparks ( float posX, float posY, float posZ, float dirX, float dirY, float dirZ, [float force=1, int count=1, float acrossLineX=0, float acrossLineY=0, float acrossLineZ=0, bool blur=false, float spread=1, float life=1] )
</syntaxhighlight>

===Required Arguments===
*'''posX, posY, posZ:''' the world coordinates where the sparks originate.
*'''dirX, dirY, dirZ:''' a direction vector indicating where the sparks fly to. The longer this vector is, the faster the sparks fly.

===Optional Arguments===
{{OptionalArg}}
*'''force:''' speed factor: the higher this value, the faster and further the sparks fly.
*'''count:''' the number of effects to create.
*'''acrossLineX, acrossLineY, acrossLineZ:''' a vector starting at the '''pos''' coordinates. If specified, the sparks will be created along a line going from '''pos''' to '''pos - acrossLine'''. If not specified, all sparks originate from the point at '''pos'''.
*'''blur:''' if ''false'', creates standard bullet impact-like sparks. If ''true'', adds motion blur to the sparks.
*'''spread:''' determines how strongly the particles deviate from each other. With low values the particles will stay quite close together, high values will make them fly in all directions. Also affects their speed.
*'''life:''' the higher this value, the longer the sparks survive before they disappear.

===Returns===
Returns a true if the operation was successful, false otherwise.

==Example==
<section name="Client" class="client" show="true">
This example will add Fire Bins to all locations added in the table.

<syntaxhighlight lang="lua">
fires = {
{0, 0, 3} --Middle of SA
}

for i = 1, #fires do
bin = createObject(1362, fires[i][1], fires[i][2], fires[i][3]-0.5)
torch = createObject(3461, fires[i][1]-0.1, fires[i][2]-0.1, fires[i][3]-2)
light = createMarker(fires[i][1], fires[i][2], fires[i][3]+0.2, "corona", 1, 255, 170, 0, 80, root)
fireCol = createColSphere(fires[i][1], fires[i][2], fires[i][3]+0.5, 0.8)
setTimer(fxAddSparks, math.random(4000, 5000), 0, fires[i][1]+math.random(0.1, 0.3), fires[i][2]+math.random(0.1, 0.2), fires[i][3]+0.2, 1, 1, 1)

addEventHandler("onClientColShapeHit", fireCol,
function(theElement)
if (getElementType(theElement) == "player") then
setPedOnFire(theElement, true)
end
end)

end
</syntaxhighlight>
</section>

==See Also==
{{Client Effects functions}}

ProcessLineOfSight

2014-11-18T08:28:48Z

LuXorioN: Fixxed Bot Section

{{Client function}}
__NOTOC__
This function casts a ray between two points in the world, and tells you information about the point that was hit, if any. The two positions '''must''' be within the local player's draw distance as the collision data is not loaded outside this area, and the call will just fail as if the ray didn't hit.

This function is relatively expensive to call, so over use of this in scripts may have a detrimental effect on performance.

This function is useful for checking for collisions and for editor-style scripts. If you wish to find what element is positioned at a particular point on the screen, use this function combined with [[getWorldFromScreenPosition]]. If you wish to just know if something is hit, and don't care about what or where was hit, use [[isLineOfSightClear]].

==Syntax==
Return values labelled for ease of reference.
<syntaxhighlight lang="lua">
bool float float float element float float float int float int int float float float float float float int processLineOfSight ( float startX, float startY, float startZ, float endX, float endY, float endZ, [ bool checkBuildings = true, bool checkVehicles = true, bool checkPlayers = true, bool checkObjects = true, bool checkDummies = true, bool seeThroughStuff = false, bool ignoreSomeObjectsForCamera = false, bool shootThroughStuff = false, element ignoredElement = nil, bool includeWorldModelInformation = false, bool bIncludeCarTyres ] )
</syntaxhighlight>

===Required Arguments===
*'''startX:''' The start ''x'' position
*'''startY:''' The start ''y'' position
*'''startZ:''' The start ''z'' position
*'''endX:''' The end ''x'' position
*'''endY:''' The end ''y'' position
*'''endZ:''' The end ''z'' position

===Optional Arguments===
{{OptionalArg}}
*'''checkBuildings:''' Allow the line of sight to be blocked by GTA's internally placed buildings, i.e. the world map.
*'''checkVehicles:''' Allow the line of sight to be blocked by [[Vehicle|vehicles]].
*'''checkPlayers:''' Allow the line of sight to be blocked by [[Player|players]].
*'''checkObjects:''' Allow the line of sight to be blocked by [[Object|objects]].
*'''checkDummies:''' Allow the line of sight to be blocked by GTA's internal dummies. These are not used in the current MTA version so this argument can be set to ''false''.
*'''seeThroughStuff:''' Allow the line of sight to be blocked by translucent game objects, e.g. glass.
*'''ignoreSomeObjectsForCamera:''' Allow the line of sight to pass through objects that have (K) property enabled in "object.dat" data file. (i.e. Most dynamic objects like boxes or barrels)
*'''shootThroughStuff:''' Allow the line of sight to be blocked by things that can be shot through
*'''ignoredElement:''' Allow the line of sight to pass through a certain specified element. This is usually set to the object you are tracing from so it does not interfere with the results.
*'''includeWorldModelInformation :''' Include the results of hitting a world model.
*'''bIncludeCarTyres :''' Includes car tyre hits.

===Returns===
*'''hit:''' ''true'' if there is a collision, ''false'' otherwise
The other values are only filled if there is a collision, they contain ''nil'' otherwise
*'''hitX, hitY, hitZ:''' collision position
*'''hitElement:''' the MTA element hit if any, ''nil'' otherwise
*'''normalX, normalY, normalZ:''' the normal of the surface hit
*'''material:''' an integer representing the [[Material IDs|GTASA material ID]] of the surface hit when applicable (world, objects)
*'''lighting:''' a float between 0 (fully dark) and 1 (bright) representing the amount of light that the hit building surface will transfer to peds or vehicles that are in contact with it. The value can be affected by the game time of day, usually with a lower (darker) value being returned during the night.
*'''piece:''' an integer representing the part of the element hit if hitElement is a vehicle or a ped/player, ''0'' otherwise.
**For a ped/player, piece represents the body part hit:
{{BodyParts}}
**For vehicles, piece represents the vehicle part hit:
{{VehicleParts}}
*'''worldModelID:''' If includeWorldModelInformation was set to ''true'' and a world model was hit, this will contain the model ID.
*'''worldModelPositionX,Y,Z:''' If worldModelID is set, this will contain the world model position.
*'''worldModelRotationX,Y,Z:''' If worldModelID is set, this will contain the world model rotation.
*'''worldLODModelID:''' If worldModelID is set, this will contain the LOD model ID if applicable.

==Examples==
This example shows how you can tell what position and element the camera is looking at, up to 50 units away.
<syntaxhighlight lang="lua">
local w, h = guiGetScreenSize ()
local tx, ty, tz = getWorldFromScreenPosition ( w/2, h/2, 50 )
local px, py, pz = getCameraMatrix()
hit, x, y, z, elementHit = processLineOfSight ( px, py, pz, tx, ty, tz )
if hit then
outputChatBox ( "Looking at " .. x .. ", " .. y .. ", " .. z )
if elementHit then
outputChatBox ( "Hit element " .. getElementType(elementHit) )
end
end
</syntaxhighlight>
This example shows how you can get the surface type a vehicle is on. This is useful if you want to do a script to dirt cars over time. Please note that this function doesn't count if the vehicle is streamed in or not, so expect this function to fail or return incorrect values on unloaded vehicles.
<syntaxhighlight lang="lua">
function getSurfaceVehicleIsOn(vehicle)
if isElement(vehicle) and (isVehicleOnGround(vehicle) or isElementInWater(vehicle)) then -- Is an element and is touching any surface?
local cx, cy, cz = getElementPosition(vehicle) -- Get the position of the vehicle
local gz = getGroundPosition(cx, cy, cz) - 0.001 -- Get the Z position of the ground the vehicle is on (-0.001 because of processLineOfSight)
local hit, _, _, _, _, _, _, _, surface = processLineOfSight(cx, cy, cz, cx, cy, gz) -- This will get the material of the thing the car is standing on
if hit then
return surface -- If everything is correct, stop executing this function and return the surface type
end
end
return false -- If something isn't correct, return false
end
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.04273|''bIncludeCarTyres'' argument added}}
{{ChangelogItem|1.3.0-9.04273|''worldModelID'' return value fixed}}
{{ChangelogItem|1.3.0-9.04405|''lighting'' return value fixed}}

==See Also==
{{Client world functions}}

IsLineOfSightClear

2014-11-18T08:24:00Z

LuXorioN: Fixxed Bot Section

__NOTOC__
{{Client function}}
This function checks if there are obstacles between two points of the game world, optionally ignoring certain kinds of elements. Use [[processLineOfSight]] if you want more information about what the ray hits.

==Syntax==
<syntaxhighlight lang="lua">
bool isLineOfSightClear ( float startX, float startY, float startZ, float endX, float endY, float endZ, [ bool checkBuildings = true, bool checkVehicles = true, bool checkPeds = true, bool checkObjects = true, bool checkDummies = true, bool seeThroughStuff = false, bool ignoreSomeObjectsForCamera = false, element ignoredElement = nil ] )
</syntaxhighlight>

===Required Arguments===
*'''startX:''' The first point's world X coordinate.
*'''startY:''' The first point's world Y coordinate.
*'''startZ:''' The first point's world Z coordinate.
*'''endX:''' The second point's world X coordinate.
*'''endY:''' The second point's world Y coordinate.
*'''endZ:''' The second point's world Z coordinate.

===Optional Arguments===
{{OptionalArg}}
*'''checkBuildings:''' Allow the line of sight to be blocked by GTA's internally placed buildings, i.e. the world map.
*'''checkVehicles:''' Allow the line of sight to be blocked by [[Vehicle|vehicles]].
*'''checkPeds:''' Allow the line of sight to be blocked by peds, i.e. [[Player|players]].
*'''checkObjects:''' Allow the line of sight to be blocked by [[Object|objects]].
*'''checkDummies:''' Allow the line of sight to be blocked by GTA's internal dummies. These are not used in the current MTA version so this argument can be set to ''false''.
*'''seeThroughStuff:''' Allow the line of sight to be blocked by translucent game objects, e.g. glass.
*'''ignoreSomeObjectsForCamera:''' Allow the line of sight to be blocked by certain objects.
*'''ignoredElement:''' Allow the line of sight to pass through a certain specified element.

===Returns===
Returns ''true'' if the line between the specified points is clear, ''false'' if there's an obstacle or if invalid parameters are passed.

==Example==
<section name="Client" class="client" show="false">
isLineOfSightClear is the economical way to cast a ray in the world.
This example demonstrates how you can easily implement basic NPC behaviour such as jumping obstacles. A 3D line is drawn connecting the two points in the ray.
<syntaxhighlight lang="lua">
local t_Data = {}

local function updateNPC ()
if (not isElement(t_Data.ped) or (getElementHealth(t_Data.ped) == 0)) then
return toggleNPCFollower ()
end

local t_PlayerPos = {getElementPosition(localPlayer)}
local t_PedPos = {getElementPosition(t_Data.ped)}

local intDistance = getDistanceBetweenPoints3D (t_PedPos[1], t_PedPos[2], t_PedPos[3], unpack(t_PlayerPos))
if (intDistance < 4) then
setPedControlState (t_Data.ped, 'forwards', false)
return true
end

-- Calculate the rotation between ped and player position
local intPedRot = -math.deg (math.atan2(t_PlayerPos[1] - t_PedPos[1], t_PlayerPos[2] - t_PedPos[2]))
if intPedRot < 0 then intPedRot = intPedRot + 360 end;

setElementRotation (t_Data.ped, 0, 0, intPedRot, 'default', true)
-- At this point we know that the ped needs to move it
setPedControlState (t_Data.ped, 'forwards', true)

local bPathClear = true
local t_Matrix = getElementMatrix (t_Data.ped)

-- Calculate a position 1m ahead of ped
local int_RayX = t_Matrix[2][1] + t_Matrix[4][1]
local int_RayY = t_Matrix[2][2] + t_Matrix[4][2]
local int_RayZ = t_Matrix[2][3] + t_Matrix[4][3]

-- We cast 10 rays 1m ahead of the ped
for i = 1, 10 do
local intSourceX, intSourceY, intSourceZ = t_PedPos[1], t_PedPos[2], t_PedPos[3]

-- The target position height is identical to the center of the ped (1m above ground)
-- We lower this value by 0.5m to detect short obstacles
local intTargetX, intTargetY, intTargetZ = int_RayX, int_RayY, int_RayZ - 0.5 + i*0.2

bPathClear = isLineOfSightClear (intSourceX, intSourceY, intSourceZ, intTargetX, intTargetY, intTargetZ, true, true, false, true)
dxDrawLine3D (intSourceX, intSourceY, intSourceZ, intTargetX, intTargetY, intTargetZ, bPathClear and tocolor(255,255,255,255) or tocolor(255,0,0,255))

if (not bPathClear) then
break
end
end

if (not bPathClear) then
setPedControlState (t_Data.ped, 'jump', true)
else
setPedControlState (t_Data.ped, 'jump', false)
end

if (intDistance > 15) then
setPedControlState (t_Data.ped, 'sprint', true)
else
setPedControlState (t_Data.ped, 'sprint', false)
end
end

function toggleNPCFollower ()
if (t_Data.ped) then
if (t_Data.updateNPCTimer) then
if (isTimer(t_Data.updateNPCTimer)) then
killTimer (t_Data.updateNPCTimer)
end
end
if (isElement(t_Data.ped)) then
destroyElement (t_Data.ped)
end
t_Data.ped = nil
return true
end

local intX, intY, intZ = getElementPosition (localPlayer)
local _, _, intRZ = getElementRotation (localPlayer)
local t_Matrix = getElementMatrix (localPlayer)

-- Calculate a position 4m behind local player
local intPedX = -4 * t_Matrix[2][1] + t_Matrix[4][1]
local intPedY = -4 * t_Matrix[2][2] + t_Matrix[4][2]
local intPedZ = -4 * t_Matrix[2][3] + t_Matrix[4][3]

t_Data.ped = createPed (0, intPedX, intPedY, intPedZ, intRZ)
t_Data.updateNPCTimer = setTimer (updateNPC, 50, 0)
end
addCommandHandler ('npc', toggleNPCFollower)
</syntaxhighlight>
</section>

==See Also==
{{Client world functions}}

CreateBlipAttachedTo

2014-11-18T08:21:40Z

LuXorioN: Fixxed Bot Section

__NOTOC__
{{Server client function}}
This function creates a [[blip]] that is attached to an [[element]]. This blip is displayed as an icon on the client's radar and will 'follow' the element that it is attached to around.

==Syntax==
{{OOP|This function instantiates a class|createAttachedTo}}
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
blip createBlipAttachedTo ( element elementToAttachTo, [int icon=0, int size=2, int r=255, int g=0, int b=0, int a=255, int ordering=0, float visibleDistance=99999.0, visibleTo = getRootElement()] )
</syntaxhighlight>

===Required Arguments===
*'''elementToAttachTo:''' The [[element]] to attach the marker to.

===Optional Arguments===
{{OptionalArg}}
*'''icon:''' The icon that the radar blips should be. Valid values are:
{{Blip_Icons}}
*'''size:''' The size of the radar blip. Only applicable to the ''Marker'' icon. Default value is 2.
*'''r:''' The amount of red in the blip's color (0 - 255). Only applicable to the ''Marker'' icon. Default is 255.
*'''g:''' The amount of green in the blip's color (0 - 255). Only applicable to the ''Marker'' icon. Default is 0.
*'''b:''' The amount of blue in the blip's color (0 - 255). Only applicable to the ''Marker'' icon. Default is 0.
*'''a:''' The amount of alpha in the blip's color (0 - 255). Only applicable to the ''Marker'' icon. Default is 255.
{{New feature/item|3|1.0||
*'''ordering:''' This defines the blip's Z-level ordering (-32768 - 32767). Default is 0.
*'''visibleDistance:''' The maximum distance from the camera at which the blip is still visible (0 - 65535)
}}
*'''visibleTo:''' What elements can see the blip. Defaults to visible to everyone. See [[visibility]].
</section>
<section name="Client" class="client" show="false">
<syntaxhighlight lang="lua">
blip createBlipAttachedTo ( element elementToAttachTo, [int icon=0, int size=2, int r=255, int g=0, int b=0,
int a=255, int ordering=0, float visibleDistance=99999.0] )
</syntaxhighlight>

===Required Arguments===
*'''elementToAttachTo:''' The [[element]] to attach the marker to.

===Optional Arguments===
{{OptionalArg}}
*'''icon:''' The icon that the radar blips should be. Valid values are:
{{Blip_Icons}}
*'''size:''' The size of the radar blip. Only applicable to the ''Marker'' icon. Default is 2.
*'''r:''' The amount of red in the blip's color (0 - 255). Only applicable to the ''Marker'' icon. 'Default is 255.
*'''g:''' The amount of green in the blip's color (0 - 255). Only applicable to the ''Marker'' icon. Default is 0.
*'''b:''' The amount of blue in the blip's color (0 - 255). Only applicable to the ''Marker'' icon. Default is 0.
*'''a:''' The amount of alpha in the blip's color (0 - 255). Only applicable to the ''Marker'' icon. Default is 255.
{{New feature/item|3|1.0||
*'''ordering:''' This defines the blip's Z-level ordering (-32768 - 32767). Default is 0.
*'''visibleDistance:''' The maximum distance from the camera at which the blip is still visible
}}
</section>

===Returns===
Returns a [[blip]] if the blip was created succesfully, or ''false'' otherwise.

==Example==
<section name="Server" class="server" show="true">
This example creates a radar blip attached to a random player, visible to everyone. The blip will follow the player around as they move. This could be used for manhunt, to emphasise a random player.
<syntaxhighlight lang="lua">
-- Pick a random player
function setupRandomRobber ()
local myPlayer = getRandomPlayer ()
-- Create a radar blip at the player's position, with a 'cash' icon and only visible to everyone (no 'visibleTo' parameter)
local myBlip = createBlipAttachedTo ( myPlayer, 52 )
end
</syntaxhighlight>
</section>

==See Also==
{{Blip_functions}}

SetWaterLevel

2014-11-18T08:20:48Z

LuXorioN: Fixxed Bot Section

__NOTOC__
{{Server client function}}

Sets the height of some or all the water in the game world.
{{Note|When the water level is 0, the standard GTA rendering is performed so that water is visible when viewed through translucent surfaces, such as vehicle windows. However, some MTA custom objects placed underwater will appear in front of the water. Setting the water level to any non-zero value (i.e. setWaterLevel(0.001) ) forces alternative rendering and MTA custom objects placed underwater will be drawn correctly.}}
==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
bool setWaterLevel ( [water theWater,] float level )
</syntaxhighlight>
<syntaxhighlight lang="lua">
bool setWaterLevel ( float level [, bool includeWaterFeatures = true, bool includeWaterElements = true ] )
</syntaxhighlight>

===Required Arguments===
*'''level:''' the new Z coordinate of the water surface. All water in the game world is set to this height.

===Optional Arguments===
*'''theWater:''' the water element to change.

''or:''
{{New feature/item|3.0120|1.2||
*'''includeWaterFeatures :''' a boolean indicating whether to also set the level of water features such as ponds and pools.
*'''includeWaterElements :''' a boolean indicating whether to also set the level of all water elements.
}}

===Returns===
Returns ''true'' if successful, ''false'' in case of failure.
</section>

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">bool setWaterLevel ( [float x, float y, float z,] float level )
bool setWaterLevel ( [water theWater,] float level )
bool setWaterLevel ( float level [, bool includeWaterFeatures = true, bool includeWaterElements = true ] )</syntaxhighlight>

===Required Arguments===
*'''level:''' the new Z coordinate of the water surface. If '''x''', '''y''' and '''z''', or '''water''', are specified, the area of water containing that point or corresponding to that water element is changed. Otherwise, all water in the game world is changed.

===Optional Arguments===
*'''x:''' the X coordinate of the point indicating the water area to change.
*'''y:''' the Y coordinate of the point indicating the water area to change.
*'''z:''' the Z coordinate of the point indicating the water area to change. This parameter is reserved and is currently ignored, set it to 0.

''or:''
*'''theWater:''' the water element to change.

''or:''
{{New feature/item|3.0120|1.2||
*'''includeWaterFeatures :''' a boolean indicating whether to also set the level of water features such as ponds and pools.
*'''includeWaterElements :''' a boolean indicating whether to also set the level of all water elements.
}}

===Returns===
Returns ''true'' if successful, ''false'' in case of failure (there is no water at the specified coordinates).
</section>

==Example==
<section name="Client" class="client" show="true">
This example code will slowly drain away all rivers and seas.
<syntaxhighlight lang="lua">
local level = 0

function drainSomeWater()
level = level - 0.01
setWaterLevel ( level )
end
setTimer ( drainSomeWater, 100, 15000 )
</syntaxhighlight>
</section>
<section name="Server" class="server" show="true">
This example code will slowly drain away all rivers and seas.
<syntaxhighlight lang="lua">
local level = 0

function drainSomeWater()
level = level - 0.01
setWaterLevel ( level )
end
setTimer ( drainSomeWater, 100, 15000 )
</syntaxhighlight>

This example code adds a command ''water'' which can be used to change the current water level.
<syntaxhighlight lang="lua">
addCommandHandler ( "water",
function ( thePlayer, command, level )
if level and tonumber ( level ) then -- if we have input something and if it is actually a number value
setWaterLevel ( tonumber( level ) ) -- change the water level
outputChatBox ( "Waterlevel is now: " .. level ) -- send a message to everyone to inform about the change
end
end
)
</syntaxhighlight>
</section>

==Issues==
{{Issues|
{{Issue|7542|Water functions in general do not work outside the -3000 -3000 3000 3000 bounds}}
}}

==See Also==
{{Client water functions}}

SetTrafficLightState

2014-11-18T08:20:00Z

LuXorioN: Fixxed Bot Section

__NOTOC__
{{Server client function}}
Sets the current traffic light state. This state controls the traffic light colors. For instance, state '''1''' will cause the north and south traffic lights to be amber, and the ones left and east will turn red.

==Syntax==
<syntaxhighlight lang="lua">
bool setTrafficLightState ( int state )
</syntaxhighlight>
<syntaxhighlight lang="lua">
bool setTrafficLightState ( string state )
</syntaxhighlight>
<syntaxhighlight lang="lua">
bool setTrafficLightState ( string colorNS, string colorEW )
</syntaxhighlight>

===Required Arguments===
*'''state''': If an integer is provided, the [[Traffic_light_states|state]] you wish to use (possible values: 0-9). Else, one of the following strings:
**'''auto''': Sets the traffic lights default behavior (switches the colors automatically).
**'''disabled''': Turns traffic lights off.
Alternatively, you can provide two string parameters ('''colorNS''' and '''colorEW''') with the colors for north-south and east-west traffic lights respectively. Valid colors are:
*'''green'''
*'''yellow'''
*'''red'''

===Returns===
Returns ''true'' if the state was successfully set, ''false'' otherwise.

==Example==
This example causes all traffic lights to be out of order. (flashing amber)

<syntaxhighlight lang="lua">
function handleTrafficLightsOutOfOrder()
-- See if the lights are currently off
local lightsOff = getTrafficLightState() == 9

if lightsOff then
-- If they're off, turn them on
setTrafficLightState(6)
else
-- If they're on, turn them off
setTrafficLightState(9)
end
end
-- Repeat it every half a second
setTimer(handleTrafficLightsOutOfOrder,500,0)
</syntaxhighlight>

==See Also==
{{World_functions}}

CreateRadarArea

2014-11-18T08:19:15Z

LuXorioN: Fixxed Bot Section

__NOTOC__
{{Server client function}}
This function can be used to create custom radar areas on the radar.

==Syntax==
<syntaxhighlight lang="lua">
radararea createRadarArea ( float leftX, float bottomY, float sizeX, float sizeY, [ int r = 255, int g = 0, int b = 0, int a = 255, element visibleTo = getRootElement() ] )
</syntaxhighlight>

===Required Arguments===
*'''leftX:''' A float representing the left 'x' position of the radar area.
*'''bottomY:''' A float representing the bottom 'y' position of the radar area.
*'''sizeX:''' A float representing the width of the radar area.
*'''sizeY:''' A float representing the height of the radar area.

*'''r:''' An integer representing the amount of red in the color. Maximum value is 255
*'''g:''' An integer representing the amount of green in the color. Maximum value is 255
*'''b:''' An integer representing the amount of blue in the color. Maximum value is 255
*'''a:''' An integer representing the amount of alpha in the color. This allows setting the transparency of the radar area. 255 is opaque and 0 is transparent.

===Optional Arguments===
{{OptionalArg}}
*'''visibleTo:''' An [[element]] that you wish to restrict the [[visibility]] of the radar area to. (Server function only)

==Example==
<section name="Server" class="server" show="true">
This example creates a radar area for the King of the hill script, and a colsquare. When the player enters the radar area it flashes, and stops flashing when a player leaves it.
<syntaxhighlight lang="lua">
-- create our hill area for our gamemode
local hillArea = createColRectangle ( -2171.0678710938, 678.17950439453, 15, 15 )
local hillRadar = createRadarArea ( -2183.5678710938, 705.67950439453, 40, -40, 0, 255, 0, 175 )

-- add hill_Enter as a handler for when a player enters the hill area
function hill_Enter ( thePlayer, matchingDimension )
-- announce to everyone that the player entered the hill
if (getElementType(thePlayer) == "player") then
outputChatBox( getPlayerName(thePlayer) .. " entered the zone!", getRootElement(), 255, 255, 109 )
setRadarAreaFlashing ( hillRadar, true )
end
end
addEventHandler ( "onColShapeHit", hillArea, hill_Enter )

-- add hill_Enter as a handler for when a player leaves the hill area
function hill_Exit ( thePlayer, matchingDimension )
-- check if the player is not dead
if (getElementType(thePlayer) == "player") then
if isPedDead ( thePlayer ) ~= true then
-- if he was alive, announce to everyone that the player has left the hill
outputChatBox ( getPlayerName(thePlayer) .. " left the zone!", getRootElement(), 255, 255, 109 )
setRadarAreaFlashing ( hillRadar, false )
end
end
end
addEventHandler ( "onColShapeLeave", hillArea, hill_Exit )
</syntaxhighlight>
</section>

==See Also==
{{Radar area_functions}}

InterpolateBetween

2014-11-18T08:18:33Z

LuXorioN: Fixxed Bot Section

__NOTOC__
{{Server client function}}

Interpolates a 3D Vector between a source value and a target value using either linear interpolation or any other [[Easing|easing function]].
It can also be used to interpolate 2D vectors or scalars by only setting some of the x, y, z values and putting 0 to the others.

==Syntax==
<syntaxhighlight lang="lua">
float float float interpolateBetween ( float x1, float y1, float z1, float x2, float y2, float z2, float fProgress, string strEasingType, [ float fEasingPeriod, float fEasingAmplitude, float fEasingOvershoot ] )
</syntaxhighlight>

===Required Arguments===
*'''x1, y1, z1:''' 3D coordinates of source vector/value
*'''x2, y2, z2:''' 3D coordinates of target vector/value
*'''fProgress:''' float between 0 and 1 indicating the interpolation progress (0 at the beginning of the interpolation, 1 at the end).
*'''strEasingType:''' the [[Easing|easing function]] to use for the interpolation

===Optional Arguments===
*'''fEasingPeriod:''' the period of the [[Easing|easing function]] (only some easing functions use this parameter)
*'''fEasingAmplitude:''' the amplitude of the [[Easing|easing function]] (only some easing functions use this parameter)
*'''fEasingOvershoot:''' the overshoot of the [[Easing|easing function]] (only some easing functions use this parameter)

===Returns===
Returns ''x, y, z'' the interpolated 3D vector/value if successful, ''false'' otherwise (error in parameters).
As mentioned before, interpolateBetween can be used on 2D vectors or scalars in which case only some (x, y or just x) of the returned values are to be used (cf. alpha interpolation in marker example or size interpolation in window example).

== Examples ==
The examples below are only clientside examples even though the function can be used on both sides. Indeed it makes more sense to use it with onClientRender/onClientPreRender but the freedom is given to use it in any other context.
<section name="Client" class="client" show="true">
This clientside example uses interpolateBetween to create position and color interpolation(with effect) on a marker.
The command to test it is "/marker".
The position is interpolated with "OutBounce" as strEasingType to make the marker bounce off the ground and "Linear" interpolation for the color.
<syntaxhighlight lang="lua">
local g_Marker = nil
addCommandHandler("marker",
function ()
if g_Marker then return end

local x, y, z = getElementPosition(getLocalPlayer())
z = z - 1

g_Marker = {}
g_Marker.startPos = {x, y, z + 5}
g_Marker.startTime = getTickCount()
g_Marker.startColor = {255, 0, 0, 0}
g_Marker.endPos = {x, y, z}
g_Marker.endTime = g_Marker.startTime + 2000
g_Marker.endColor = {0, 0, 255, 255}

local x, y, z = unpack(g_Marker.startPos)
local r, g, b, a = unpack(g_Marker.startColor)
g_Marker.marker = createMarker(x, y, z, "cylinder", 1, 255, r, g, b, a)

addEventHandler("onClientRender", getRootElement(), popMarkerUp)
end)

function popMarkerUp()
local now = getTickCount()
local elapsedTime = now - g_Marker.startTime
local duration = g_Marker.endTime - g_Marker.startTime
local progress = elapsedTime / duration

local x1, y1, z1 = unpack(g_Marker.startPos)
local x2, y2, z2 = unpack(g_Marker.endPos)
local x, y, z = interpolateBetween (
x1, y1, z1,
x2, y2, z2,
progress, "OutBounce")

setElementPosition(g_Marker.marker, x, y, z)

local r1, g1, b1, a1 = unpack(g_Marker.startColor)
local r2, g2, b2, a2 = unpack(g_Marker.endColor)
local r, g, b = interpolateBetween (
r1, g1, b1,
r2, g2, b2,
progress, "Linear")
local a = interpolateBetween (
a1, 0, 0,
a2, 0, 0,
progress, "Linear")

setMarkerColor(g_Marker.marker , r, g, b, a)

if now >= g_Marker.endTime then
removeEventHandler("onClientRender", getRootElement(), popMarkerUp)
setTimer(
function ()
destroyElement(g_Marker.marker)
g_Marker = nil
end, 3000, 1)
end
end
</syntaxhighlight>
</section>

<section name="Client" class="client" show="true">
This clientside example uses interpolateBetween to create size and position interpolation (with effect) on a gui-window.
The command to test it is "/window".
When the window pops up it uses "OutElastic" as the strEasingType to create the bouncing/elastic effect.
When it fades away, it uses "InQuad" to have an accelerating fading.
<syntaxhighlight lang="lua">
local g_Window = nil
addCommandHandler("window",
function ()
if g_Window then return end

g_Window = {}

local screenWidth, screenHeight = guiGetScreenSize()
g_Window.windowWidth, g_Window.windowHeight = 400, 315
local left = screenWidth/2 - g_Window.windowWidth/2
local top = screenHeight/2 - g_Window.windowHeight/2

g_Window.window = guiCreateWindow(left, top, g_Window.windowWidth, g_Window.windowHeight, "Interpolation on GUI", false)

g_Window.closeBtn = guiCreateButton(320, 285, 75, 23, "Close", false, g_Window.window)

guiWindowSetSizable(g_Window.window, false)
guiWindowSetMovable(g_Window.window, false)
guiSetEnabled(g_Window.window, false)
guiSetVisible(g_Window.window, false)

g_Window.startTime = getTickCount()
g_Window.startSize = {0, 0}
g_Window.endSize = {g_Window.windowWidth, g_Window.windowHeight}
g_Window.endTime = g_Window.startTime + 1000
addEventHandler("onClientRender", getRootElement(), popWindowUp)
end)

function on_closeBtn_clicked(button, state, absoluteX, absoluteY)
if (button ~= "left") or (state ~= "up") then
return
end

if not g_Window then return end

showCursor(false)
guiSetEnabled(g_Window.window, false)
guiWindowSetMovable(g_Window.window, false)

local screenWidth, screenHeight = guiGetScreenSize()
local posX, posY = guiGetPosition(g_Window.window, false)

g_Window.startTime = getTickCount()
g_Window.startSize = {g_Window.windowWidth, g_Window.windowHeight}
g_Window.startCenter =
{
posX + g_Window.windowWidth/2,
posY + g_Window.windowHeight/2,
}

g_Window.endSize = {0, 0}
g_Window.endTime = g_Window.startTime + 1000
g_Window.endCenter =
{
screenWidth,
screenHeight
}

addEventHandler("onClientRender", getRootElement(), popWindowDown)
end

function popWindowUp()
local now = getTickCount()
local elapsedTime = now - g_Window.startTime
local duration = g_Window.endTime - g_Window.startTime
local progress = elapsedTime / duration

local width, height, _ = interpolateBetween (
g_Window.startSize[1], g_Window.startSize[2], 0,
g_Window.endSize[1], g_Window.endSize[2], 0,
progress, "OutElastic")

guiSetSize(g_Window.window, width, height, false)

local screenWidth, screenHeight = guiGetScreenSize()
guiSetPosition(g_Window.window, screenWidth/2 - width/2, screenHeight/2 - height/2, false)

if not guiGetVisible(g_Window.window) then
guiSetVisible(g_Window.window, true)
guiBringToFront(g_Window.window)
end

if now >= g_Window.endTime then
guiSetEnabled(g_Window.window, true)

guiBringToFront(g_Window.window)
removeEventHandler("onClientRender", getRootElement(), popWindowUp)
addEventHandler("onClientGUIClick", g_Window.closeBtn, on_closeBtn_clicked, false)
showCursor(true)
guiWindowSetMovable(g_Window.window, true)
end
end

function popWindowDown()
local now = getTickCount()
local elapsedTime = now - g_Window.startTime
local duration = g_Window.endTime - g_Window.startTime
local progress = elapsedTime / duration

local width, height, _ = interpolateBetween (
g_Window.startSize[1], g_Window.startSize[2], 0,
g_Window.endSize[1], g_Window.endSize[2], 0,
progress, "InQuad")

guiSetSize(g_Window.window, width, height, false)

local centerX, centerY, _ = interpolateBetween (
g_Window.startCenter[1], g_Window.startCenter[2], 0,
g_Window.endCenter[1], g_Window.endCenter[2], 0,
progress, "InQuad")

guiSetPosition(g_Window.window, centerX - width/2, centerY - height/2, false)

if now >= g_Window.endTime then
removeEventHandler("onClientRender", getRootElement(), popWindowDown)
destroyElement(g_Window.window)
g_Window = nil
end
end

</syntaxhighlight>
</section>

<section name="Client" class="client" show="true">
This clientside example uses interpolateBetween to create and position interpolation (with effect) on a camera.
The command to test it is "/ccam".
When the camera pops up it uses "OutQuad" as the strEasingType to create the slow down effect.
<syntaxhighlight lang="lua">
local enabled = false

addCommandHandler("ccam", function()
enabled = not enabled
if enabled then
start = getTickCount()
dx, dy, dz, lx, ly, lz = getCameraMatrix()
addEventHandler("onClientPreRender", root, interpolateCam)
else
start = nil
setCameraTarget(localPlayer)
removeEventHandler("onClientPreRender", root, interpolateCam)
end
end)

function interpolateCam()
local now = getTickCount()
local endTime = start + 2000
local elapsedTime = now - start
local duration = endTime - start
local progress = elapsedTime / duration
local px, py, pz = getElementPosition(localPlayer)
local x, y, z = interpolateBetween ( dx, dy, dz, dx+4, dy+4, dz, progress, "OutQuad")
setCameraMatrix(x, y, z, px, py, pz+0.6, 0, 0)
end
</syntaxhighlight>
</section>

==See Also==
{{Utility functions}}

AttachElements

2014-11-18T08:16:22Z

LuXorioN: Fixxed Bot Section

__NOTOC__
{{Server client function}}
This function attaches one element to another, so that the first one follows the second whenever it moves.

If an attempt is made to attach two elements that are already attached the opposite way (eg theElement becomes theAttachToElement and vice versa), the 1st attachment order is automatically detached in favor of the 2nd attachment order. For example, if carA was attached to carB, now carB is attached to carA. Also, an element cannot be attached to two separate elements at one time. For example, two cars can be attached to one single car, but one single car cannot be attached to two separate cars. If you attempt to do this, the existing attachment will automatically be dropped in favor of the new attachment. For example, if carA is asked to attached to carB then carC, it is only attached to carC.

This is not compatible with all elements. The following elements are compatible:
* [[Marker]]s
* [[Blip]]s
* [[Object]]s
* [[Player]]s
* [[Vehicle]]s
* [[Sound]]s
* [[Colshape]]s
* [[Camera]]s
* [[createWeapon|Weapons]]

'''Note:''' The offset coodinates reflect the object space, not the world space. This means that you cannot calculate the exact offsets between two objects by pre-positioning them in the map editor as a reference. Please see [[attachElementsOffsets]] for more details.

'''Note #2:''' Due to a limitation in GTA, unexpected attach rotations may occur if all rotation offsets are non-zero. (i.e. Try to ensure at least one of 'xRotOffset', 'yRotOffset' or 'zRotOffset' is zero)

==Syntax==
<syntaxhighlight lang="lua">
bool attachElements ( element theElement, element theAttachToElement, [ float xPosOffset, float yPosOffset, float zPosOffset, float xRotOffset, float yRotOffset, float zRotOffset ] )
</syntaxhighlight>
{{OOP|This function is also a static function underneath the Element class.|[[element]]:attach||}}

===Required Arguments===
*'''theElement:''' The element to be attached.
*'''theAttachToElement:''' The element to attach the first to.

===Optional Arguments===
{{OptionalArg}}
*'''xPosOffset:''' The x offset, if you want the elements to be a certain distance from one another (default 0).
*'''yPosOffset:''' The y offset (default 0).
*'''zPosOffset:''' The z offset (default 0).
*'''xRotOffset:''' The x rotation offset (default 0).
*'''yRotOffset:''' The y rotation offset (default 0).
*'''zRotOffset:''' The z rotation offset (default 0).

===Returns===
Returns ''true'' if the attaching process was successful, ''false'' otherwise.

==Example==
<section name="Server" class="server" show="true">
'''Example 1:''' This example attaches a marker to the player who steals the Mr. Whoopee:
<syntaxhighlight lang="lua">
-- create the vehicle
local vehicleMrWhoopee = createVehicle ( 423, 237.472, -54.225, 1.518, 0, 354.488, 0 )

function onMrWhoopeeEnter ( thePlayer, seat, jackedPlayer )
outputChatBox ( getPlayerName ( thePlayer ) .. " stole the Whoopee!", getRootElement(), 255, 0, 0 )
-- create the marker to attach
local arrowMarker = createMarker ( 0, 0, 0, "arrow", .75, 255, 0, 0, 170 )
-- attach the marker to the player with a vertical offset of 2 units
attachElements ( arrowMarker, thePlayer, 0, 0, 2 )
end

-- attach it to an event
addEventHandler ( "onVehicleEnter", vehicleMrWhoopee, onMrWhoopeeEnter )
</syntaxhighlight>
'''Example 2:''' This function adds a tank on top of a player (for extra defense):
<syntaxhighlight lang="lua">
function tankHat ( source, commandName )
local x, y, z = getElementPosition ( source ) --Get the players position
local tank = createVehicle ( 432, x, y, z + 5 ) --Create a tank
attachElements ( tank, source, 0, 0, 5 ) --Attach the tank to the player.
end
addCommandHandler ( "hat", tankHat )
</syntaxhighlight>
</section>
<section name="Client" class="client" show="false">
'''Example 3:''' This function adds a tank on top of a player (for extra defense), clientside. This means it will be invisible to other players.
<syntaxhighlight lang="lua">
function tankHat ( commandName )
local x, y, z = getElementPosition ( source ) --Get the players position
local tank = createVehicle ( 432, x, y, z + 5 ) --Create a tank
attachElements ( tank, source, 0, 0, 5 ) --Attach the tank to the player.
end
addCommandHandler( "hat", tankHat )
</syntaxhighlight>
</section>

==See Also==
{{Element functions}}

MoveObject

2014-11-18T08:14:28Z

LuXorioN: Fixxed Bot Section

__NOTOC__
{{Server client function}}
This function will smoothly move an object from its current position to a specified rotation and position.

==Syntax==
<syntaxhighlight lang="lua">
bool moveObject ( object theObject, int time, float targetx, float targety, float targetz, [ float moverx, float movery, float moverz, string strEasingType, float fEasingPeriod, float fEasingAmplitude, float fEasingOvershoot ] )
</syntaxhighlight>
{{OOP||[[object]]:move||}}
===Required Arguments===
* '''theObject:''' the object that will be moved.
* '''time:''' the time in milliseconds the object will arrive at the destination.
* '''targetx:''' the X value of the target position
* '''targety:''' the Y value of the target position
* '''targetz:''' the Z value of the target position

===Optional Arguments===
* '''moverx:''' the rotation along the X axis '''relative''' to its current rotation, which is its starting angle.
* '''movery:''' the rotation along the Y axis '''relative''' to its current rotation, which is its starting angle.
* '''moverz:''' the rotation along the Z axis '''relative''' to its current rotation, which is its starting angle.
*'''strEasingType:''' the [[Easing|easing function]] to use for the interpolation (default is "Linear")
*'''fEasingPeriod:''' the period of the [[Easing|easing function]] (only some easing functions use this parameter)
*'''fEasingAmplitude:''' the amplitude of the [[Easing|easing function]] (only some easing functions use this parameter)
*'''fEasingOvershoot:''' the overshoot of the [[Easing|easing function]] (only some easing functions use this parameter)

===Returns===
* ''true'' if the function moved the object succesfully.
* ''false'' otherwise.

==Examples ==
<section name="Server" class="server" show="true">
'''Example 1:''' This example moves every object in the game up 100 units in ten seconds.
<syntaxhighlight lang="lua">
allObjects = getElementsByType ( "object" )
for key, theObject in ipairs ( allObjects ) do
local origX, origY, origZ = getElementPosition ( theObject ) --get the origanal position
local newZ = origZ + 100 -- make a new z position
moveObject ( theObject, 10000, origX, origY, newZ ) --move the object to this position in 10 seconds.
end
</syntaxhighlight>
</section>

<section name="Server" class="server" show="true">
'''Example 2:''' This example created a model (of a bed) near a player called ''someguy'', if they exist in the game. It will then move the model towards the player over 3 seconds.
<syntaxhighlight lang="lua">
-- Find a player called 'someguy'
someGuy = getPlayerFromName ( "someguy" )
-- If a player called someguy was found then
if ( someGuy ) then
-- Get the player's position
x, y, z = getElementPosition ( someGuy )
-- Create a bed (1700) object near to the player
bed = createObject ( 1700, x + 5, y, z )
-- Move the bed towards the player over 3 seconds (3000 milliseconds)
moveObject ( bed, 3000, x, y, z )
-- Tell the player in the chat box
outputChatBox ( "Moving a bed towards you!", someGuy )
else
-- Tell everyone that a player called 'someguy' could not be found
outputChatBox ( "Player someguy doesn't exist" )
end
</syntaxhighlight>
</section>

<section name="Server" class="server" show="true">
'''Example 3:''' This example creates a ball moving (in front of CJ's house in Grove Street) using easing functions. Test command is "/smove" for instance "/smove OutBounce". This example is a serverside code but the same could be done clientside (adapting the command handler)
<syntaxhighlight lang="lua">
local START_POS = {2497.203125, -1672.4864501953, 12.640947341919}
local STOP_POS = {2480.2595214844, -1666.521484375, 12.640114784241}
local MOTION_DURATION = 5000
local WAIT_DURATION = 1000

addCommandHandler("smove",
function (player, cmd, strEasingType, period, amplitude, overshoot)
local x, y, z = unpack(START_POS)
local object = createObject(1598, x, y, z)
x, y, z = unpack(STOP_POS)

period = period or 0.3
amplitude = amplitude or 1.0
overshoot = overshoot or 1.70158

outputChatBox(string.format("Server Easing %s %s %s %s", strEasingType, tostring(period), tostring(amplitude), tostring(overshoot)))
moveObject(object, MOTION_DURATION, x, y, z, 0, 0, 360, strEasingType, period, amplitude, overshoot)
setTimer(destroyElement, MOTION_DURATION+WAIT_DURATION, 1, object)
end)
</section>

<section show="true">
'''Example 4:''' This example move gate with easing.
<syntaxhighlight lang="lua">
local x,y,z = 2096.3, 1721, 12.7
local easing = "OutBounce"
local time = 2000
local gate = createObject(980, x,y,z, 0, 0, 63)
local marker = createMarker(x,y,z, "cylinder", 12, 0, 0, 0, 0)

function moveGate(hitPlayer, matchingDimension)
moveObject(gate, time, x+4.9, y+9.6, z, 0, 0, 0, easing)
end
addEventHandler("onMarkerHit", marker, moveGate)

function moveBack()
moveObject(gate, time, x, y, z, 0, 0, 0, easing)
end
addEventHandler("onMarkerLeave", marker, moveBack)
</syntaxhighlight>
</section>

==See Also==
{{Object functions}}

BanPlayer

2014-11-18T08:11:41Z

LuXorioN: /* Syntax */

__NOTOC__
{{Server function}}
{{New feature|3|1.0|
This function will ban the specified player by either IP, [[serial]] or username
}}

{{Deprecated_feature|3|1.0|
This function will ban the specified player from the server by IP.
}}

==Syntax==
{{New feature|3|1.0|
<syntaxhighlight lang="lua">
ban banPlayer ( player bannedPlayer, [ bool IP = true, bool Username = false, bool Serial = false, player responsiblePlayer = nil, string reason = nil, int seconds = 0 ] )
</syntaxhighlight>
}}

{{Deprecated_feature|3|1.0|
<syntaxhighlight lang="lua">
bool banPlayer ( player bannedPlayer , [ element responsibleElement, string reason ] )
</syntaxhighlight>
}}
{{OOP||[[player]]:ban||}}
===Required Arguments===
*'''bannedPlayer:''' The player that will be banned from the server.

===Optional Arguments===
{{OptionalArg}}
{{New feature|3|1.0|
*'''IP:''' Will player be banned by IP?
*'''Username:''' Will player be banned by username?
*'''Serial:''' Will player be banned by serial?

:'''Note:''' to ban by username or serial, ''verifyserials'' must be enabled in the server configuration file.

}}
*'''responsibleElement:''' The element that is responsible for banning the player. This can be a player or the root ([[getRootElement]]()) (Maximum 30 characters if using a string).
*'''reason:''' The reason the player will be banned from the server.
*'''seconds:''' The amount of seconds the player will be banned from the server for. This can be 0 for an infinite amount of time.

===Returns===
{{Deprecated_feature|3|1.0|
Returns ''true'' if the player was banned succesfully, ''false'' if invalid arguments are specified.
}}

{{New feature|3|1.0|
Returns a [[ban]] object if banned successfully, or ''false'' if unsuccessful.
}}

==Example==
This example lets a player ban anyone if he has ACL rights.
<syntaxhighlight lang="lua">
--Add the "ban" command handler
-- Example with the player
function banPlayerCommand ( theClient, commandName, bannedName, reason )

-- Give the player a nice error if he doesn't have rights
if ( hasObjectPermissionTo ( theClient, "function.banPlayer" ) ) then
--Get player element from the name
local bannedPlayer = getPlayerFromName ( bannedName )

--Ban the player
banPlayer ( bannedPlayer, theClient, reason )
outputChatBox ( "ban: " .. bannedName .. " successfully banned", theClient )

else
outputChatBox ( "ban: You don't have enough permissions", theClient )
end

end
addCommandHandler ( "ban", banPlayerCommand )

-- Example function with the root element. Here you would pass a player element to the function.
function banCheater(theCheater)
banPlayer(theCheater, getRootElement(), "You are banned because of cheating.")
end
</syntaxhighlight>

This example is Firewall Account Player by serial on Login
<syntaxhighlight lang="lua">
Firewall =
{
[ 'AccountName' ] = 'SerialPlayer',
[ '3ash8' ] = '9C9F3B55D9D7BB7135FF274D3BF444E4',
[ 'test5' ] = '1D6F76CF8D7193792D13789849498452',
}

addEventHandler ( 'onPlayerLogin', getRootElement ( ),
function ( _, theCurrentAccount )
local Serial = Firewall[getAccountName(theCurrentAccount)]
if ( Serial ) then
if Serial ~= getPlayerSerial ( source ) then
banPlayer ( source, false, false, true, getRootElement ( ), 'reason ban' )
end
end
end
)
</syntaxhighlight>

==See Also==
{{Admin_functions}}
[[es:banPlayer]]
[[ru:BanPlayer]]