Multi Theft Auto: Wiki - User contributions [en]

GuiSetEnabled

2019-05-12T21:04:08Z

Sheva: /* Example */

{{Client function}}
__NOTOC__
This function enables/disables a GUI element. A disabled GUI element can't be used, gets a gray aspect and doesn't receive any events.

==Syntax==
<syntaxhighlight lang="lua">
bool guiSetEnabled ( element guiElement, bool enabled )
</syntaxhighlight>
{{OOP||[[GUI widgets|GuiElement]]:setEnabled|enabled|guiGetEnabled}}

===Required Arguments===
*'''guiElement:''' the GUI element you wish to enable or disable
*'''enabled:''' the new state

===Returns===
If the function succeeds it returns ''true'', if it fails it returns ''false''.

==Example==
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">function ChangeMyButtonEnabled ( )
guiSetEnabled ( MyButton, not guiGetEnabled ( MyButton ) ) -- enable button if disabled. Disable if enabled
end
MyGuiWindow = guiCreateWindow(254,206,478,306,"Awesome Gui Window",false) -- Your gui window
MyButton = guiCreateButton(0.477,0.8268,0.1946,0.0784,"Hello World!",true,MyGuiWindow) -- Creates a button in your gui window
ChangeMyButtonEnabled ( ) -- Execute function </syntaxhighlight></section>

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

XmlNodeSetValue

2019-05-12T20:52:54Z

Sheva: Do not forget xmlUnloadFile.

{{Server client function}}
__NOTOC__
This function is made to be able to assign values to tags in XML files (eg. <something>anything</something>).

==Syntax==
<syntaxhighlight lang="lua">
bool xmlNodeSetValue ( xmlnode theXMLNode, string value [, bool setCDATA = false] )
</syntaxhighlight>
{{OOP||[[xmlnode]]:setValue|value|xmlNodeGetValue}}
===Required Arguments===
*'''theXMLNode:''' The [[xml node]] you want to set the value of.
*'''value:''' The [[string]] value you want the node to have.
{{New feature/item|4.0140|1.4.0|6782|
*'''setCDATA:''' A boolean indicating if you want the value to be enclosed inside CDATA tags.
}}

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

==Example==
<section name="Server Example" class="server" show="false">
In this example a sample value is inserted into a XML file.
<syntaxhighlight lang="lua">
local xmlFile = xmlLoadFile ( "exampleFile.xml" ) -- Open a file already created
if xmlFile then -- If it's indeed opened
local node = xmlCreateChild ( xmlFile, "somesubnode" ) -- Create a new subnode
local success = xmlNodeSetValue ( node, "somevalue" ) -- Set the value of it
if success then -- Check if it was successful
xmlSaveFile ( xmlFile ) -- Save the file
end
xmlUnloadFile(xmlFile)
end
</syntaxhighlight>
After both changing the value and saving the XML file with [[xmlSaveFile]], the file will look like this:
<section name="exampleFile.xml" class="server" show="true">
<syntaxhighlight lang="xml">
<somenode>
<somesubnode>somevalue</somesubnode>
</somenode>
</syntaxhighlight>
</section>
<section name="Client Example: Save and load from a clientside XML" class="client" show="true">
This shows an example of a clientside XML file. You can use this to store user preferences and load them the next time the script loads. Almost always, you should have an options GUI for clients to interact with to set these values.
<br/><br/>
Since the XML will change, it should NOT be included in the resource's meta.xml file. MTA will think that file is corrupted and will download it again from the server. Instead, you should create the XML within the script, and then load it within the script on future script runs if it exists.

'''This xml will be created from the script following it below'''
<syntaxhighlight lang="xml">
<root>
<hud_display>
<IconSizeX>60</IconSizeX>
<IconSizeY>60</IconSizeY>
</hud_display>
<hud_binds>
<weaponSlot0>tab</weaponSlot0>
<weaponSlot1>1</weaponSlot1>
</hud_binds>
</root>
</syntaxhighlight>

'''This script will create the xml or load it if it exists'''
<syntaxhighlight lang="lua">
function ClientResourceStart ()
xmlRootTree = xmlLoadFile ( "userSettings.xml" ) --Attempt to load the xml file

if xmlRootTree then -- If the xml loaded then...
xmlHudBranch = xmlFindChild(xmlRootTree,"hud_display",0) -- Find the hud sub-node
xmlBindsBranch = xmlFindChild(xmlRootTree,"hud_binds",0) -- Find the binds sub-node
outputChatBox ( "XML Found and Loaded" )
else -- If the xml does not exist then...
xmlRootTree = xmlCreateFile ( "userSettings.xml", "root" ) -- Create the xml file
xmlHudBranch = xmlCreateChild ( xmlRootTree, "hud_display" ) -- Create the hud sub-node under the root node
xmlBindsBranch = xmlCreateChild ( xmlRootTree, "hud_binds" )-- Create the binds sub-node under the root node
xmlNodeSetValue (xmlCreateChild ( xmlHudBranch, "IconSizeX"), "60" ) --Create sub-node values under the hud sub-node
xmlNodeSetValue (xmlCreateChild ( xmlHudBranch, "IconSizeY"), "60" ) --Create sub-node values under the hud sub-node
xmlNodeSetValue (xmlCreateChild ( xmlBindsBranch, "weaponSlot0"), "tab" ) --Create sub-node values under the binds sub-node
xmlNodeSetValue (xmlCreateChild ( xmlBindsBranch, "weaponSlot1"), "1" ) --Create sub-node values under the binds sub-node
outputChatBox ( "XML Created" )
end

--Retrieve a single sub-node name or value
outputChatBox( "Node name: "..xmlNodeGetName (xmlFindChild(xmlHudBranch,"IconSizeX",0)), 0, 0, 255 ) --blue outputs
outputChatBox( "Node Value: "..xmlNodeGetValue (xmlFindChild(xmlHudBranch,"IconSizeX",0)), 0, 0, 255 ) --blue outputs

--Retrieve multiple sub-node names or values
xmlHudChildrenTable = xmlNodeGetChildren ( xmlHudBranch ) --Create a table of this branch's children
for i,node in pairs(xmlHudChildrenTable ) do --Loop through the branch's children for sub-nodes
outputChatBox( "Node name: "..xmlNodeGetName (node), 0, 255, 0 ) --green outputs
outputChatBox( "Node Value: "..xmlNodeGetValue(node), 0, 255, 0 ) --green outputs
end
end
addEventHandler ( "onClientResourceStart", resourceRoot, ClientResourceStart )

function ClientResourceStop ()
xmlSaveFile ( xmlRootTree ) --Save the xml from memory for use next time
xmlUnloadFile ( xmlRootTree ) --Unload the xml from memory
outputChatBox ( "Saved and unloaded the XML." )
end
addEventHandler ( "onClientResourceStop", resourceRoot, ClientResourceStop )
</syntaxhighlight>
</section>

==See Also==
{{XML functions}}

XmlNodeSetName

2019-05-12T20:51:50Z

Sheva: Do not forget xmlUnloadFile.

__NOTOC__
{{Server client function}}
Sets the tag name of the specified XML node.

==Syntax==
<syntaxhighlight lang="lua">
bool xmlNodeSetName ( xmlnode node, string name )
</syntaxhighlight>
{{OOP||[[xmlnode]]:setName|name|xmlNodeGetName}}

===Required Arguments===
*'''node:''' the node to change the tag name of.
*'''name:''' the new tag name to set.

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

==Example==
<syntaxhighlight lang="lua">
local xml = xmlCreateFile("fileName.xml","Test")
local xmlNode = xmlCreateChild(xml,"Test1")
local xmlNodeName = xmlNodeGetName(xmlNode)
xmlUnloadFile(xml)
if xmlNodeName == "Test1" then
xmlNodeSetName(xmlNode, "Test2")
end
</syntaxhighlight>

==See Also==
{{XML functions}}
[[ru:xmlNodeSetName]]

XmlNodeGetValue

2019-05-12T20:50:49Z

Sheva: Do not forget xmlUnloadFile.

{{Server client function}}
__NOTOC__
This function is made to be able to read tag values in XML files (eg. <something>anything</something>).

==Syntax==
<syntaxhighlight lang="lua">
string xmlNodeGetValue ( xmlnode theXMLNode )
</syntaxhighlight>
{{OOP||[[xmlnode]]:getValue|value|xmlNodeSetValue}}

===Required Arguments===
*'''theXMLNode:''' The [[xml node]] of which you need to know the value.

===Returns===
Returns the value of the node as a [[string]] if it was received successfully, ''false'' otherwise.

==Example==
<section name="Server Example: return a sample file from a XML file" class="server" show="true">
In this example a sample value is returned from a XML file.
<syntaxhighlight lang="lua">
local xmlFile = xmlLoadFile ( "exampleFile.xml" ) -- Open a file that we have already created
if xmlFile then -- If it's indeed opened
local node = xmlFindChild( xmlFile, "somesubnode", 0 ) -- Find our first sub node
local success = xmlNodeGetValue ( node ) -- Get the value of it
xmlUnloadFile(xmlFile)
if success then -- Check if it was successful
outputChatBox ( tostring ( success ) ) -- Output "somevalue" to the chatbox
end
end
</syntaxhighlight>
In order for the result to be valid, the xml file has to look like this:
<section name="exampleFile.xml" class="server" show="true">
<syntaxhighlight lang="xml">
<somenode>
<somesubnode>somevalue</somesubnode>
</somenode>
</syntaxhighlight>
</section>

<section name="Client Example: Save and load from a clientside XML" class="client" show="true">
This shows an example of a clientside XML file. You can use this to store user preferences and load them the next time the script loads. Almost always, you should have an options GUI for clients to interact with to set these values.
<br/><br/>
Since the XML will change, it should NOT be included in the resource's meta.xml file. MTA will think that file is corrupted and will download it again from the server. Instead, you should create the XML within the script, and then load it within the script on future script runs if it exists.

'''This xml will be created from the script following it below'''
<syntaxhighlight lang="xml">
<root>
<hud_display>
<IconSizeX>60</IconSizeX>
<IconSizeY>60</IconSizeY>
</hud_display>
<hud_binds>
<weaponSlot0>tab</weaponSlot0>
<weaponSlot1>1</weaponSlot1>
</hud_binds>
</root>
</syntaxhighlight>

'''This script will create the xml or load it if it exists'''
<syntaxhighlight lang="lua">
function ClientResourceStart ()
if source ~= getResourceRootElement() then return end --This event will happen with any resource start, isolate it to this resource
xmlRootTree = xmlLoadFile ( "userSettings.xml" ) --Attempt to load the xml file

if xmlRootTree then -- If the xml loaded then...
xmlHudBranch = xmlFindChild(xmlRootTree,"hud_display",0) -- Find the hud sub-node
xmlBindsBranch = xmlFindChild(xmlRootTree,"hud_binds",0) -- Find the binds sub-node
outputChatBox ( "XML Found and Loaded" )
else -- If the xml does not exist then...
xmlRootTree = xmlCreateFile ( "userSettings.xml", "root" ) -- Create the xml file
xmlHudBranch = xmlCreateChild ( xmlRootTree, "hud_display" ) -- Create the hud sub-node under the root node
xmlBindsBranch = xmlCreateChild ( xmlRootTree, "hud_binds" )-- Create the binds sub-node under the root node
xmlNodeSetValue (xmlCreateChild ( xmlHudBranch, "IconSizeX"), "60" ) --Create sub-node values under the hud sub-node
xmlNodeSetValue (xmlCreateChild ( xmlHudBranch, "IconSizeY"), "60" ) --Create sub-node values under the hud sub-node
xmlNodeSetValue (xmlCreateChild ( xmlBindsBranch, "weaponSlot0"), "tab" ) --Create sub-node values under the binds sub-node
xmlNodeSetValue (xmlCreateChild ( xmlBindsBranch, "weaponSlot1"), "1" ) --Create sub-node values under the binds sub-node
outputChatBox ( "XML Created" )
end

--Retrieve a single sub-node name or value
outputChatBox( "Node name: "..xmlNodeGetName (xmlFindChild(xmlHudBranch,"IconSizeX",0)), 0, 0, 255 ) --blue outputs
outputChatBox( "Node Value: "..xmlNodeGetValue (xmlFindChild(xmlHudBranch,"IconSizeX",0)), 0, 0, 255 ) --blue outputs

--Retrieve multiple sub-node names or values
xmlHudChildrenTable = xmlNodeGetChildren ( xmlHudBranch ) --Create a table of this branch's children
for i,node in pairs(xmlHudChildrenTable ) do --Loop through the branch's children for sub-nodes
outputChatBox( "Node name: "..xmlNodeGetName (node), 0, 255, 0 ) --green outputs
outputChatBox( "Node Value: "..xmlNodeGetValue(node), 0, 255, 0 ) --green outputs
end
end
addEventHandler ( "onClientResourceStart", root, ClientResourceStart )

function ClientResourceStop ()
if source ~= getResourceRootElement() then return end --This event will happen with any resource stop, isolate it to this resource
xmlSaveFile ( xmlRootTree ) --Save the xml from memory for use next time
xmlUnloadFile ( xmlRootTree ) --Unload the xml from memory
outputChatBox ( "Saved and unloaded the XML." )
end
addEventHandler ( "onClientResourceStop", root, ClientResourceStop )
</syntaxhighlight>
</section>

</section>

==See Also==
{{XML functions}}

XmlNodeGetName

2019-05-12T20:49:05Z

Sheva: Do not forget xmlUnloadFile.

__NOTOC__
{{Server client function}}
Gets the tag name of the specified XML node.

==Syntax==
<syntaxhighlight lang="lua">
string xmlNodeGetName ( xmlnode node )
</syntaxhighlight>
{{OOP||[[xmlnode]]:getName|name|xmlNodeSetName}}
===Required Arguments===
*'''node:''' the node to get the tag name of.

===Returns===
Returns the tag name of the node if successful, ''false'' otherwise.

<section name="Example 1" class="both" show="true">
==Example==
<syntaxhighlight lang="lua">
local xml = xmlCreateFile("test.xml","test")
local xmlNode = xmlCreateChild(xml,"nextTest")
local xmlNodeName = xmlNodeGetName(xmlNode)
xmlUnloadFile(xml)
outputConsole(xmlNodeName) --This should output "nextTest".
</syntaxhighlight>
</section>

==See Also==
{{XML functions}}
[[ru:xmlNodeGetName]]

XmlFindChild

2019-05-12T20:47:34Z

Sheva: Do not forget xmlUnloadFile.

__NOTOC__
{{Server client function}}
This function returns a named child node of an XML node.

==Syntax==
<syntaxhighlight lang="lua">xmlnode xmlFindChild ( xmlnode parent, string tagName, int index )</syntaxhighlight>
{{OOP||[[xmlnode]]:findChild}}
===Required Arguments===
* '''parent''': This is an [[xmlnode]] that you want to find the child node under.
* '''tagName''': This is the name of the child node you wish to find (case-sensitive).
* '''index''': This is the 0-based index of the node you wish to find. For example, to find the 5th subnode with a particular name, you would use 4 as the index value. To find the first occurence, use 0.

===Returns===
Returns an [[xmlnode]] if the node was found, ''false'' otherwise.

==Example==
<section name="Server" class="server" show="true">
If you wanted to find an ''instructions'' node in an xml file like this:
<syntaxhighlight lang="xml">
<root version="2.0">
<options>
<instructions>Start at the beginning and keep going until the end!</instructions>
</options>
</root>
</syntaxhighlight>

You could use the following code to print the text in the ''instructions'' node to the chatbox:
<syntaxhighlight lang="lua">
local rootNode = xmlLoadFile ( "test.xml" )
local optionsNode = xmlFindChild ( rootNode, "options", 0 )
local instructionsNode = xmlFindChild ( optionsNode, "instructions", 0 )
local instructions = xmlNodeGetValue ( instructionsNode )
xmlUnloadFile(rootNode)

outputChatBox ( instructions )
</syntaxhighlight>
</section>

==See Also==
{{XML functions}}
[[ru:xmlFindChild]]

XmlSaveFile

2019-05-12T20:46:01Z

Sheva: Prevented memory leak

__NOTOC__
{{Server client function}}
This function saves a loaded XML file.

==Syntax==
<syntaxhighlight lang="lua">bool xmlSaveFile ( xmlnode rootNode ) </syntaxhighlight>
{{OOP||[[xmlnode]]:saveFile}}
===Required Arguments===
*'''rootNode:''' the root [[xmlnode]] of the loaded XML file.

===Returns===
Returns ''true'' if save was successful, ''false'' if the XML file does not exist.

==Example==
<section name="Client" class="client" show="true">
This example allows a player to use the command 'createfile' to create an .xml file.
<syntaxhighlight lang="lua">
-- Creates a file named "new.xml" with root node "newroot" and childnode "newchild".
function createFileHandler()
local RootNode = xmlCreateFile("new.xml"," newroot")
local NewNode = xmlCreateChild(RootNode, "newchild")
xmlSaveFile(RootNode)
xmlUnloadFile(RootNode)
end

addCommandHandler("createfile", createFileHandler)
</syntaxhighlight>
</section>

==See Also==
{{XML_functions}}
[[ru:xmlSaveFile]]

XmlCreateChild

2019-05-12T20:44:54Z

Sheva: Prevented memory leak

__NOTOC__
{{Server client function}}
This function creates a new child node under an XML node.

==Syntax==
<syntaxhighlight lang="lua">xmlnode xmlCreateChild ( xmlnode parentNode, string tagName )</syntaxhighlight>
{{OOP||[[xmlnode]]:createChild}}
===Required Arguments===
*'''parentNode:''' the [[xmlnode]] you want to create a new child node under.
*'''tagName:''' the type of the child node that will be created.

===Returns===
Returns the created [[xmlnode]] if successful, ''false'' otherwise.

==Example==
This example allows a player to use the command 'createfile' to create an .xml file.
<syntaxhighlight lang="lua">
-- Creates a file named "new.xml" with root node "newroot" and childnode "newchild".
function createFileHandler()
local RootNode = xmlCreateFile("new.xml"," newroot")
local NewNode = xmlCreateChild(RootNode, "newchild")
xmlSaveFile(RootNode)
xmlUnloadFile(RootNode)
end

addCommandHandler("createfile", createFileHandler)
</syntaxhighlight>

==See Also==
{{XML functions}}
[[ru:xmlCreateChild]]

GetPedTargetStart

2019-04-29T23:09:06Z

Sheva: Optimization in the example

__NOTOC__
{{Client function}}
This function allows retrieval of the position a ped's target range begins, when he is aiming with a weapon.

==Syntax==
<syntaxhighlight lang="lua">
float float float getPedTargetStart ( ped targetingPed )
</syntaxhighlight>

===Required Arguments===
*'''targetingPed:''' The ped whose target start you wish to retrieve

===Returns===
Returns three floats, x,y,z, representing the position where the ped's target starts, or ''false'' if it was unsuccessful.

==Example==
This Example draws a line from where the Ped´s Target Starts to the Point where the Target Ends
<syntaxhighlight lang="lua">
function drawline()
local x, y, z = getPedTargetStart(localPlayer) -- Gets the Point to start From.
if (x) then -- Checks if there is a Point to start From.
local sx, sy, sz = getPedTargetCollision(localPlayer) -- Gets the Point where the Targets Collision is.
dxDrawLine3D(x, y, z, sx, sy, sz) -- Draws the Line
end
end
addEventHandler("onClientPreRender", getRootElement(), drawline) -- Adds the Handler.
</syntaxhighlight>

==See Also==
{{Client_ped_functions}}

GetPedTargetCollision

2019-04-29T23:06:09Z

Sheva: Optimization in the example

__NOTOC__
{{Client function}}
This function allows retrieval of where a ped's target is blocked. It will only be blocked if there is an obstacle within a ped's target range.

==Syntax==
<syntaxhighlight lang="lua">
float float float getPedTargetCollision ( ped targetingPed )
</syntaxhighlight>

===Required Arguments===
*'''targetingPed:''' This is the ped whose target collision you wish to retrieve

===Returns===
Returns three floats, ''x'',''y'',''z'', representing the position where the ped's target collides, or ''false'' if it was unsuccessful.

==Example==

This Example draws a line from where the Ped´s Target Starts to the Point where the Targets Collision is.
<syntaxhighlight lang="lua">
function drawline()
local x, y, z = getPedTargetStart(localPlayer) -- Gets the Point to start From.
if (x) then -- Checks if there is a Point to start From.
local sx, sy, sz = getPedTargetCollision(localPlayer) -- Gets the Point where the Targets Collision is.
dxDrawLine3D(x, y, z, sx, sy, sz) -- Draws the Line
end
end
addEventHandler("onClientPreRender", getRootElement(), drawline) -- Adds the Handler.
</syntaxhighlight>

==See Also==
{{Client_ped_functions}}

GetObjectProperty

2019-02-08T23:15:35Z

Sheva: Fixed argument list

__NOTOC__
{{Client function}}
{{New feature/item|3.0157|1.5.6|14370|This function gets a property of the specified [[object]].}}

==Syntax==
<syntaxhighlight lang="lua">mixed getObjectProperty ( object theObject, string property [ , var value1, ... ] )</syntaxhighlight>
{{OOP||[[object]]:getProperty||setProperty}}
===Required Arguments===
*'''theObject''': the [[object]] you wish to get a property of.
*'''property:''': the property you want to get the value of:
<div style="padding-left:20px">
* "all" - ''table'' with values of all properties below (OOP method: ''getProperties'')
</div>
{{Object Properties}}

===Returns===
On success: [[table]] for '''all''', 3 [[float|floats]] for '''center_of_mass''' or [[float]] for other properties

On failure: ''false''

==Example==
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
addEventHandler("onClientResourceStart", resourceRoot, function()
local theObject = createObject(980, 0, 0, 0) -- create an object
if theObject then
setObjectProperty(theObject, "center_of_mass", 0, -1, 0) -- set it's center of mass

local x, y, z = getObjectProperty(theObject, "center_of_mass") -- get it's center of mass
outputChatBox("Object's center of mass: "..tostring(x)..", "..tostring(y)..", "..tostring(z))
end
end)
</syntaxhighlight>
</section>

==See Also==
{{Client_object_functions}}