Multi Theft Auto: Wiki - User contributions [en]

EngineLoadDFF

2017-06-20T18:31:26Z

Hale: /* Removed the second argument from examples due to confusions */

{{Client function}}
__NOTOC__
{{Note box|Please note the loading order that is used in the examples as other orders can cause collisions, textures or the DFF not to load due to technical limitations.}}

This function loads a RenderWare Model (DFF) file into GTA.

To successfully load your model with textures, be sure to use [[engineLoadTXD]] and [[engineImportTXD]] before calling this function. If some error occurs while loading the DFF, MTA will output a message - check out [[DFF error messages]] to know what they mean.

This is a client side function. Be sure to transfer your DFF file by including it in the meta file.

The returned [[DFF]] element is an element in the element tree, just like vehicles and objects. When the dff is destroyed, ie on resource unload or using [[destroyElement]], any elements that use the DFF, such as vehicles or objects will be reset.

==Syntax==
<syntaxhighlight lang="lua">
dff engineLoadDFF ( string dff_file / string raw_data )
</syntaxhighlight>
{{OOP||[[DFF|EngineDFF]]}}
===Required Arguments===
*'''dff_file / raw_data:''' The [[filepath]] to the DFF file you want to load or whole data buffer of the DFF file.

===Returns===
Returns a [[DFF]] element if the dff file loaded, ''false'' otherwise.

==Example==
'''Example 1:''' This example loads a combination of a custom DFF and TXD file to replace the Euros vehicle in-game. The collisions are embedded inside the DFF file.
<syntaxhighlight lang="lua">
outputChatBox ( "> replacing the euros vehicle" )

txd = engineLoadTXD ( "data/euros.txd" )
engineImportTXD ( txd, 587 )
dff = engineLoadDFF ( "data/euros.dff" )
engineReplaceModel ( dff, 587 )
</syntaxhighlight>

'''Example 2:''' This example replaces a standard SA skin (in this example ID '190) with a custom skin model (DFF & TXD)
<syntaxhighlight lang="lua">
addEventHandler ( "onClientResourceStart", getResourceRootElement ( getThisResource() ),
function ()
txd = engineLoadTXD ( "skinmodel.txd" ); -- change 'skinmodel' to your mod's file name
engineImportTXD ( txd, 190 ); -- change the ID 190 into the GTA skin ID you with to replace with mod
dff = engineLoadDFF ( "skinmodel.dff" ); -- change 'skinmodel' to your mod's file name
engineReplaceModel ( dff, 190 ); -- change the ID 190 into the GTA skin ID you with to replace with mod
end
);
</syntaxhighlight>

'''Example 3:''' This example replaces a default weapon with a custom weapon mod (TXD & DFF)
<syntaxhighlight lang="lua">
function replaceWeapon()
txd = engineLoadTXD ( "m4.txd" )
engineImportTXD ( txd, 356)
dff = engineLoadDFF ( "m4.dff") -- use weapon model ID, not GTA weapon ID (model ID from https://wiki.multitheftauto.com/wiki/Weapons)
engineReplaceModel ( dff, 356) -- Likewise, model ID, for M4 as example it's 356

end
addEventHandler ( "onClientResourceStart", getResourceRootElement(getThisResource()), replaceWeapon)
</syntaxhighlight>

'''Example 4:''' This example loads a combination of custom TXD, COL and DFF files to replace an in-game model of a set of floors.
<syntaxhighlight lang="lua">
outputChatBox ( "> loading floor objects" )
col_floors = engineLoadCOL ( "models/office_floors.col" )
engineReplaceCOL ( col_floors, 3781 )
txd_floors = engineLoadTXD ( "models/office_floors.txd" )
engineImportTXD ( txd_floors, 3781 )
dff_floors = engineLoadDFF ( "models/office_floors.dff" )
engineReplaceModel ( dff_floors, 3781 )
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.4.1-9.07088|Added option to use raw data instead of a file name}}

==See Also==
{{Engine_functions}}

DxDrawAnimWindow

2017-06-08T22:22:09Z

Hale: /* Grammar fix */

{{Useful Function}}
__NOTOC__
This function is for creating and animating a dX Window.
* '''NOTE:''' This is made to be used clientside!.

==Syntax==
<syntaxhighlight lang="lua">bool dxDrawAnimWindow ( string text, int height, int width, int color, string element font, string anim)</syntaxhighlight>

===Required Arguments===
* '''text:''' The text of the window
* '''height:''' The height of the window
* '''width:''' The width of the window
* '''color:''' The color of the window
* '''font:''' A element or string representing the font.
* '''anim:''' The easing or animation type. See https://wiki.multitheftauto.com/wiki/Easing] For more Types-

==Code==
<section name="Clientside script" class="client" show="true">
<syntaxhighlight lang="lua">
function dxDrawAnimWindow(text,height,width,color,font,anim)
local x,y = guiGetScreenSize()

btwidth = width
btheight = height/20

local now = getTickCount()
local elapsedTime = now - start
local endTime = start + 1500
local duration = endTime - start
local progress = elapsedTime / duration
local x1, y1, z1 = interpolateBetween ( 0, 0, 0, width, height, 255, progress, anim)
local x2, y2, z2 = interpolateBetween ( 0, 0, 0, btwidth, btheight, btheight/11, progress, anim)

posx = (x/2)-(x1/2)
posy = (y/2)-(y1/2)

dxDrawRectangle ( posx, posy-y2, x2, y2, color )
dxDrawRectangle ( posx, posy, x1, y1, tocolor ( 0, 0, 0, 200 ) )
dxDrawText ( text, 0, -(y1)-y2, x, y, tocolor ( 255, 255, 255, 255 ), z2,font,"center","center")

end
</syntaxhighlight>
</section>

==Use==
Always remember to define the "start" value with getTickCount() and use onClientRender or onClientPreRender
<section name="Clientside example" class="client" show="true">
<syntaxhighlight lang="lua">function content()
local color = tocolor ( 0, 0, 0, 200 )
dxDrawAnimWindow ( "My Animated Window", 520, 600, color, "default-bold", "OutBounce")
end
bindKey ( "F2", "down", main )
function main()
start = getTickCount()
addEventHandler ( "onClientRender", getRootElement(), content )
end
</syntaxhighlight>
</section>

Author: Bc#

==See Also==
{{Useful_Functions}}

AddEventHandler

2017-06-08T20:57:19Z

Hale: /* Example */

__NOTOC__
{{Server client function}}
{{Note_box|It is strongly advised that you do not use the same name for your handler function as the event name, as this can lead to confusion if multiple handler functions are used.}}
This function will add an [[event]] handler. An event handler is a function that will be called when the event it's attached to is triggered. See [[event system]] for more information on how the event system works.

Event handlers are functions that are called when a particular event happens. Each event specifies a specific set of variables that are passed to the event handler and can be read by your function. The following global variables are available for use in handler functions:
*'''source''': the element that triggered the event
*'''this''': the element that the event handler is attached to
*'''sourceResource''': the resource that triggered the event
*'''sourceResourceRoot''': the root element of the resource that triggered the event
*'''client''': the client that triggered the event using [[triggerServerEvent]]. Not set if the event was not triggered from a client.
{{New_feature|3|1.0|
*'''eventName''': the name of the event which triggered the handler function.
}}

It is important to remember that events pass up and down the [[element tree]]. An event triggered on the root element is triggered on every element in the tree. An event triggered on any other element is triggered on its ancestors (its parent element and its parent's parent etc) and its children, grandchildren and great-grandchildren. You can use the ''getPropagated'' argument to specify if you wish your handler to receive events that have propagated up or down the tree.

The order in which event handlers are triggered is undefined, you should not rely on one event handler being executed before another.
{{Note|See [[Script security]] for tips on preventing cheaters when using events and element data}}
{{Note|See [[Event_Source_Element|Event Source Element]] for a descriptive visualization of the event system handling an event trigger.}}
==Syntax==
<syntaxhighlight lang="lua">
bool addEventHandler ( string eventName, element attachedTo, function handlerFunction, [ bool getPropagated = true, string priority = "normal" ] )
</syntaxhighlight>

===Required Arguments===
*'''eventName:''' The name of the [[event]] you want to attach the handler function to.
*'''attachedTo:''' The [[element]] you wish to attach the handler to. The handler will only be called when the event it is attached to is triggered for this element, or one of its children. Often, this can be the root element (meaning the handler will be called when the event is triggered for ''any'' element).
*'''handlerFunction:''' The handler function you wish to call when the event is triggered. This function will be passed all of the event's parameters as arguments, but it isn't required that it takes all of them.

===Optional Arguments===
*'''getPropagated:''' A boolean representing whether the handler will be triggered if the event was propagated down or up the [[element tree]] (starting from the source), and not triggered directly on attachedTo (that is, handlers attached with this argument set to ''false'' will only be triggered if ''source == this'').
{{New_feature|3.0131|1.3.1|
*'''priority :''' A string representing the trigger order priority relative to other event handlers of the same name. Possible values are:
**'''"high"'''
**'''"normal"'''
**'''"low"'''
''It is also possible to add finer priority control by appending a positive or negative number to the priority string. For example (in priority order for reference): "high+4" "high" "high-1" "normal-6" "normal-7" "low+1" "low" "low-1"''
'''Important note:''' Anything bound to a specific element will be run before other handlers that are bound to something higher in the element tree (like root) This means that "high+10" bound to root won't trigger before "normal" bound directly to an element.
}}

===Returns===
Returns ''true'' if the event handler was attached successfully. Returns ''false'' if the specified event could not be found or any parameters were invalid.

==Example==
<section name="Server" class="server" show="true">
This serverside example sends a message to everyone in the server when a player spawns.
<syntaxhighlight lang="lua">
-- define our handler function
function onPlayerSpawnHandler ( )
-- get the player's name, source is the player because he was spawned
local playerName = getPlayerName( source )
-- output in the chat box that they've spawned
outputChatBox ( playerName .. " has spawned!" )
end

addEventHandler( "onPlayerSpawn", root, onPlayerSpawnHandler ) -- root is a predefined global variable for getRootElement()
</syntaxhighlight>
</section>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.03795|Added priority argument}}

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

Predefined variables list

2017-05-27T14:35:01Z

Hale: Added 'arg' predefined variable

'''Lua Predefined variables'''
<syntaxhighlight lang="lua">
_G -- returns a table of all global variables
coroutine -- returns a table containing functions for threads
debug -- returns a table containing debug functions
math -- returns a table that contains mathematical functions
string -- returns a table containing functions for strings
table -- returns a table that contains functions for tables
_VERSION -- returns a string of the version of lua in format "Lua 5.1"
self -- used in methods
arg -- used in functions which use '...' as an argument (https://www.lua.org/pil/5.2.html)
</syntaxhighlight>

'''MTA Predefined variables'''
<section name="Shared" class="both" show="true">
<syntaxhighlight lang="lua">
exports -- returns a table of resource names containing all export functions
resource -- returns a resource element of the resource the snippet was executed in
resourceRoot -- returns a resource root element of the resource the snippet was executed in
root -- returns the root element of the server
</syntaxhighlight>

</section>
<section name="Client only" class="client" show="true">
<syntaxhighlight lang="lua">
guiRoot -- returns the root element of all GUI elements.
localPlayer -- returns the player element of the local player.
</syntaxhighlight>
</section>
The list of hidden variables, that can be found in functions - handlers:
<section name="Shared" class="both" show="true">
<syntaxhighlight lang="lua">
source -- The player or element the event was attached to
this -- Element, which was attached function-handler.
eventName -- the name of the event ("onResourceStart", "onPlayerWasted" etc.)
</syntaxhighlight>
</section>

<section name="Server only" class="server" show="true">
<syntaxhighlight lang="lua">
client -- the client that called the event
</syntaxhighlight>

</section>

[http://wiki.multitheftauto.com/wiki/AddEventHandler More details about hidden variables in functions and events]

[[Element_tree]]

List Predefined variables available in the HTTP files:
<syntaxhighlight lang="lua">[php]
requestHeaders -- table, contains all HTTP headlines current page.
form -- table, contains all POST and GET settings, transferred current page.
cookies -- table, contains all COOKIE, transferred current page.
hostname -- string, contains IP or name host, which requested current page.
url -- string, URL current page.
user -- element, account user, which requested current page.
</syntaxhighlight>

[http://wiki.multitheftauto.com/wiki/Resource_Web_Access More info about it]

Predefined variables list

2017-05-27T14:33:33Z

Hale: Added 'arg' predefined variable

'''Lua Predefined variables'''
<syntaxhighlight lang="lua">
_G -- returns a table of all global variables
coroutine -- returns a table containing functions for threads
debug -- returns a table containing debug functions
math -- returns a table that contains mathematical functions
string -- returns a table containing functions for strings
table -- returns a table that contains functions for tables
_VERSION -- returns a string of the version of lua in format "Lua 5.1"
self -- used in methods
arg -- used in functions which use '...' as an argument ([https://www.lua.org/pil/5.2.html])
</syntaxhighlight>

'''MTA Predefined variables'''
<section name="Shared" class="both" show="true">
<syntaxhighlight lang="lua">
exports -- returns a table of resource names containing all export functions
resource -- returns a resource element of the resource the snippet was executed in
resourceRoot -- returns a resource root element of the resource the snippet was executed in
root -- returns the root element of the server
</syntaxhighlight>

</section>
<section name="Client only" class="client" show="true">
<syntaxhighlight lang="lua">
guiRoot -- returns the root element of all GUI elements.
localPlayer -- returns the player element of the local player.
</syntaxhighlight>
</section>
The list of hidden variables, that can be found in functions - handlers:
<section name="Shared" class="both" show="true">
<syntaxhighlight lang="lua">
source -- The player or element the event was attached to
this -- Element, which was attached function-handler.
eventName -- the name of the event ("onResourceStart", "onPlayerWasted" etc.)
</syntaxhighlight>
</section>

<section name="Server only" class="server" show="true">
<syntaxhighlight lang="lua">
client -- the client that called the event
</syntaxhighlight>

</section>

[http://wiki.multitheftauto.com/wiki/AddEventHandler More details about hidden variables in functions and events]

[[Element_tree]]

List Predefined variables available in the HTTP files:
<syntaxhighlight lang="lua">[php]
requestHeaders -- table, contains all HTTP headlines current page.
form -- table, contains all POST and GET settings, transferred current page.
cookies -- table, contains all COOKIE, transferred current page.
hostname -- string, contains IP or name host, which requested current page.
url -- string, URL current page.
user -- element, account user, which requested current page.
</syntaxhighlight>

[http://wiki.multitheftauto.com/wiki/Resource_Web_Access More info about it]

Predefined variables list

2017-05-27T14:30:41Z

Hale:

'''Lua Predefined variables'''
<syntaxhighlight lang="lua">
_G -- returns a table of all global variables
coroutine -- returns a table containing functions for threads
debug -- returns a table containing debug functions
math -- returns a table that contains mathematical functions
string -- returns a table containing functions for strings
table -- returns a table that contains functions for tables
_VERSION -- returns a string of the version of lua in format "Lua 5.1"
self -- used in methods
arg -- used in functions which use '...' as an argument
</syntaxhighlight>

'''MTA Predefined variables'''
<section name="Shared" class="both" show="true">
<syntaxhighlight lang="lua">
exports -- returns a table of resource names containing all export functions
resource -- returns a resource element of the resource the snippet was executed in
resourceRoot -- returns a resource root element of the resource the snippet was executed in
root -- returns the root element of the server
</syntaxhighlight>

</section>
<section name="Client only" class="client" show="true">
<syntaxhighlight lang="lua">
guiRoot -- returns the root element of all GUI elements.
localPlayer -- returns the player element of the local player.
</syntaxhighlight>
</section>
The list of hidden variables, that can be found in functions - handlers:
<section name="Shared" class="both" show="true">
<syntaxhighlight lang="lua">
source -- The player or element the event was attached to
this -- Element, which was attached function-handler.
eventName -- the name of the event ("onResourceStart", "onPlayerWasted" etc.)
</syntaxhighlight>
</section>

<section name="Server only" class="server" show="true">
<syntaxhighlight lang="lua">
client -- the client that called the event
</syntaxhighlight>

</section>

[http://wiki.multitheftauto.com/wiki/AddEventHandler More details about hidden variables in functions and events]

[[Element_tree]]

List Predefined variables available in the HTTP files:
<syntaxhighlight lang="lua">[php]
requestHeaders -- table, contains all HTTP headlines current page.
form -- table, contains all POST and GET settings, transferred current page.
cookies -- table, contains all COOKIE, transferred current page.
hostname -- string, contains IP or name host, which requested current page.
url -- string, URL current page.
user -- element, account user, which requested current page.
</syntaxhighlight>

[http://wiki.multitheftauto.com/wiki/Resource_Web_Access More info about it]

Predefined variables list

2017-05-27T14:20:40Z

Hale:

'''Lua Predefined variables'''
<syntaxhighlight lang="lua">
_G -- returns a table of all global variables
coroutine -- returns a table containing functions for threads
debug -- returns a table containing debug functions.
math -- returns a table that contains mathematical functions.
string -- returns a table containing functions for strings
table -- returns a table that contains functions for tables
_VERSION -- returns a string of the version of lua in format "Lua 5.1"
self -- used in methods.
</syntaxhighlight>

'''MTA Predefined variables'''
<section name="Shared" class="both" show="true">
<syntaxhighlight lang="lua">
exports -- returns a table of resource names containing all export functions
resource -- returns a resource element of the resource the snippet was executed in
resourceRoot -- returns a resource root element of the resource the snippet was executed in
root -- returns the root element of the server
</syntaxhighlight>

</section>
<section name="Client only" class="client" show="true">
<syntaxhighlight lang="lua">
guiRoot -- returns the root element of all GUI elements.
localPlayer -- returns the player element of the local player.
</syntaxhighlight>
</section>
The list of hidden variables, that can be found in functions - handlers:
<section name="Shared" class="both" show="true">
<syntaxhighlight lang="lua">
source -- The player or element the event was attached to
this -- Element, which was attached function-handler.
eventName -- the name of the event ("onResourceStart", "onPlayerWasted" etc.)
</syntaxhighlight>
</section>

<section name="Server only" class="server" show="true">
<syntaxhighlight lang="lua">
client -- the client that called the event
</syntaxhighlight>

</section>

[http://wiki.multitheftauto.com/wiki/AddEventHandler More details about hidden variables in functions and events]

[[Element_tree]]

List Predefined variables available in the HTTP files:
<syntaxhighlight lang="lua">[php]
requestHeaders -- table, contains all HTTP headlines current page.
form -- table, contains all POST and GET settings, transferred current page.
cookies -- table, contains all COOKIE, transferred current page.
hostname -- string, contains IP or name host, which requested current page.
url -- string, URL current page.
user -- element, account user, which requested current page.
</syntaxhighlight>

[http://wiki.multitheftauto.com/wiki/Resource_Web_Access More info about it]

Singleton

2017-05-25T12:18:30Z

Hale: /* Requirements */

{{Useful Class}}
__NOTOC__
This class allows you to restrict the instantiation of a specific class to one object.

==Requirements==

sbx320's classLib, can be found Here[https://github.com/sbx320/lua_utils/blob/master/classlib.lua]

OOP on

==Code==
<syntaxhighlight lang="lua">
Singleton = {}

function Singleton:getSingleton(...)
if not self.ms_Instance then
self.ms_Instance = self:new(...)
end
return self.ms_Instance
end

function Singleton:new(...)
self.new = function() end
local inst = new(self, ...)
self.ms_Instance = inst
return inst
end

function Singleton:isInstantiated()
return self.ms_Instance ~= nil
end

function Singleton:virtual_destructor()
for k, v in pairs(super(self)) do
v.ms_Instance = nil
v.new = Singleton.new
end
end
</syntaxhighlight>

'''Call class methods by newest instance'''
==Example==
<syntaxhighlight lang="lua">
-- DEFINE CLASS
TestClass = inherit(Singleton)

function TestClass:run()
-- DO SOMETHING
end

TestClass:getSingleton():run()
</syntaxhighlight>

==See Also==
{{Useful_Classes}}

Singleton

2017-05-25T12:18:02Z

Hale: /* Requirements */

{{Useful Class}}
__NOTOC__
This class allows you to restrict the instantiation of a specific class to one object.

==Requirements==

sbx320's classLib, can be found Here[https://github.com/sbx320/lua_utils/blob/master/classlib.lua]
OOP on

==Code==
<syntaxhighlight lang="lua">
Singleton = {}

function Singleton:getSingleton(...)
if not self.ms_Instance then
self.ms_Instance = self:new(...)
end
return self.ms_Instance
end

function Singleton:new(...)
self.new = function() end
local inst = new(self, ...)
self.ms_Instance = inst
return inst
end

function Singleton:isInstantiated()
return self.ms_Instance ~= nil
end

function Singleton:virtual_destructor()
for k, v in pairs(super(self)) do
v.ms_Instance = nil
v.new = Singleton.new
end
end
</syntaxhighlight>

'''Call class methods by newest instance'''
==Example==
<syntaxhighlight lang="lua">
-- DEFINE CLASS
TestClass = inherit(Singleton)

function TestClass:run()
-- DO SOMETHING
end

TestClass:getSingleton():run()
</syntaxhighlight>

==See Also==
{{Useful_Classes}}

AclGroupGetName

2017-05-22T14:28:28Z

Hale: /* Returns */

__NOTOC__
{{Server function}}

This function is used to get the name of the given ACL group.

==Syntax==

<syntaxhighlight lang="lua">
string aclGroupGetName ( aclgroup aclGroup )
</syntaxhighlight>
{{OOP||[[aclgroup]]:getName|name|}}
===Required Arguments===

*'''aclGroup:''' The ACL group to get the name of

===Returns===

Returns the name of the given ACL group as a string if successful, otherwise ''false'' or ''nil'' if the aclGroup is invalid or it fails for some other reason.

==Example==
This example outputs to the console that "Admin's are ready to watch :)".
<syntaxhighlight lang="lua">addEventHandler("onResourceStart", resourceRoot, function()
outputConsole(aclGroupGetName(aclGetGroup("Admin")).."'s are ready to watch :)",root)
end)
</syntaxhighlight>

==See Also==

{{ACL_functions}}

AclGroupGetName

2017-05-22T14:26:58Z

Hale: /* Example */

__NOTOC__
{{Server function}}

This function is used to get the name of the given ACL group.

==Syntax==

<syntaxhighlight lang="lua">
string aclGroupGetName ( aclgroup aclGroup )
</syntaxhighlight>
{{OOP||[[aclgroup]]:getName|name|}}
===Required Arguments===

*'''aclGroup:''' The ACL group to get the name of

===Returns===

Returns the name of the given ACL group as a string if successfull, ''false''/''nil'' if the aclGroup is invalid or it fails for some other reason.

==Example==
This example outputs to the console that "Admin's are ready to watch :)".
<syntaxhighlight lang="lua">addEventHandler("onResourceStart", resourceRoot, function()
outputConsole(aclGroupGetName(aclGetGroup("Admin")).."'s are ready to watch :)",root)
end)
</syntaxhighlight>

==See Also==

{{ACL_functions}}