Multi Theft Auto: Wiki - User contributions [en]

OnClientGUISize

2012-09-29T20:59:19Z

Callum: Minor improvements.

{{Client event}}
__NOTOC__
This event is triggered when the local client resizes a GUI element.

==Parameters==
''None''

==Source==
The [[event system#Event source|source]] of this event is the GUI element that was resized.

==Example==
This example will output the type of GUI element that the client has resized, to the chatbox.
<syntaxhighlight lang="lua">addEventHandler("onClientGUISize",guiRoot,function()
outputChatBox("You have resized a "..getElementType(source)..".",255,255,0)
end)
</syntaxhighlight>

==See Also==
===GUI events===
{{GUI_events}}
===Client event functions===
{{Client_event_functions}}

IsPedDoingGangDriveby

2012-09-29T20:53:15Z

Callum: Modernized the example.

{{Server client function}}
__NOTOC__
This function checks if the ped is in the driveby state.

==Syntax==
<syntaxhighlight lang="lua">
bool isPedDoingGangDriveby ( ped thePed )
</syntaxhighlight>

===Required Arguments===
*'''thePed:''' The [[ped]] element whose state is to be checked.

===Returns===
Returns '''true''' if the driveby state is enabled, '''false''' otherwise.

==Example==
<section name="Client" class="client" show="true">
This example turns on driveby mode when the local player types ''driveby'' in the console.
<syntaxhighlight lang="lua">function setDoingDriveby ( )
-- we check if local player isn't currently doing a gang driveby
if not isPedDoingGangDriveby ( localPlayer ) then
-- if he got driveby mode off, turn it on
setPedWeaponSlot ( localPlayer, 4 )
setPedDoingGangDriveby ( localPlayer, true )
else
-- otherwise, turn it off
setPedWeaponSlot ( localPlayer, 0 )
setPedDoingGangDriveby ( localPlayer, false )
end
end
addCommandHandler ( "driveby", setDoingDriveby )</syntaxhighlight>
</section>

==See Also==
{{Ped functions}}

Modules

2012-09-29T20:49:48Z

Callum: Updated the links structure.

Modules are extensions for Multi Theft Auto's Lua core, allowing the integration and use of custom Lua functions that have been written in C++, and compiled as a DLL or SO file. Modules are commonly used to create functions for such purposes that Multi Theft Auto lacks, such as sockets. All modules listed hereof are not distributed with Multi Theft Auto, and must be manually installed.

==Modules list==
You can view a list of all the documented modules in this wiki [[:Category:Modules|here]].

==Modules SDK==
To be able to create your own modules, you must use the Modules SDK. You can download it from one of the links below - choose a link in accordance with your server's operating system.

* Linux
** [http://files.mtasa.com/apps/1.0/dm/ml_devkit.tar.gz Official]
* Microsoft Windows
** [http://wobzip.org/file/TANPP Mirror (wobzip.org)]
** [http://www.mediafire.com/?b8b3asgegn0xkm4 Mirror (Mediafire)]

===SDK functions===
*Currently in there:
**Base:
***HelloWorld
**MySQL
***MySQLCreate
***MySQLOpen
***MySQLDestroy
***MySQLQuery
***MySQLSafeString

[[Category:Scripting Concepts]]
[[Category:Incomplete]]
[[Category:Modules]]

[[ru:Modules]]

Modules

2012-09-29T20:47:14Z

Callum: Rewritten some of the poor sentance structures.

Modules are extensions for Multi Theft Auto's Lua core, allowing the integration and use of custom Lua functions that have been written in C++, and compiled as a DLL or SO file. Modules are commonly used to create functions for such purposes that Multi Theft Auto lacks, such as sockets. All modules listed hereof are not distributed with Multi Theft Auto, and must be manually installed.

==Modules list==
You can view a list of all the documented modules in this wiki [[:Category:Modules|here]].

==Modules SDK==
To be able to create your own modules, you must use the Modules SDK. You can download it from one of the links below - chose the appropriate one in accordance with your server's operating system.

*[http://files.mtasa.com/apps/1.0/dm/ml_devkit.tar.gz Linux]
*[http://wobzip.org/file/TANPP here] or [http://www.mediafire.com/?b8b3asgegn0xkm4 Microsoft Windows]

===SDK functions===
*Currently in there:
**Base:
***HelloWorld
**MySQL
***MySQLCreate
***MySQLOpen
***MySQLDestroy
***MySQLQuery
***MySQLSafeString

[[Category:Scripting Concepts]]
[[Category:Incomplete]]
[[Category:Modules]]

[[ru:Modules]]

OnElementModelChange

2012-09-29T20:24:24Z

Callum: Grammatical changes.

__NOTOC__
{{Server event}}
{{New feature|3.0120|1.2|
'''Available only in MTA SA 1.2 and onwards'''
}}
This event is triggered when the model of an [[element]] is changed using [[setElementModel]].

==Parameters==
<syntaxhighlight lang="lua">
int oldModel, int newModel
</syntaxhighlight>

* '''oldModel:''' The model of the element beforehand.
* '''newModel:''' The new model of the element.

==Source==
The source of this event is the element that changed its model

==Cancel Effect==
This event doesn't support [[Event system#Canceling|cancellation]].

==Example==
This example sends a message to players when their model changes telling them what the model ID is and was.
<syntaxhighlight lang="lua">
function informPlayerOnModelChange(oldModel, newModel)
if ( getElementType(source) == "player" ) then -- Make sure the element is a player
outputChatBox("Model ID changing from: "..oldModel.." to: "..newModel, source, 0, 255, 0) -- Message for player
end
end
addEventHandler("onElementModelChange", root, informPlayerOnModelChange) -- Bind the event to every element
</syntaxhighlight>

==See Also==
===Element events===
{{Element_events}}
===Event functions===
{{Event_functions}}

CreateWater

2012-09-27T20:13:41Z

Callum: Updated example to use resourceRoot.

__NOTOC__
{{Server client function}}

{{Needs_Checking|Use of bShallow is unknown. There was a stupid note pointing to arc_ and assuming it meant if the water is visible which is not true.}}

Creates an area of [[water]].

The largest possible size of a water area is 5996×5996. Also be aware that the function will change all x and y coordinates you specify into even integer numbers if necessary: this is because of a limitation of San Andreas.

==Syntax==
<syntaxhighlight lang="lua">water createWater ( float x1, float y1, float z1, float x2, float y2, float z2, float x3, float y3, float z3 [, float x4, float y4, float z4 ] [, bool bShallow = false ] )</syntaxhighlight>
[[Image:WaterAreas.jpg|thumb|Example of water quadrant.|284x230px]]

===Required Arguments===
*'''x1, y1, z1:''' position of bottom left (south-west) corner.
*'''x2, y2, z2:''' position of bottom right (south-east) corner.
*'''x3, y3, z3:''' position of top left (north-west) corner.
''Note: Only 3 coords creates a triangle''

===Optional Arguments===
*'''x4, y4, z4:''' position of top right (north-east) corner.
*'''bShallow:''' Need documentation...

===Returns===
Returns a water element if successful, ''false'' otherwise. The water element can be repositioned with [[setElementPosition]] and destroyed with [[destroyElement]].

==Example==
<section name="Client" class="client" show="true">
Example code for creating a water area to cover the entire San Andreas Map (flood the cities). Also, [[setWaterLevel]] is used to raise the existing rivers and lakes.
<syntaxhighlight lang="lua">
-- Setting water properties.
height = 40
SizeVal = 2998
-- Defining variables.
southWest_X = -SizeVal
southWest_Y = -SizeVal
southEast_X = SizeVal
southEast_Y = -SizeVal
northWest_X = -SizeVal
northWest_Y = SizeVal
northEast_X = SizeVal
northEast_Y = SizeVal

-- OnClientResourceStart function that creates the water.
function thaResourceStarting( )
water = createWater ( southWest_X, southWest_Y, height, southEast_X, southEast_Y, height, northWest_X, northWest_Y, height, northEast_X, northEast_Y, height )
setWaterLevel ( height )
end
addEventHandler("onClientResourceStart", resourceRoot, thaResourceStarting)
</syntaxhighlight>
</section>

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

Template:Ped move states

2012-09-27T20:12:08Z

Callum: Updated list of Ped move states.

<div style="border:3px solid red;margin-bottom:3px;padding-left:5px;"><div style="float:right;padding-right:5px;font-weight:bold;"></div>
* '''stand''': The ped is standing still.
* '''walk''': The ped is walking.
* '''powerwalk''': The ped is walking quickly.
* '''jog''': The ped is jogging.
* '''sprint''': The ped is sprinting.
* '''crouch''': The ped is crouching still.
* '''jump''': The ped is jumping into the air.
* '''fall''': The ped is falling to the ground.
* '''climb''': The ped is climbing onto an object.
</div>

OnClientVehicleDrown

2012-09-27T20:07:14Z

Callum: Fixed a typo and added additional information.

{{Client event}}
__NOTOC__
This event is triggered when a vehicle starts to drown in water. This event is even triggered when vehicles merely come into contact with water, so not every trigger is an indication of actual drowning.

==Parameters==
This event has no parameters.

==Source==
The source of this event is the [[vehicle]] that is drowning.

==Example==
<syntaxhighlight lang="lua">addEventHandler("onClientVehicleDrown",root,function()
outputChatBox("* A "..getVehicleName(source).." is drowning!")
end)</syntaxhighlight>

==See Also==
===Client vehicle events===
{{Client_vehicle_events}}
===Client event functions===
{{Client_event_functions}}

User:Callum

2012-07-15T23:20:10Z

Callum: Created page with "<div style="border:solid #CCCCCC 1px;margin:1px;width:438px;"> {| cellspacing="0" style="width:438px;background:#EEEEEE;" | style="width:45px;height:45px;background:#CCCCCC;text-..."

<div style="border:solid #CCCCCC 1px;margin:1px;width:438px;">
{| cellspacing="0" style="width:438px;background:#EEEEEE;"
| style="width:45px;height:45px;background:#CCCCCC;text-align:center;font-size:14pt;" | '''[[Image:Coder.gif]]'''
| style="font-size:8pt;padding:4pt;line-height:1.25em;text-align:center;font-weight:bold" | This user is a [http://forum.mtasa.com/viewtopic.php?f=136&t=45236 Project Redivivus] Developer.
|}</div>

* Lua expert.
* C++ newbie.
* MTA Patch Contributor.
* GTANet IRC Operator.

SetPedLookAt

2012-07-03T21:11:43Z

Callum: Added 'Needs Example' category.

__NOTOC__
{{Client function}}

Makes a ped turn his head and look at a specific world position or element.

==Syntax==
<syntaxhighlight lang="lua">
bool setPedLookAt ( ped thePed, float x, float y, float z [, int time = 3000, element target ] )
</syntaxhighlight>

===Required Arguments===
*'''thePed:''' the ped to change the lookat of.
*'''x:''' the x coordinate of the world position to look at.
*'''y:''' the y coordinate of the world position to look at.
*'''z:''' the z coordinate of the world position to look at.

===Optional Arguments===
*'''time:''' the time, in milliseconds, during which the ped will look at the target. Once this time has elapsed, he will look ahead again like before the function was applied. A time of 0 will immediately stop any lookat. A negative time will make the ped look at the target indefinitely.
*'''target:''' if this argument is specified, the position arguments will be ignored and the ped's gaze will follow the specified element instead. Can be a player, a vehicle, another ped etc.

==See Also==
{{Client ped functions}}

[[Category:Needs Example]]

OnClientHUDRender

2012-06-25T11:10:16Z

Callum: Incorrectly categorized as 'Needs Example'.

__NOTOC__
{{Client event}}
This event is triggered before GTA renders the HUD. This is particularly useful if you want to use [[dxUpdateScreenSource]] to capture the screen onto a texture without capturing the HUD, or to alter HUD textures using [[Element/Shader|shaders]] before they are drawn onto the screen.

==Parameters==
''None''

==Source==
The [[event system#Event source|source]] of this event is the client's [[root element]].

==Example==
<syntaxhighlight lang="lua">
local render_count = 0

addEventHandler("onClientHUDRender", root, function()
render_count = render_count + 1
end)

addEventHandler("onClientRender", root, function()
render_count = render_count - 1
end)

addCommandHandler("getLossFrames", function()
outputChatBox("Loss: "..render_count)
outputDebugString("Loss: "..render_count, 3, 255, 0, 0)
end)
</syntaxhighlight>

==See Also==
===[[Game_Processing_Order|Game Processing Order]]===
===Other client events===
{{Client_other_events}}
===Client event functions===
{{Client_event_functions}}

GuiGridListSetItemData

2012-06-25T11:08:14Z

Callum: Incorrectly categorized as 'Needs Example'.

{{Client function}}
__NOTOC__
This function sets a Item Data associated to a grid list item.<br/>
'''Note:''' This function will only work '''after''' you set the item's text using [[guiGridListSetItemText]]!

==Syntax==
<syntaxhighlight lang="lua">
bool guiGridListSetItemData ( element gridList, int rowIndex, int columnIndex, string data )
</syntaxhighlight>

===Required Arguments===
*'''gridList:''' A gridlist element of the data you wish to set to
*'''rowIndex:''' The row of the item you wish to set to
*'''columnIndex:''' The column of the item you wish to set to
*'''data:''' The data you wish to set to the item.

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

==Example==
In this example, the gridlist shows the list of players without their color codes and outputs their names with color-codes at the chatbox when player is selected.
<syntaxhighlight lang="lua">
function showPlayers()
local window = guiCreateWindow(0,0,500,400,"Window example - Title",false) -- Create the window
grid = guiCreateGridList(0,0,100,300,false,window) -- Create the gridlist
local column = guiGridListAddColumn(grid, "Players online", 0.9) -- Create a column
showCursor(true)--show cursor
for index,player in ipairs(getElementsByType("player")) do -- Loop through all players
local row = guiGridListAddRow(grid) -- Add a row
guiGridListSetItemText ( grid, row, column, (string.gsub ( getPlayerName(player), '#%x%x%x%x%x%x', '' ) or getPlayerName(player)), false, false) -- Set it's text to the player's name excluding colorcodes
guiGridListSetItemData ( grid, row, column, getPlayerName(player)) -- Set it's data to the player's name with colorcodes
end
end

function outputPlayerName()
if source == grid then -- If the player clicked something in the grid
local selectedRow, selectedColumn = guiGridListGetSelectedItem(grid) -- See which player he selected
local playerName = guiGridListGetItemData(grid, selectedRow, selectedColumn) -- Get the selected player's name with color codes local playerNameWithoutColorCodes = guiGridListGetItemText(grid, selectedRow, selectedColumn) -- Get the selected player's name without color codes
local playerNameWithoutColorCodes = guiGridListGetItemText(grid, selectedRow, selectedColumn) -- Get the selected player's name without color codes
if playerName and playerNameWithoutColorCodes then -- If he really selected something
outputChatBox("The selected player's name without color codes : "..playerNameWithoutColorCodes, 255,255,255,false) -- output without color codes
outputChatBox("The selected player's name with color codes : "..playerName, 255,255,255,false) -- output with color codes
outputChatBox("The selected player's name with colors : "..playerName, 255,255,255,true) -- output with colors
end
end
end

addEventHandler("onClientGUIClick", getRootElement(), outputPlayerName)
addEventHandler("onClientResourceStart", getResourceRootElement(getThisResource()), showPlayers)</syntaxhighlight>

==See Also==
{{GUI functions}}

GuiMemoSetCaratIndex

2012-06-25T11:05:05Z

Callum: Shouldn't need an example now deprecated.

__NOTOC__
{{deprecated}}
{{Client function}}
This function sets the current position of the caret (the text cursor) within the memo.

Please use [[guiMemoSetCaretIndex]]

==Syntax==
<syntaxhighlight lang="lua">
bool guiMemoSetCaratIndex ( gui-memo theMemo, int index )
</syntaxhighlight>

===Required Arguments===
*'''theMemo:''' The memo edit box where the caret position is to be changed.
*'''index:''' An integer referring to the desired position within the box.

===Returns===
Returns ''true'' if the caret was successfully moved, ''false'' otherwise.

==See Also==
{{GUI_functions}}

FxAddGunshot

2012-06-25T11:03:08Z

Callum: Incorrectly categorized as 'Needs Example'.

__NOTOC__
{{Client function}}
[[Image:Fxgunshot.png|thumb|200px|Gunshot]]
This function creates a gunshot particle effect.

==Syntax==
<syntaxhighlight lang="lua">
bool fxAddGunshot ( float posX, float posY, float posZ, float dirX, float dirY, float dirZ, [bool includeSparks=true] )
</syntaxhighlight>

===Required Arguments===
*'''posX, posY, posZ:''' the world coordinates where the effect originates.
*'''dirX, dirY, dirZ:''' a direction vector indicating where the bullet is fired.

===Optional Arguments===
{{OptionalArg}}
* '''includeSparks:''' A bool representing whether the particle effect will generate sparks.

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

==Example==
<section name="Client" class="client" show="true">
This example adds a sparks in front of your face.
<syntaxhighlight lang="lua">
addCommandHandler("sshot", function()
local x, y, z = getElementPosition(localPlayer)
fxAddGunshot(x, y+0.5, z+0.5, 0, 0, 0, true)
end)
</syntaxhighlight>
</section>

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

SetSoundEffectEnabled

2012-06-25T11:01:52Z

Callum: Incorrectly categorized as 'Needs Example'.

__NOTOC__
{{Client function}}
Used to enable or disable specific sound effects.

==Syntax==
<syntaxhighlight lang="lua">bool setSoundEffectEnabled ( element sound, string effectName, bool bEnable )</syntaxhighlight>

===Required Arguments===
*'''sound:''' a [[sound]] element.
*'''effectName:''' the effect you want to enable or disable
{{Sound_Effects}}
*'''bEnable:''' ''true'' if you want to enable the effect, ''false'' if you want to disable it.

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

==Example==
This example creates a sound and set's the flanger sound effect enabled.
<syntaxhighlight lang="lua">addCommandHandler("flanger",function(cmd,enabled)
if(isElement(waterSplashes))then
setSoundEffectEnabled(waterSplashes,cmd,enabled)
else
waterSplashes = playSound("splashes.mp3",true)
setSoundEffectEnabled(waterSplashes,cmd,enabled)
end
end,true) --set it case sensitive as we are going to get the command name and use it in the setSoundEffectEnabled
</syntaxhighlight>

==See Also==
{{Client_audio_functions}}

TriggerEvent

2012-06-25T10:56:11Z

Callum: Removed useless rootElement variable from example.

__NOTOC__
{{Server client function}}
This function will trigger a named [[event]] on a specific [[element]] in the [[element tree]]. See [[event system]] for more information on how the event system works.

You should avoid triggering events on the [[root element]] unless you really need to. Doing this triggers the event on every element in the element tree, which is potentially very CPU intensive. Use as specific (i.e. low down the tree) element as you can.

You can use the value returned from this function to determine if the event was cancelled by one of the event handlers. You should determine what your response (if any) to this should be based on the event's purpose. Generally, cancelling an event should prevent any further code being run that is dependent on whatever triggered that event. For example, if you have an ''onFlagCapture'' event, cancelling it would be expected to prevent the flag being able to be captured. Similarly, if you have ''onPlayerKill'' as an event you trigger, canceling it would either be expected to prevent the player being killed from dying or at least prevent the player from getting a score for it.

==Syntax==
<syntaxhighlight lang="lua">
bool triggerEvent ( string eventName, element baseElement, [ var argument1, ... ] )
</syntaxhighlight>

===Required Arguments===
*'''eventName:''' The name of the event you wish to trigger
*'''baseElement:''' The element you wish to trigger the event on. See [[event system]] for information on how this works.

===Optional Arguments===
{{OptionalArg}}
*'''argument1:''' The first argument that the event handler expects should be added after the ''baseElement'' variable.
**''NOTE:'' This function can have more than one of these arguments specified, once for each argument the event handler is expecting.

===Returns===
* Returns '''nil''' if the arguments are invalid or the event could not be found.
* Returns '''true''' if the event was triggered successfully, and ''was not'' cancelled using [[cancelEvent]].
* Returns '''false''' if the event was triggered successfully, and ''was'' cancelled using [[cancelEvent]].

==Example==
If you define a new custom event as follows:
<syntaxhighlight lang="lua">
-- Add a new event called onSpecialEvent
addEvent ( "onSpecialEvent", true )
-- Define our handler function
function specialEventHandler ( text )
outputChatBox ( text )
end
-- Add the event handler
addEventHandler ( "onSpecialEvent", root, specialEventHandler )
</syntaxhighlight>

You can then trigger this event later on using:
<syntaxhighlight lang="lua">
triggerEvent ( "onSpecialEvent", root, "test" )
</syntaxhighlight>

==See Also==
{{Event_functions}}
[[ru:triggerEvent]]