MTA includes a complete Access Control List (ACL) that allows you to secure and limit access to the server, its functions and resources in any number of ways.

The key concept of MTA's ACL (and ACLs in general) is that you're giving a specific object a set of rights. In MTA's case objects are one of two things - resources or users. There are numerous ''rights'' available in MTA - these mainly focus on server-side scripting functions.

What this essentially means is that the ACL allows you to choose exactly what functions a resource or user can perform. This can obviously be invaluable - for example preventing all your server's players from being able to ban each other, or preventing your new untested resources from doing the same.

Of course, ''with great power comes great responsibility'' and it is very easily possible to completely break resources - for example, disabling [[spawnPlayer]] for all resources would be a Bad Thing. Of course, there are situations when you might want to do this - if you want to force all your resources to use a spawn manager resource for example, but even this is somewhat draconian.

==Understanding the ACL==
There are two major components to the ACL: groups and ACL lists. They appear as '''<group name="">''' nodes and '''<acl name="" />''' nodes. Their purpose is to:<br \>
'''1.''' Grant users permission to control the server and use resource commands. Examples:''<br \>
*Allowing only admins to use the giveweapon function of freeroam
*Allowing all users to start a resource
'''2.''' Grant resources permission to use script functions and functions of other resources. Examples:<br \>
*Allowing a resource to use the restartResource function
*Allowing a resource to use the call function to use exported functions from another script

===Default Groups===
MTA has provided some default groups with increasing permissions. These groups are:
*'''Everyone'''
*'''Moderator'''
*'''SuperModerator'''
*'''Admin'''
*'''Console''' - This controls permissions of people who are using the console through '''<object name="user.Console" />'''
*'''RPC''' - Remote Procedure Call. Specifically grants access to [[callRemote]] only and disables commands of default resources. Check the function for details.
<br \>

To explain further, I will use the Everyone group as an example. By default it looks like this:
<syntaxhighlight lang="lua"> <group name="Everyone">
<acl name="Default" />
<object name="user.*" />
<object name="resource.*" />
</group>
</syntaxhighlight>
<br \>
You will first notice the acl name inside the group. It defines what permissions the group has. Users and resources in this group will have the permissions specified on the "Default" acl name list. ''Note: You will notice this group is special, in that it includes every user and resource by using a '''wildcard (*)''' where the user or resource name would be.''

Now, scroll further down the ACL and you will see the '''<acl name="Default" />''' listing. Note I have trimmed this list dramatically due to its length.

<syntaxhighlight lang="lua"> <acl name="Default">
<right name="command.start" access="false" />
<right name="command.stop" access="false" />
<right name="command.stopall" access="false" />
...etc etc...
<right name="function.executeCommandHandler" access="false" />
<right name="function.setPlayerMuted" access="false" />
<right name="function.restartResource" access="false" />
...etc etc...
<right name="general.adminpanel" access="false" />
<right name="general.tab_players" access="false" />
<right name="general.tab_resources" access="false" />
...etc etc...
<right name="command.freeze" access="false" />
<right name="command.shout" access="false" />
<right name="command.spectate" access="false" />
...etc etc...
</acl>
</syntaxhighlight>
<br \>
*'''Function''' entries are MTA scripting functions. For example, if a resource needed to use restartResource and was only in the 'Everyone' group (with the 'Default' list), it would be denied access to restartResource and fail to work correctly.
*'''Commands''' are created when a resource uses [[addCommandHandler]]. An example would be typing '''/createvehicle [vehicle]''' in the chatbox for the freeroam resource. This controls whether users in the group using this ACL can use the command. ''Note: commands have no effect on resources within the group. Commands are only related to users.''
**''General is a custom right name group created by the admin resource but it works on the same principles. The script works with them by using [[hasObjectPermissionTo]]''

You will notice some groups such as admin have multiple '''<acl name="" />''' nodes. An example is the admin group:
<syntaxhighlight lang="lua">
<group name="Admin">
<acl name="Moderator" />
<acl name="SuperModerator" />
<acl name="Admin" />
<acl name="RPC" />
<object name="resource.admin" />
<object name="resource.webadmin" />
<object name="user.Ransom" />
</group>
</syntaxhighlight>

This gives all the permissions defined in each '''<acl name="" />''' node in order of listing. So for example, the admin group makes sure all the permissions are given to admins by using all the lists. If there are any conflicts, the lowest entry wins. For example, pretend these 2 acls were in a group in the following order:

'''1.''' '''<acl name="Default">''' sets <right name="general.ModifyOtherObjects" access="false" /> <br\>
'''2.''' '''<acl name="Admin">''' sets <right name="general.ModifyOtherObjects" access="true" /> <br\>
'''3.''' For all users and resources in group admin: <right name="general.ModifyOtherObjects" access="true" /><br\>
<br\>

=== Resource Groups and ACLs ===
You will notice there are some other groups that came with MTA. These were defined by resources that came with MTA. If a resource wants to designate specific ACL rights not provided by the default MTA groups, it can create its own ACL name and a group to use it. I will show AMX's entry as an example. AMX is designed to emulate SA-MP scripts and it needs a certain set of permissions that doesn't fit the default groups well. It is shown below:

<syntaxhighlight lang="lua">
<group name="AMX">
<acl name="AMX" />
<object name="resource.amx" />
</group>

<acl name="AMX">
<right name="general.ModifyOtherObjects" access="true" />
<right name="function.startResource" access="true" />
<right name="function.stopResource" access="true" />
<right name="general.adminpanel" access="false" />
...etc etc...
<right name="command.kick" access="false" />
<right name="command.freeze" access="false" />
<right name="command.mute" access="false" />
...etc etc...
</acl>
</syntaxhighlight>

==Modifying the ACL==
There are three ways you can modify the ACL - how you do it depends who you are.

===HTTP Interface===
You can use the [[Resource/webadmin|webadmin]] http interface to modify the ACL in your web browser. This is by far the easiest way to do so. Just make sure the ''webadmin'' resource is started on your server and visit ''<nowiki>http://ServerIP:HttpPort/</nowiki>''. You can then use the two sections - ACLs and Groups. ACLs allows you to create your Access Control Lists - lists of rights. Groups allow you to group together collections of users and assign ACLs to them. For example, the ACLs section allows you to specify that the Admin ACL has access to the ''start'' console command. You can the go to the Groups section and create an Admin ''group'' that has access to your Admin ''acl''. You can then add users to your Admin ''group''.

===XML file===
You can modify the ACL.xml file manually. This has a fairly straightforward syntax, but it can get a bit confusing at times. If you do it while the server is running, don't forget to call the scripting function [[aclReload]] ("start runcode", "run aclReload()") so the new ACL is loaded, or otherwise stop your server before modifying. This also prevents your changes from being accidentally overwritten by the server.

===Scripting functions===
You can use a large number of ACL scripting functions to modify the ACL on the fly. Of course, you can (and really should!) limit access to the ACL functions with the ACL. Note that the '''admin resource''' that comes with MTA can be used to manage the ACL from the resources tab. You must be setup as admin to use the admin panel. [http://wiki.multitheftauto.com/wiki/Admin Click here for admin setup instructions].

==See Also==
{{ACL functions}}
[[Category:Scripting Concepts]]
[[ru:Access Control List]]

Talk:Tutorial: How To Create DX Window

2014-02-05T19:16:25Z

AlexsSteel: /* Is this necessary? */

User:Renkon

2014-02-05T19:14:56Z

AlexsSteel:

==Who am I==

I'm a 18 year-old boy from Argentina who fancies playing Multi Theft Auto. I started playing SA-MP back in 2007 and moved to MTA in late 2009. Since then I have never left the community (although I got registered in 2010). I'm currently active in Drunk Drivers Club community and the forum itself.

==Services==

At the moment I offer my scripting services for MTA:SA. If you are interested please go to http://forum.mtasa.com/viewtopic.php?f=5&t=68603 (my service's forum thread)

==Feedback==

*Alexs_Steel approves this guy

TakeWeapon

2014-01-18T17:15:00Z

AlexsSteel: /* Example */

__NOTOC__
{{Server function}}
This function removes a specified weapon or ammo from a certain player's inventory.

==Syntax==
<syntaxhighlight lang="lua">bool takeWeapon ( player thePlayer, int weaponId [, int ammo ] )</syntaxhighlight>

===Required Arguments===
*'''thePlayer''': A player object referencing the specified player.
*'''weaponId''': An integer that refers to a [[weapon]] that you wish to remove.

===Optional Arguments===
*'''ammo''': If used, this amount of ammo will be taken instead and the weapon will not be removed.

===Returns===
Returns a ''true'' if the weapon/ammo was removed successfully, ''false'' otherwise.

==Example==
This example removes teargas from player.
<syntaxhighlight lang="lua">
addCommandHandler( 'rtear',
function( thePlayer )
takeWeapon( thePlayer, 17 )
end
)</syntaxhighlight>

==See Also==
{{Weapon functions}}
[[ru:takeWeapon]]

TakeWeapon

2014-01-18T17:14:35Z

AlexsSteel: /* Example */

__NOTOC__
{{Server function}}
This function removes a specified weapon or ammo from a certain player's inventory.

==Syntax==
<syntaxhighlight lang="lua">bool takeWeapon ( player thePlayer, int weaponId [, int ammo ] )</syntaxhighlight>

===Required Arguments===
*'''thePlayer''': A player object referencing the specified player.
*'''weaponId''': An integer that refers to a [[weapon]] that you wish to remove.

===Optional Arguments===
*'''ammo''': If used, this amount of ammo will be taken instead and the weapon will not be removed.

===Returns===
Returns a ''true'' if the weapon/ammo was removed successfully, ''false'' otherwise.

==Example==
This example removes weapon 28 from player.
<syntaxhighlight lang="lua">
addCommandHandler( 'rtear',
function( thePlayer )
takeWeapon( thePlayer, 17 )
end
)</syntaxhighlight>

==See Also==
{{Weapon functions}}
[[ru:takeWeapon]]

TakeWeapon

2014-01-18T17:14:20Z

AlexsSteel:

__NOTOC__
{{Server function}}
This function removes a specified weapon or ammo from a certain player's inventory.

==Syntax==
<syntaxhighlight lang="lua">bool takeWeapon ( player thePlayer, int weaponId [, int ammo ] )</syntaxhighlight>

===Required Arguments===
*'''thePlayer''': A player object referencing the specified player.
*'''weaponId''': An integer that refers to a [[weapon]] that you wish to remove.

===Optional Arguments===
*'''ammo''': If used, this amount of ammo will be taken instead and the weapon will not be removed.

===Returns===
Returns a ''true'' if the weapon/ammo was removed successfully, ''false'' otherwise.

==Example==
This example removes weapon 28 from player.
<syntaxhighlight lang="lua">
addCommandHandler( 'rtear',
function( thePlayer )
takeWeapon( thePlayer, 17 )
end
)[/lua]</syntaxhighlight>

==See Also==
{{Weapon functions}}
[[ru:takeWeapon]]

TakeWeapon

2014-01-18T17:13:33Z

AlexsSteel: /* Example */

__NOTOC__
{{Server function}}
This function removes a specified weapon or ammo from a certain player's inventory.

==Syntax==
<syntaxhighlight lang="lua">bool takeWeapon ( player thePlayer, int weaponId [, int ammo ] )</syntaxhighlight>

===Required Arguments===
*'''thePlayer''': A player object referencing the specified player.
*'''weaponId''': An integer that refers to a [[weapon]] that you wish to remove.

===Optional Arguments===
*'''ammo''': If used, this amount of ammo will be taken instead and the weapon will not be removed.

===Returns===
Returns a ''true'' if the weapon/ammo was removed successfully, ''false'' otherwise.

==Example==
This example removes weapon 28 from player.
<syntaxhighlight lang="lua">
addCommandHandler( 'rtear',
function( thePlayer )
takeWeapon( thePlayer, 17 )
end
)/code>

==See Also==
{{Weapon functions}}
[[ru:takeWeapon]]

AR/مقدمه في البرمجه

2014-01-16T23:24:16Z

AlexsSteel: Reverse

<p align="right">
السكربتات جزء أساسي في تشغيل MTA فتستطيع بإستخدامهم إنشاء تطبيقات لتحسين اللعب ، تختلف أنواع السكربتات فمنها خريطة أو وضع للعب " freeroam , race , deathmatch " وغيرها ..

برمجة السكربتات تعتمد على لغة البرمجة (Lua) [www.lua.org] .
لغة البرمجة تعتمد إعتماداً كلياً على اللغة الإنجليزية , فيجب أن تكون لديك خلفية في اللغة الإنجليزية قبل المتابعة.
لبرمجة سكربت ما تحتاج لمحرر .. ويفضل إستخدام محرر إحترافي لكي يسهل عليك البرمجة مثل :
*Notepad++ [http://notepad-plus-plus.org/download]
*Lua Edit [http://luaedit.sourceforge.net/ LuaEdit]
لكن يفضل إستخدام برنامج MTASE فهو يسهل عملية إنشاء السكربتات وبرمجتها :
* [[MTASE|MTA Script Editor]].'''

==إنشاء سكربت ==
سوف نتعلم كيف نقوم بإنشاء سكربت يدخل اللاعب إلى اللعبة .. خطوة بحطوة
===أين مسار كل البرامج النصية (السكريبتات أو المودات)؟===
الان نتعرف على مجلد المودات أو السكربتات.
اذهب إلى مجلد Multi Theft Auto واتبع المسار التالي:

/Your MTA Server/mods/deathmatch/resources/

سترى الكثير من الملفات. ربما ترى مجلدات صيغتها .zip أو مجلد عادي , وجميعها يقبله الـ MTA ..
ولإنشاء المودات الخاصة بك: قم بعمل مجلد جديد واجعل اسمه كما تريد فمثلاً قم بتسميته "myserver" وهو الذي سنستخدمه بالبرنامج التعليمي
والان يجب أن يكون مسار المجلد الذي قمت بعمله هذا:

/Your MTA Server/mods/deathmatch/resources/myserver/

* myserver: اسم المجلد الذي قمت بتسميته

===تعريف السكربت (إضافة ملف meta.xml)===
حتى يستطيع السيرفر من معرفة المودات, يجب علينا إنشاء ملف meta.xml
" ويكون بداخل مجلد السكربت الذي قمنا بإنشائه وهو "myserver"
ولإنشاء ملف meta.xml : أفتح ملف نصي جديد وقم بتسميته meta.xml وافتحه باستخدام المفكرة =)
ولا تنسى ان يكون بداخل مجلد السكربت .

أدخل الكود التالي في ملف ''meta.xml'':
<syntaxhighlight lang="xml">
<meta>
<info author="إسمك" type="gamemode" name="إسم السكربت" description="وصف بسيط للسكربت" />
<script src="script.lua" />
</meta>
</syntaxhighlight>

هنا يتم تعريف أجزاء السكربت فمثلاً :
* <info ..>
تضع فيه بيانات السكربت .. مثل الإسم والنوع والوصف
* type="gamemode"
تعني أن نوع السكربت هو مود لعب وتوجد أنواع عديدة مثل :
**gamemode
**map
**script

===إنشاء ملف السكربت Lua===
قمنا بوضع هذا السطر في :
*meta.xml
:
<script src="script.lua" />

الآن نقوم بإنشاء ملف نصي بنفس الإسم
**script.lua
بإستخدام برنامج التحرير لديك .. نقوم بإنشاء الكود

<syntaxhighlight lang="lua">
function joinHandler() -- الوظيفة .. وبعدها نقوم بكتابة الإسم
local x = 1959.55 -- تعريف x
local y = -1714.46 -- تعريف y
local z = 10 -- تعريف z
spawnPlayer(source, x, y, z) -- نقوم بإستخدام هذه الوظيفة لإنتاج اللاعب ونقوم بتحديد اللاعب وهو المصدر : source
fadeCamera(source, true) -- نقوم بعمل fade للكاميرا
setCameraTarget(source, source) -- نجعل هدف الكاميرا هو اللاعب
outputChatBox("مرحباً بك في السيرفر", source) -- نقوم بإخراج نص في الدردشة
end
addEventHandler("onPlayerJoin", getRootElement(), joinHandler) -- نقوم بإضافة المعالج حيث سيتم تشغيله بعد الحدث المحدد وهو عند دخول اللا
</syntaxhighlight>
وصف وشرح الكود اعلاه :
سيقوم السكربت بوضع اللاعب في الاحداثيات (x,y,z) المحدده اعلاه, عند دخوله الى السيرفر
لاحظ انه يجب استخدام وظيفة [ ''fadeCamera'' ] ستكون الشاشة سوداء وأيضاً يجب تعيين الكاميرا ( setTargetCamera ) ..

نرى أن '''source''' هو المصدر وهو اللاعب الذي يقوم بالدخول

أيضاً لو رأينا في المعالج
*[[addEventHandler]] - إضافة معالج للحدث
نرى 3 أشياء
*: onPlayerJoin - عند دخول اللاعب
وهو الحدث .. حيث يحدد متى يتم تشغيل المعالج - في هذه الحالة عند دخول اللاعب
*getRootElement() - جلب العنصر الحالي
هذا يقوم بتعيين العنصر الذي يقوم بتشغيل الحدث
*joinHandler
وهو إسم الوظيفة التي قمنا بصناعتها

يمكنك التوسع أكثر في : [[addEventHandler]]

===تشغيل السكربت===
بعد أن تقوم بحفظ أجزاء السكربت في ملف واحد ويمكن حفظه في الملفات التالية :
* مجلد
* أرشيف .zip
ونقوم بنسخه إلى مجلد السكربتات داخل سيرفرك ونقوم بتشغيله بالطريقة العادية.

الآن إنتهينا من صنع السكربت .. بعد هذا سنقوم بصنع سكربت مع أمر
* command
يمكنك المتابعة أو الذهاب إلى دورة صناعة النوافذ
*[[Introduction to Scripting GUI]]

==صناعة أمر بسيط==
لنعد الآن إلى ملف
*script.lua
ونقوم بتعديله قليلاً لإنشاء أمر بسيط يقوم بإنشاء سيارة بجانب اللاعب

<syntaxhighlight lang="lua">
-- في البداية نقوم بكتب وظيفة إنشاء السيارة
function createVehicleForPlayer(thePlayer, command, vehicleModel)
-- هنا نقوم بكتابة وظيفة إنشاء السيارة كـ
-- createVehicle
end

-- نقوم بإضافة الأمر
addCommandHandler("createvehicle", createVehicleForPlayer)
</syntaxhighlight>
''ملاحظة: يمكنك الضغط على الوظائف والتعمق فيها بداخل الويكي.

== الوظيفة ==
الوظيفة هي شيء يسمى

function

الوظيفة هي الشيء التي يتكون عليها الحدث

يمكنك ان تسمي الوظيفة كما شئت ويمكنك أيضاً عدم وضع اسم للوظيفة

'''مثال لـ وظيفة لها إسم'''
<syntaxhighlight lang="lua">
function arabs( ) -- الوظيفة
outputChatBox("مرحباً بك") --s ستلاحظ بـ أن كلمة " مرحباً بك " ظهرت في الشات عند دخول الاعب
end
addEventHandler("onPlayerJoin", root, arabs) -- .الحدث مع اسم الوظيفة
-- root = getRootElement()
</syntaxhighlight>

'''مثال لـ وظيفة ليس لها إسم'''
<syntaxhighlight lang="lua">
addEventHandler("onPlayerWasted", root,
function(_,killer)
outputChatBox( killer .. " من قبل" .. getPlayerName(source) .. " لقد قُتل الاعب" )
end)
</syntaxhighlight>

كما تلاحظ ووضع قوس قريباً من

end)

هذا القوس يكمل القوس الآخر كما نلاحظ في الحدث

addEventHandler(

----

== الحدث ==
الحدث هو شيء يسمى

event

الحدث هو الذي يتكون على بناء الوظيفة
فـ اذا رجعنا الى الامثلة التي في الاعلى سوف نرى عدة احداث ومنها

[[onPlayerWasted]]

الحدث ببساطة يحدد متى سوف تحدث او كيف سوف تحدث الوظائف التي ادخلتها

onPlayerWasted

عند موت الاعب

'''مثال للحدث'''
<syntaxhighlight lang="lua">
function onJoin()
x, y, z = getElementPosition(source) -- s يآتي بمكان الاعب x, y, z
local theVehicle = createVehicle(445, x, y, z) -- s السيارة التي سـ تصنع بمكان الاعب الذي تم تحديده مسبقاً
warpPedIntoVehicle(source, theVehicle) -- s يجعل الاعب داخل السيارة
end
addEventHandler("onPlayerJoin", root, onJoin) -- s الحدث
-- root = getRootElement()
</syntaxhighlight>
هذه الوظيفة مع هذا الحدث سوف يعطون الاعب سيارة عند دخوله السيرفر

ملاحظة الحدث ليس دائم على الوظيفة فـ أيصاً يمكنك تكوين هذه الوظيفة على حدث آخر

'''مثال'''
<syntaxhighlight lang="lua">
function onJoin()
x, y, z = getElementPosition(source)
local theVehicle = createVehicle(445, x, y, z)
warpPedIntoVehicle(source, theVehicle)
end
addEventHandler("onPlayerLogin", root, onJoin)
</syntaxhighlight>
هذا سوف يعطي الاعب سيارة لاكن ليس عند دخوله السيرفر , إنما عند دخوله حسابه

'''Edit'''

مثال آخر
<syntaxhighlight lang="lua">
addEventHandler("onVehicleExplode",root, -- نضيف حدث عند إنفجار اي سيارة
function() -- الوظيفة
setTimer(destroyElement,5000,1,source) -- يخفي السيارة بعد 5 ثواني من انفاجرها
end
)
</syntaxhighlight>
يمكنك ان تجد
الاحداث
والوظائف
كلنت وسيرفر
هنا

كلنت:

'''وظائف كلنت'''

http://wiki.multitheftauto.com/wiki/Client_Scripting_Functions

'''احداث كلنت'''

http://wiki.multitheftauto.com/wiki/Client_Scripting_Events

سيرفر:

'''وظائف سيرفر'''

http://wiki.multitheftauto.com/wiki/Server_Scripting_Functions

'''احداث سيرفر'''

http://wiki.multitheftauto.com/wiki/Server_Scripting_Events

----

== String الـ ==
السترنج هو شيء يوجد في بعض الوظايف التي توجد داخل الام تي اي

مثلاً
<syntaxhighlight lang="lua">
addEventHandler("onResourceStart",resourceRoot, -- الايفنت هنا يجب ان تكون بين سترنق كما الموضح هنا
function()
outputChatBox("تم بدء السكربت") -- s هنا سوف يظهر رسالة بالشات " تم بدء السكربت " عند بدء السكربت ويجب ان تكون سترنق
end
) -- نهاية قوس الحدث
</syntaxhighlight>
السترنق له عدة أشكال , فيمكن ان يكون كالآتي

""

أو

' '

أو

[[]]

فمثلاً اذا نريد ان نخرج رسالة بعلبة الشات

يمكن ان تكون كذلك
<syntaxhighlight lang="lua">
outputChatBox([[مرحباً]])

-- أو كذلك
outputChatBox('مرحباً')

-- أو كذلك

outputChatBox("مرحباً")
</syntaxhighlight>

====Command handlerعن الـ====
.(`) أو زر F8 التي يمكن للاعب ان يعرضها باستخدام زر Consoleهو اسم الامر الذي يمكن للاعب ان يدخله في الـ [[addCommandHandler]] في argument أول

."createVehicleForPlayer"هي وظيفة تُنفذ عند كتابة اللاعب الامر في هذه الحالة لـ [[addCommandHandler]] في argument ثاني

:اذا كنت متمرس في البرمجة, ستعرف انك ستحتاج ان تنفذ وظيفة مثل

<syntaxhighlight lang="lua">
functionName(argument1, argument2, argument3, ..)
</syntaxhighlight>
<syntaxhighlight lang="lua">
functionName(thePlayer, commandName, argument3, ..)
</syntaxhighlight>
If we have a closer look on the lower example above, we can see argument1 is thePlayer and argument2 the commandName. thePlayer is simply the one who typed the command, so whatever you call it, the variable will contain the player who activated the command. commandName is simply the command they typed. So if they typed "/greet", this argument will contain "greet". Argument 3 is something extra the player typed, you'll learn it a little bit further in the tutorial. Never forget that the first 2 arguments are standard arguments, but you can name them to anything you want.

We called the [[addCommandHandler]] function this way already and since ''createVehicleForPlayer'' is a function too, it can be called that way as well. But we are using a command handler for that, which calls it in a similiar manner, internally.

For example: Someone types "createvehicle 468" ingame in the console to spawn a Sanchez, the command handler calls the createVehicleForPlayer function, as '''if''' we would have this line of code in the script:
<syntaxhighlight lang="lua">
createVehicleForPlayer(thePlayer,"createvehicle","468") -- thePlayer is the player element of the player who entered the command
</syntaxhighlight>
As we can see, it provides several parameters: the player who called the command, the command he entered and whatever text he had after that, in this case "468" as vehicle id for the Sanchez. The first two parameters are the same with all command handlers, which you can read on the [[addEventHandler]] page. For this fact, you always have to define at least those two parameters to use any after that (for example to process text that was entered after the command, like in our example the vehicle model id).

''Note: You have to add the command handler AFTER you defined the handler function, else it can't find it. The order of execution matters.''

====Writing the function====
In order to fill the function we created, we need to think about what we have to do:
* Get the players position, so we know where to spawn the vehicle (we want it to appear right beside the player)
* Calculate the position we want to spawn the vehicle at (we don't want it to appear in the player)
* Spawn the vehicle
* Check if it has been spawned successfully, or output a message

In order to achieve our goals, we have to use several functions. To find function we need to use, we should visit the [[Scripting Functions|Server Functions List]]. First we need a function to get the players position. Since players are Elements, we first jump to the '''Element functions''' where we find the [[getElementPosition]] function. By clicking on the function name in the list, you get to the function description. There we can see the syntax, what it returns and usually an example. The syntax shows us what arguments we can or have to submit.

For [[getElementPosition]], the syntax is:
<syntaxhighlight lang="lua">
float, float, float getElementPosition ( element theElement )
</syntaxhighlight>

The three ''float'' in front of the function name are the return type. In this case it means the function returns three floating point numbers. (x, y and z) Within the parentheses, you can see what arguments you have to submit. In this case only the element whose position you want to get, which is the player in our example.

<syntaxhighlight lang="lua">
function createVehicleForPlayer(thePlayer, command, vehicleModel)
-- get the position and put it in the x,y,z variables
-- (local means, the variables only exist in the current scope, in this case, the function)
local x,y,z = getElementPosition(thePlayer)
end
</syntaxhighlight>

Next we want to ensure that the vehicle won't spawn directly in the player, so we add a few units to the ''x'' variable, which will make it spawn east from the player.

<syntaxhighlight lang="lua">
function createVehicleForPlayer(thePlayer, command, vehicleModel)
local x,y,z = getElementPosition(thePlayer) -- get the position of the player
x = x + 5 -- add 5 units to the x position
end
</syntaxhighlight>

Now we need another function, one to spawn a vehicle. We once again search for it on the [[Scripting Functions|Server Functions List]], this time - since we are talking about vehicles - in the '''Vehicle functions''' section, where we will choose [[createVehicle]]. In this function's syntax, we only have one return type (which is more common), a vehicle element that points to the vehicle we just created. Also, we see that some arguments are enclosed within [ ] which means that those are optional.

We already have all arguments we need for [[createVehicle]] in our function: The position we just calculated in the ''x,y,z'' variables and the model id that we provided through the command ("createvehicle 468") and can access in the function as ''vehicleModel'' variable.

<syntaxhighlight lang="lua">
function createVehicleForPlayer(thePlayer, command, vehicleModel)
local x,y,z = getElementPosition(thePlayer) -- get the position of the player
x = x + 5 -- add 5 units to the x position
-- create the vehicle and store the returned vehicle element in the ''createdVehicle'' variable
local createdVehicle = createVehicle(tonumber(vehicleModel),x,y,z)
end
</syntaxhighlight>

Of course this code can be improved in many ways, but at least we want to add a check whether the vehicle was created successfully or not. As we can read on the [[createVehicle]] page under '''Returns''', the function returns ''false'' when it was unable to create the vehicle. Thus, we check the value of the ''createVehicle'' variable.

Now we have our complete script:
<syntaxhighlight lang="lua">
function createVehicleForPlayer(thePlayer, command, vehicleModel)
local x,y,z = getElementPosition(thePlayer) -- get the position of the player
x = x + 5 -- add 5 units to the x position
local createdVehicle = createVehicle(tonumber(vehicleModel),x,y,z)
-- check if the return value was ''false''
if (createdVehicle == false) then
-- if so, output a message to the chatbox, but only to this player.
outputChatBox("Failed to create vehicle.",thePlayer)
end
end
addCommandHandler("createvehicle", createVehicleForPlayer)
</syntaxhighlight>

As you can see, we introduced another function with [[outputChatBox]]. By now, you should be able to explore the function's documentation page yourself. For more advanced scripting, please check out the [[Map manager|Map Manager]].

==What you need to know==
You already read some things about resources, command handlers and finding functions in the documentation in the first paragraph, but there is much more to learn. This section will give you a rather short overview over some of these things, while linking to related pages if possible.
===Clientside and Serverside scripts===
You may have already noticed these or similiar terms (Server/Client) somewhere on this wiki, mostly in conjunction with functions. MTA not only supports scripts that run on the server and provide commands (like the one we wrote above) or other features, but also scripts that run on the MTA client the players use to connect to the server. The reason for this is, that some features MTA provides have to be clientside (like a GUI - Graphical User Interface), others should be because they work better and still others are better off to be serverside or just don't work clientside.

Most scripts you will make (gamemodes, maps) will probably be serverside, like the one we wrote in the first section. If you run into something that can't be solved serverside, you will probably have to make it clientside. For a clientside script for example, you would create a ordinary script file (for example called ''client.lua'') and specify it in the meta.xml, like this:
<syntaxhighlight lang="xml">
<script src="client.lua" type="client" />
</syntaxhighlight>
The ''type'' attribute defaults to 'server', so you only need to specify it for clientside scripts. When you do this, the clientside script will be downloaded to the player's computer once he connects to the server. Read more about [[Client side scripts]].

===More complex resources===
The previous section showed briefly how to add clientside scripts to the resource, but there is also much more possible. As mentioned at the very top of this page, resources can be pretty much everything. Their purpose is defined by what they do. Let's have some theoretical resources, by looking at the files it contains, the ''meta.xml'' and what they might do:

====First example - A utility script====
<syntaxhighlight lang="xml">
/admin_commands
/meta.xml
/commands.lua
/client.lua
</syntaxhighlight>
<syntaxhighlight lang="xml">
<meta>
<info author="Someguy" description="admin commands" />
<script src="commands.lua" />
<script src="client.lua" type="client" />
</meta>
</syntaxhighlight>

* The ''commands.lua'' provides some admin commands, like banning a player, muting or something else that can be used to admin the server
* The ''client.lua'' provides a GUI to be able to perform the mentioned actions easily

This example might be running all the time (maybe even auto-started when the server starts) as it's useful during the whole gaming experience and also wont interfere with the gameplay, unless an admin decides to take some action of course.

====Second example - A gamemode====
<syntaxhighlight lang="xml">
/counterstrike
/meta.xml
/counterstrike.lua
/buymenu.lua
</syntaxhighlight>
<syntaxhighlight lang="xml">
<meta>
<info author="Someguy" description="Counterstrike remake" type="gamemode" />
<script src="counterstrike.lua" />
<script src="buymenu.lua" type="client" />
</meta>
</syntaxhighlight>

* The ''counterstrike.lua'' contains similiar to the following features:
** Let players choose their team and spawn them
** Provide them with weapons, targets and instructions (maybe read from a Map, see below)
** Define the game's rules, e.g. when does the round end, what happens when a player dies
** .. and maybe some more
* The ''buymenu.lua'' is a clientside script and creates a menu to buy weapons

This example can be called a gamemode, since it not only intereferes with the gameplay, but actually defines the rules of it. The ''type'' attribute indicates that this example works with the [[Map manager]], yet another resource that was written by the QA Team to manage gamemodes and map loading. It is highly recommended that you base your gamemodes on the techniques it provides.

This also means that the gamemode probably won't run without a map. Gamemodes should always be as generic as possible. An example for a map is stated in the next example.

====Third example - A Map====
<syntaxhighlight lang="xml">
/cs-airport
/meta.xml
/airport.map
/airport.lua
</syntaxhighlight>
<syntaxhighlight lang="xml">
<meta>
<info author="Someguy" description="Counterstrike airport map" type="map" gamemodes="counterstrike" />
<map src="airport.map" />
<script src="airport.lua" />
</meta>
</syntaxhighlight>

* The ''airport.map'' in a XML file that provides information about the map to the gamemode, these may include:
** Where the players should spawn, with what weapons, what teams there are
** What the targets are
** Weather, World Time, Timelimit
** Provide vehicles
* The ''airport.lua'' might contain map-specific features, that may include:
** Opening some door/make something explode when something specific happens
** Create or move some custom objects, or manipulate objects that are created through the .map file
** .. anything else map-specific you can think of

As you can see, the ''type'' attribute changed to 'map', telling the [[Map manager]] that this resource is a map, while the ''gamemodes'' attribute tells it for which gamemodes this map is valid, in this case the gamemode from the above example.
What may come as a surprise is that there is also a script in the Map resource. Of course this is not necessarily needed in a map, but opens a wide range of possibilities for map makers to create their own world within the rules of the gamemode they create it for.

The ''airport.map'' file might look similiar to this:
<syntaxhighlight lang="xml">
<map mode="deathmatch" version="1.0">
<terrorists>
<spawnpoint posX="2332.23" posY="-12232.33" posZ="4.42223" skins="23-40" />
</terrorists>
<counterterrorists>
<spawnpoint posX="2334.23443" posY="-12300.233" posZ="10.2344" skins="40-50" />
</counterterrorists>

<bomb posX="23342.23" posY="" posZ="" />

<vehicle posX="" posY="" posZ="" model="602" />
<vehicle posX="" posY="" posZ="" model="603" />
</map>
</syntaxhighlight>

When a gamemode is started with a map, the map resources is automatically started by the mapmanager and the information it contains can be read by the gamemode resource. When the map changes, the current map resource is stopped and the next map resource is started. For a more in-depth explanation and examples of how map resources are utilized in the main script, please visit the [[Writing Gamemodes]] page.

===Events===
Events are the way MTA tells scripts about things that happen. For example when a player dies, the [[onPlayerWasted]] event is triggered. In order to perform any actions when a player dies, you have to prepare yourself similiar to adding a command handler, as shown in [[#Writing_the_script|the first chapter]].

This example will output a message with the name of the player who died:
<syntaxhighlight lang="lua">
function playerDied(totalAmmo, killer, killerWeapon, bodypart)
outputChatBox(getPlayerName(source).." died!")
end
addEventHandler("onPlayerWasted",getRootElement(),playerDied)
</syntaxhighlight>

Instead of showing what arguments are needed, the documentation page for Events shows what parameters are passed to the handler function, similiar to the way a [[#About_command_handlers|command handler]] does, just that it is different from event to event. Another important point is the ''source'' variable, that exists in handler functions. It doesn't have to be added to the parameter list of the function, but it still exists. It has a different value from event to event, for player events (as in the example above) it is the player element. As another example, you can take a look at the basic spawning player script in the first section to get an idea how ''source'' is used.

==Where to go from here==
You should now be familiar with the most basic aspects of MTA scripting and also a bit with the documentation. The [[Main Page]] provides you with links to more information, Tutorials and References that allow a deeper look into the topics you desire to learn about.

From here we recommend reading the [[debugging]] tutorial. Good debugging skills are an absolute necessity when you are making scripts.

[[ru:Scripting Introduction]]
[[it:Introduzione allo scripting]]
[[es:Introducción a la Programación]]
</p>

User talk:TheBest12

2014-01-16T23:22:46Z

AlexsSteel: ;)

== bam ==

ban this idiot

== Comments ==

Alexs_Steel: +1

Introduction to Scripting the GUI

2014-01-16T23:20:57Z

AlexsSteel: *facepalm* "hack" solved

One important feature in MTA:SA is the ability to script customized GUI (Graphic User Interface). The GUI consists of windows, button, edit boxes, check boxes... Almost every standard form components in graphical environments. They can be displayed while the user is in game, and used for inputs and outputs in place of traditional commands.

[[Image:AdminGUI.png|thumb|Admin Console GUI]]

==A tutorial to make a login window==
In this tutorial we'll make a simple login window, with two input boxes and a button. The window appears when the player joins the game, and once the button is clicked, the player is spawned. The tutorial will continue the gamemode we made in [[Scripting Introduction|Introduction to Scripting]] ''(If you have used the [[Scripting Introduction|Introduction to Scripting]], you will need to remove or comment the [[spawnPlayer]] line in the "joinHandler" function in your code, as we will be replacing it with a gui alternative in this tutorial)''. We'll also take a look at client-side scripting.

===Draw the window===
All the GUI must be made client side. It is also a good practice to keep all the client scripts in a separate folder.

Browse to /Your MTA Server/mods/deathmatch/resources/myserver/ directory, and create a folder named "client". Under /client/ directory, create a text file and name it "gui.lua".

In this file we will write a funtion that draws the window. To create a window we will use [[guiCreateWindow]]:
<syntaxhighlight lang="lua">
function createLoginWindow()
-- define the X and Y positions of the window
local X = 0.375
local Y = 0.375
-- define the width and height of the window
local Width = 0.25
local Height = 0.25
-- create the window and save its element value into the variable 'wdwLogin'
-- click on the function's name to read its documentation
wdwLogin = guiCreateWindow(X, Y, Width, Height, "Please Log In", true)
end
</syntaxhighlight>

===Relative and Absolute===
Note that the final argument passed to guiCreateWindow in the above example is ''true''. This indicates that the coordinates and dimensions of the window are '''relative''', meaning they are a ''percentage'' of the total screen size. This means that if the far left side of the screen is 0, and the far right is 1, an X position of 0.5 would represent the centre point of the screen. Similarly, if the top of the screen is 0 and the bottom is 1, a Y position of 0.2 would be 20% of the way down the screen. The same principles apply to both Width and Height as well (with a Width value of 0.5 meaning the window will be half as wide as the screen).

The alternative to using relative values is using '''absolute''' (by passing ''false'' instead of true to guiCreateWindow). Absolute values are calculated as the total number of pixels from the top-left corner of the parent (if no gui element parent is specified, the parent is the screen itself). If we assume a screen resolution of 1920x1200, the far left side of the screen being 0 pixels and the far right being 1920 pixels, an X position of 960 will represent the centre point of the screen. Similarly, if the top of the screen is 0 pixels and the bottom is 1200, a Y position of 20 would be 20 pixels down from the top of the screen. The same principles apply to both Width and Height as well (with a Width value of 50 meaning the window will be 50 pixels wide). ''You can use [[guiGetScreenSize]] and a little maths to calculate certain absolute positions.''

The differences between using relative and absolute values is quite simple; gui created using absolute values will always remain exactly the same pixel size and position, while gui created using relative values will always be a percentage of its parent's size.

Absolute is generally easier to maintain when editing code by hand, however your choice of type depends on the situation you are using it for.

For the purposes of this introduction we will be using relative values.

===Adding the components===
Next, we'll add the text labels (saying "username:" and "password:"), edit boxes (for entering your data) and a button to log in.

To create buttons we use [[guiCreateButton]] and to create edit boxes use [[guiCreateEdit]]:

'''Note that we are now writing more code for our existing 'createLoginWindow' function. This is not a new function and is meant to replace what you already have.'''
<syntaxhighlight lang="lua">
function createLoginWindow()
local X = 0.375
local Y = 0.375
local Width = 0.25
local Height = 0.25
wdwLogin = guiCreateWindow(X, Y, Width, Height, "Please Log In", true)

-- define new X and Y positions for the first label
X = 0.0825
Y = 0.2
-- define new Width and Height values for the first label
Width = 0.25
Height = 0.25
-- create the first label, note the final argument passed is 'wdwLogin' meaning the window
-- we created above is the parent of this label (so all the position and size values are now relative to the position of that window)
guiCreateLabel(X, Y, Width, Height, "Username", true, wdwLogin)
-- alter the Y value, so the second label is slightly below the first
Y = 0.5
guiCreateLabel(X, Y, Width, Height, "Password", true, wdwLogin)

X = 0.415
Y = 0.2
Width = 0.5
Height = 0.15
edtUser = guiCreateEdit(X, Y, Width, Height, "", true, wdwLogin)
Y = 0.5
edtPass = guiCreateEdit(X, Y, Width, Height, "", true, wdwLogin)
-- set the maximum character length for the username and password fields to 50
guiEditSetMaxLength(edtUser, 50)
guiEditSetMaxLength(edtPass, 50)

X = 0.415
Y = 0.7
Width = 0.25
Height = 0.2
btnLogin = guiCreateButton(X, Y, Width, Height, "Log In", true, wdwLogin)

-- make the window invisible
guiSetVisible(wdwLogin, false)
end
</syntaxhighlight>
Note that every GUI component created is a child of the window, this is done by specifying the parent element (wdwLogin, in this case) when creating the component.

This is very useful because not only does it mean that all the components are attached to the window and will move with it, but also that any changes done to the parent window will be applied down the tree to these child components. For example, we can now hide all of the GUI we just created by simply hiding the window:
<syntaxhighlight lang="lua">
guiSetVisible(wdwLogin, false) --hides all the GUI we made so we can show them to the player at the appropriate moment.
</syntaxhighlight>

===Using the function we wrote===
The createLoginWindow function is now complete, but it won't do anything until we call it. It is recommended to create all GUI when the client resource starts, hide them, and show them to the player later when needed. Therefore, we'll write an event handler for "[[onClientResourceStart]]" to create the window:
<syntaxhighlight lang="lua">
-- attach the event handler to the root element of the resource
-- this means it will only trigger when its own resource is started
addEventHandler("onClientResourceStart", getResourceRootElement(getThisResource()),
function ()
createLoginWindow()
end
)
</syntaxhighlight>

As this is a log in window, we now need to show the window when the player joins the game.
This can be done using the same event, "[[onClientResourceStart]]", so we can modify the above code to include showing the window:

'''Note that we are now writing more code for our existing 'onClientResourceStart' handler. This is not a new event handler and is meant to replace what you already have.'''
<syntaxhighlight lang="lua">
addEventHandler("onClientResourceStart", getResourceRootElement(getThisResource()),
function ()
-- create the log in window and its components
createLoginWindow()

-- output a brief welcome message to the player
outputChatBox("Welcome to My MTA:SA Server, please log in.")

-- if the GUI was successfully created, then show the GUI to the player
if (wdwLogin ~= nil) then
guiSetVisible(wdwLogin, true)
else
-- if the GUI hasnt been properly created, tell the player
outputChatBox("An unexpected error has occurred and the log in GUI has not been created.")
end

-- enable the players cursor (so they can select and click on the components)
showCursor(true)
-- set the input focus onto the GUI, allowing players (for example) to press 'T' without the chatbox opening
guiSetInputEnabled(true)
end
)
</syntaxhighlight>

Note that we have a simple security check before making the window visible, so in the unlikely event that the window has not been created, meaning wdwLogin is not a valid element, we don't get an error and just inform the player what has happened.
In the next step, we will create the button functionality for the log in button.

==Scripting the button==
Now that we have created our GUI and shown it to the player, we need to make it work.

===Detecting the click===
When the player clicks on any part of the GUI, the event "[[onClientGUIClick]]" will be triggered for the GUI component you clicked on. This allows us to easily detect any clicks on the GUI elements we want to use.
For example, we can attach the event to the btnLogin button to catch any clicks on it:
<syntaxhighlight lang="lua">
-- attach the event onClientGUIClick to btnLogin and set it to trigger the 'clientSubmitLogin' function
addEventHandler("onClientGUIClick", btnLogin, clientSubmitLogin, false)
</syntaxhighlight>
'''Note the final argument passed is "false". This indicates that the event will only trigger directly on btnLogin, not if the event has propagated up or down the tree. Setting this to "true" while attaching to gui elements will mean that clicking on any element in the same branch will trigger this event.'''

This line of code can now be added inside the createLoginWindow function. It is a common mistake to try and attach events to non-existant GUI elements, so make sure you always attach your events '''after''' the gui element (in this case, the button) has been created:

'''Note that we are now writing more code for our existing 'createLoginWindow' function.'''
<syntaxhighlight lang="lua">
function createLoginWindow()
-- create all our GUI elements
...

-- now add our onClientGUIClick event to the button we just created
addEventHandler("onClientGUIClick", btnLogin, clientSubmitLogin, false)
</syntaxhighlight>

===Managing the click===
Now that we can detect when the player clicks on the button, we need to write code to manage what happens when they do.
In our [[onClientGUIClick]] event handle, we told it to call the function clientSubmitLogin whenever btnLogin is clicked.
Therefore, we can now use the function clientSubmitLogin to control what happens when the button is clicked:
<syntaxhighlight lang="lua">
-- create the function and define the 'button' and 'state' parameters
-- (these are passed automatically by onClientGUIClick)
function clientSubmitLogin(button,state)
-- if our login button was clicked with the left mouse button, and the state of the mouse button is up
if button == "left" and state == "up" then
-- move the input focus back onto the game (allowing players to move around, open the chatbox, etc)
guiSetInputEnabled(false)
-- hide the window and all the components
guiSetVisible(wdwLogin, false)
-- hide the mouse cursor
showCursor(false)
end
end
</syntaxhighlight>
Now, when the button is clicked, the window will be hidden and all controls will be returned to the player. Next, we will tell the server to allow the player to spawn.

===Triggering the server===
Triggering the server can be done using [[triggerServerEvent]]. This allows you to trigger a specified event on the server from the client. The same can be done in reverse using [[triggerClientEvent]].
Here, we use the [[triggerServerEvent]] function to call our own custom event on the server, named "submitLogin", which will then control the spawning of the player serverside.

'''Note that we are now writing more code for our existing 'clientSubmitLogin' function. This is not a new function and is meant to replace what you already have.'''
<syntaxhighlight lang="lua">
function clientSubmitLogin(button,state)
if button == "left" and state == "up" then
-- get the text entered in the 'username' field
local username = guiGetText(edtUser)
-- get the text entered in the 'password' field
local password = guiGetText(edtPass)

-- if the username and password both exist
if username and password then
-- trigger the server event 'submitLogin' and pass the username and password to it
triggerServerEvent("submitLogin", getRootElement(), username, password)

-- hide the gui, hide the cursor and return control to the player
guiSetInputEnabled(false)
guiSetVisible(wdwLogin, false)
showCursor(false)
else
-- otherwise, output a message to the player, do not trigger the server
-- and do not hide the gui
outputChatBox("Please enter a username and password.")
end
end
end
</syntaxhighlight>

===Creating the serverside event===
At this point we now have all the code needed on the client side, so open up your serverside 'script.lua' file (from the [[Scripting Introduction|Introduction to Scripting]]) or another suitable serverside file to work with.

On the server side, recall that we are spawning the player as soon as they login.
So, first of all, we will need to define the custom event that we used before on the client. This can be done using [[addEvent]] and [[addEventHandler]].
<syntaxhighlight lang="lua">
-- create our loginHandler function, with username and password parameters (passed from the client gui)
function loginHandler(username,password)

end

-- define our custom event, and allow it to be triggered from the client ('true')
addEvent("submitLogin",true)
-- add an event handler so that when submitLogin is triggered, the function loginHandler is called
addEventHandler("submitLogin",root,loginHandler)
</syntaxhighlight>

===Logging in===
Now we have a function that is called through the custom event 'submitLogin', we can start to work on logging in and spawning the player, using our 'loginHandler' function:
<syntaxhighlight lang="lua">
function loginHandler(username,password)
-- check that the username and password are correct
if username == "user" and password == "apple" then
-- the player has successfully logged in, so spawn them
if (client) then
spawnPlayer(client, 1959.55, -1714.46, 10)
fadeCamera(client, true)
setCameraTarget(client, client)
outputChatBox("Welcome to My Server.", client)
end
else
-- if the username or password are not correct, output a message to the player
outputChatBox("Invalid username and password. Please re-connect and try again.",client)
end
end

addEvent("submitLogin",true)
addEventHandler("submitLogin",root,loginHandler)
</syntaxhighlight>
'''For the purposes of this tutorial, a very basic username and password system is shown. For a more comprehensive alternative, you can use the Account System or a MySQL database.'''

Also note the use of the variable "client", it's an internal variable used by MTA to identify the player who triggered the event.

Finally, do not forget to include the new gui.lua file in the meta.xml of the main resource, and label it as a client script:
<syntaxhighlight lang="xml">
<script src="client/gui.lua" type="client" />
</syntaxhighlight>

At this point, we now have a basic login window that checks the player's username and password when the login button is clicked. If they are correct, the player is automatically spawned.

For further help with GUI, see the [[:Category:GUI_Tutorials|GUI tutorials]].

[[Category:GUI_Tutorials]]
[[it:Introduzione_allo_scripting_della_GUI]]
[[ru:Introduction to Scripting the GUI]]
[[es:Introducción a la Programación de GUI]]

Scripting Introduction

2014-01-16T23:17:07Z

AlexsSteel:

Resources are a key part of MTA. A resource is essentially a folder or zip file that contains a collection of files, plus a meta file that describes to the server how the resource should be loaded and what files it does contain. A resource can be seen as being partly equivalent to a program running in an operating system - it can be started and stopped, and multiple resources can run at once.

Everything that has to do with scripting happens in resources, what a resource does defines if it is a gamemode, a map or anything else. MTA comes with resources that you can optionally use in your gamemodes, such as maplimits to keep playings within a playing area or deathpickups to create weapon pickups.
{{tip|Your first step to begin Lua scripting should be using an Lua editor. This makes scripting much easier. We recommend [http://www.sublimetext.com/ Sublime Text], [http://notepad-plus.sourceforge.net/uk/site.htm Notepad++] or [http://luaedit.sourceforge.net/ LuaEdit]. There is also an unofficial [[MTASE|MTA Script Editor]] (in work-in-progress state) that you can test out.}}

==Creating a working script==
We will first learn how to make a basic script that lets the player walk around in the city, step by step.
===Where are all the scripts?===
Let's take a look at the script's file structure. Go to your MTA Server folder, and follow the path below:

server/mods/deathmatch/resources/

You will see a lot of .zip files, which are the packaged sample scripts shipped with MTA. Each file is a "resource", and they will all be unzipped and loaded by the server when it starts. To create your own resource, simply make a folder with your preferred name. We'll use "myserver" for this tutorial.

Now you should be under this directory:

server/mods/deathmatch/resources/myserver/

===Identifying your resource===
In order to let the server know what's in the resource, a ''meta.xml'' file must be created to list the resource's content. It must be located in the resource's root directory, which is the "myserver" folder in our case. So create a text file and name it "meta.xml", and open it with notepad.

Enter the following codes in the ''meta.xml'' file:
<syntaxhighlight lang="xml">
<meta>
<info author="YourName" type="gamemode" name="My Server" description="My first MTA server" />
<script src="script.lua" />
</meta>
</syntaxhighlight>
In the ''<info />'' tag, there's a "type" field which indicates that the resource is a ''gamemode'' instead of a regular include or a ''map'', which will be explained later. A gamemode is what you need to make a stand-alone server.

The ''<script />'' tag indicates the script files contained in the resource, which we will create next.
===Creating a simple script===
Note that in the ''<script />'' tag above, the .lua file is not under another directory. Therefore we'll create the file in the same folder as meta.xml. Now you can copy and paste the following code into script.lua:
<syntaxhighlight lang="lua">
local spawnX, spawnY, spawnZ = 1959.55, -1714.46, 10
function joinHandler()
spawnPlayer(source, spawnX, spawnY, spawnZ)
fadeCamera(source, true)
setCameraTarget(source, source)
outputChatBox("Welcome to My Server", source)
end
addEventHandler("onPlayerJoin", getRootElement(), joinHandler)
</syntaxhighlight>
The script will spawn you at the coordinate (x, y, z) specified above, when you join the game. Note that the ''fadeCamera'' function must be used or the screen will be black. Also, in releases after DP2, you need to set the camera target (otherwise all the player will see is blue sky).

The '''source''' variable indicates who triggered the event. Since a player has joined when the code is triggered, you use this variable to look which has joined. So it'll spawn that player instead of everyone or a random person.

If we have a closer look on [[addEventHandler]], you can see 3 things: 'onPlayerJoin', which indicates when it's triggered. getRootElement(), which shows by what/who it can be triggered. (getRootElement() is everything/everyone) And joinHandler, which indicates the function that has to be triggered after the event is triggered. Other details will be explained later in another example, now let's just run the server and try it out!

===Running the script===
To get the server started, simply run the executable under the server/ directory. A list of server stats will be shown first; note the port number, which you'll need when joining the game. Then the server loads all the resources under the mods/deathmatch/resources/ directory, and then "ready to accept connections!"

Before you connect to the server, you must run the gamemode. Type "start myserver" and press Enter. The server will start the gamemode you just created, and will also show any errors and warnings from this point on. Now you can start the MTA client, and "Quick Connect" using the IP address of your server and the port number you saw earlier. If all goes well, after a few seconds your character will be walking on the streets of Los Santos.

Next we'll add a command to your script that players can use to spawn a vehicle beside their position. You may skip it and check out more advanced scripting with the [[Map manager|Map Manager]], which continues this tutorial. Another branch from this tutorial is [[Introduction to Scripting GUI]], you may follow it to see how Graphical User Interface in MTA is drawn and scripted.

==Creating a simple command==
Let's go back to the content of the ''script.lua'' file. As mentioned above, we want to provide a command to create a vehicle beside your current position in the game. Firstly we need to create a function we want to call and a command handler that creates the command the player will be able to enter in the console.

<syntaxhighlight lang="lua">
-- create the function the command handler calls, with the arguments: thePlayer, command, vehicleModel
function createVehicleForPlayer(thePlayer, command, vehicleModel)
-- create a vehicle and stuff
end

-- create a command handler
addCommandHandler("createvehicle", createVehicleForPlayer)
</syntaxhighlight>
''Note: Function names are clickable in code examples on the wiki and linked to the functions' documentation.''

====About command handlers====
The first argument of [[addCommandHandler]] is the name of the command the player will be able to enter, the second argument is the function this will call, in this case ''createVehicleForPlayer''.

If you have already experience in scripting, you will know that you call a function like this:
<syntaxhighlight lang="lua">
functionName(argument1, argument2, argument3, ..)
</syntaxhighlight>
<syntaxhighlight lang="lua">
functionName(thePlayer, commandName, argument3, ..)
</syntaxhighlight>
If we have a closer look on the lower example above, we can see argument1 is thePlayer and argument2 the commandName. thePlayer is simply the one who typed the command, so whatever you call it, the variable will contain the player who activated the command. commandName is simply the command they typed. So if they typed "/greet", this argument will contain "greet". Argument 3 is something extra the player typed, you'll learn it a little bit further in the tutorial. Never forget that the first 2 arguments are standard arguments, but you can name them to anything you want.

We called the [[addCommandHandler]] function this way already and since ''createVehicleForPlayer'' is a function too, it can be called that way as well. But we are using a command handler for that, which calls it in a similiar manner, internally.

For example: Someone types "createvehicle 468" ingame in the console to spawn a Sanchez, the command handler calls the createVehicleForPlayer function, as '''if''' we would have this line of code in the script:
<syntaxhighlight lang="lua">
createVehicleForPlayer(thePlayer,"createvehicle","468") -- thePlayer is the player element of the player who entered the command
</syntaxhighlight>
As we can see, it provides several parameters: the player who called the command, the command he entered and whatever text he had after that, in this case "468" as vehicle id for the Sanchez. The first two parameters are the same with all command handlers, which you can read on the [[addEventHandler]] page. For this fact, you always have to define at least those two parameters to use any after that (for example to process text that was entered after the command, like in our example the vehicle model id).

''Note: You have to add the command handler AFTER you defined the handler function, else it can't find it. The order of execution matters.''

====Writing the function====
In order to fill the function we created, we need to think about what we have to do:
* Get the players position, so we know where to spawn the vehicle (we want it to appear right beside the player)
* Calculate the position we want to spawn the vehicle at (we don't want it to appear in the player)
* Spawn the vehicle
* Check if it has been spawned successfully, or output a message

In order to achieve our goals, we have to use several functions. To find function we need to use, we should visit the [[Scripting Functions|Server Functions List]]. First we need a function to get the players position. Since players are Elements, we first jump to the '''Element functions''' where we find the [[getElementPosition]] function. By clicking on the function name in the list, you get to the function description. There we can see the syntax, what it returns and usually an example. The syntax shows us what arguments we can or have to submit.

For [[getElementPosition]], the syntax is:
<syntaxhighlight lang="lua">
float, float, float getElementPosition ( element theElement )
</syntaxhighlight>

The three ''float'' in front of the function name are the return type. In this case it means the function returns three floating point numbers. (x, y and z) Within the parentheses, you can see what arguments you have to submit. In this case only the element whose position you want to get, which is the player in our example.

<syntaxhighlight lang="lua">
function createVehicleForPlayer(thePlayer, command, vehicleModel)
-- get the position and put it in the x,y,z variables
-- (local means, the variables only exist in the current scope, in this case, the function)
local x,y,z = getElementPosition(thePlayer)
end
</syntaxhighlight>

Next we want to ensure that the vehicle won't spawn directly in the player, so we add a few units to the ''x'' variable, which will make it spawn east from the player.

<syntaxhighlight lang="lua">
function createVehicleForPlayer(thePlayer, command, vehicleModel)
local x,y,z = getElementPosition(thePlayer) -- get the position of the player
x = x + 5 -- add 5 units to the x position
end
</syntaxhighlight>

Now we need another function, one to spawn a vehicle. We once again search for it on the [[Scripting Functions|Server Functions List]], this time - since we are talking about vehicles - in the '''Vehicle functions''' section, where we will choose [[createVehicle]]. In this function's syntax, we only have one return type (which is more common), a vehicle element that points to the vehicle we just created. Also, we see that some arguments are enclosed within [ ] which means that those are optional.

We already have all arguments we need for [[createVehicle]] in our function: The position we just calculated in the ''x,y,z'' variables and the model id that we provided through the command ("createvehicle 468") and can access in the function as ''vehicleModel'' variable.

<syntaxhighlight lang="lua">
function createVehicleForPlayer(thePlayer, command, vehicleModel)
local x,y,z = getElementPosition(thePlayer) -- get the position of the player
x = x + 5 -- add 5 units to the x position
-- create the vehicle and store the returned vehicle element in the ''createdVehicle'' variable
local createdVehicle = createVehicle(tonumber(vehicleModel),x,y,z)
end
</syntaxhighlight>

Of course this code can be improved in many ways, but at least we want to add a check whether the vehicle was created successfully or not. As we can read on the [[createVehicle]] page under '''Returns''', the function returns ''false'' when it was unable to create the vehicle. Thus, we check the value of the ''createVehicle'' variable.

Now we have our complete script:
<syntaxhighlight lang="lua">
function createVehicleForPlayer(thePlayer, command, vehicleModel)
local x,y,z = getElementPosition(thePlayer) -- get the position of the player
x = x + 5 -- add 5 units to the x position
local createdVehicle = createVehicle(tonumber(vehicleModel),x,y,z)
-- check if the return value was ''false''
if (createdVehicle == false) then
-- if so, output a message to the chatbox, but only to this player.
outputChatBox("Failed to create vehicle.",thePlayer)
end
end
addCommandHandler("createvehicle", createVehicleForPlayer)
</syntaxhighlight>

As you can see, we introduced another function with [[outputChatBox]]. By now, you should be able to explore the function's documentation page yourself. For more advanced scripting, please check out the [[Map manager|Map Manager]].

==What you need to know==
You already read some things about resources, command handlers and finding functions in the documentation in the first paragraph, but there is much more to learn. This section will give you a rather short overview over some of these things, while linking to related pages if possible.
===Clientside and Serverside scripts===
You may have already noticed these or similiar terms (Server/Client) somewhere on this wiki, mostly in conjunction with functions. MTA not only supports scripts that run on the server and provide commands (like the one we wrote above) or other features, but also scripts that run on the MTA client the players use to connect to the server. The reason for this is, that some features MTA provides have to be clientside (like a GUI - Graphical User Interface), others should be because they work better and still others are better off to be serverside or just don't work clientside.

Most scripts you will make (gamemodes, maps) will probably be serverside, like the one we wrote in the first section. If you run into something that can't be solved serverside, you will probably have to make it clientside. For a clientside script for example, you would create a ordinary script file (for example called ''client.lua'') and specify it in the meta.xml, like this:
<syntaxhighlight lang="xml">
<script src="client.lua" type="client" />
</syntaxhighlight>
The ''type'' attribute defaults to 'server', so you only need to specify it for clientside scripts. When you do this, the clientside script will be downloaded to the player's computer once he connects to the server. Read more about [[Client side scripts]].

===More complex resources===
The previous section showed briefly how to add clientside scripts to the resource, but there is also much more possible. As mentioned at the very top of this page, resources can be pretty much everything. Their purpose is defined by what they do. Let's have some theoretical resources, by looking at the files it contains, the ''meta.xml'' and what they might do:

====First example - A utility script====
<syntaxhighlight lang="xml">
/admin_commands
/meta.xml
/commands.lua
/client.lua
</syntaxhighlight>
<syntaxhighlight lang="xml">
<meta>
<info author="Someguy" description="admin commands" />
<script src="commands.lua" />
<script src="client.lua" type="client" />
</meta>
</syntaxhighlight>

* The ''commands.lua'' provides some admin commands, like banning a player, muting or something else that can be used to admin the server
* The ''client.lua'' provides a GUI to be able to perform the mentioned actions easily

This example might be running all the time (maybe even auto-started when the server starts) as it's useful during the whole gaming experience and also wont interfere with the gameplay, unless an admin decides to take some action of course.

====Second example - A gamemode====
<syntaxhighlight lang="xml">
/counterstrike
/meta.xml
/counterstrike.lua
/buymenu.lua
</syntaxhighlight>
<syntaxhighlight lang="xml">
<meta>
<info author="Someguy" description="Counterstrike remake" type="gamemode" />
<script src="counterstrike.lua" />
<script src="buymenu.lua" type="client" />
</meta>
</syntaxhighlight>

* The ''counterstrike.lua'' contains similiar to the following features:
** Let players choose their team and spawn them
** Provide them with weapons, targets and instructions (maybe read from a Map, see below)
** Define the game's rules, e.g. when does the round end, what happens when a player dies
** .. and maybe some more
* The ''buymenu.lua'' is a clientside script and creates a menu to buy weapons

This example can be called a gamemode, since it not only intereferes with the gameplay, but actually defines the rules of it. The ''type'' attribute indicates that this example works with the [[Map manager]], yet another resource that was written by the QA Team to manage gamemodes and map loading. It is highly recommended that you base your gamemodes on the techniques it provides.

This also means that the gamemode probably won't run without a map. Gamemodes should always be as generic as possible. An example for a map is stated in the next example.

====Third example - A Map====
<syntaxhighlight lang="xml">
/cs-airport
/meta.xml
/airport.map
/airport.lua
</syntaxhighlight>
<syntaxhighlight lang="xml">
<meta>
<info author="Someguy" description="Counterstrike airport map" type="map" gamemodes="counterstrike" />
<map src="airport.map" />
<script src="airport.lua" />
</meta>
</syntaxhighlight>

* The ''airport.map'' in a XML file that provides information about the map to the gamemode, these may include:
** Where the players should spawn, with what weapons, what teams there are
** What the targets are
** Weather, World Time, Timelimit
** Provide vehicles
* The ''airport.lua'' might contain map-specific features, that may include:
** Opening some door/make something explode when something specific happens
** Create or move some custom objects, or manipulate objects that are created through the .map file
** .. anything else map-specific you can think of

As you can see, the ''type'' attribute changed to 'map', telling the [[Map manager]] that this resource is a map, while the ''gamemodes'' attribute tells it for which gamemodes this map is valid, in this case the gamemode from the above example.
What may come as a surprise is that there is also a script in the Map resource. Of course this is not necessarily needed in a map, but opens a wide range of possibilities for map makers to create their own world within the rules of the gamemode they create it for.

The ''airport.map'' file might look similiar to this:
<syntaxhighlight lang="xml">
<map mode="deathmatch" version="1.0">
<terrorists>
<spawnpoint posX="2332.23" posY="-12232.33" posZ="4.42223" skins="23-40" />
</terrorists>
<counterterrorists>
<spawnpoint posX="2334.23443" posY="-12300.233" posZ="10.2344" skins="40-50" />
</counterterrorists>

<bomb posX="23342.23" posY="" posZ="" />

<vehicle posX="" posY="" posZ="" model="602" />
<vehicle posX="" posY="" posZ="" model="603" />
</map>
</syntaxhighlight>

When a gamemode is started with a map, the map resources is automatically started by the mapmanager and the information it contains can be read by the gamemode resource. When the map changes, the current map resource is stopped and the next map resource is started. For a more in-depth explanation and examples of how map resources are utilized in the main script, please visit the [[Writing Gamemodes]] page.

===Events===
Events are the way MTA tells scripts about things that happen. For example when a player dies, the [[onPlayerWasted]] event is triggered. In order to perform any actions when a player dies, you have to prepare yourself similiar to adding a command handler, as shown in [[#Writing_the_script|the first chapter]].

This example will output a message with the name of the player who died:
<syntaxhighlight lang="lua">
function playerDied(totalAmmo, killer, killerWeapon, bodypart)
outputChatBox(getPlayerName(source).." died!")
end
addEventHandler("onPlayerWasted",getRootElement(),playerDied)
</syntaxhighlight>

Instead of showing what arguments are needed, the documentation page for Events shows what parameters are passed to the handler function, similiar to the way a [[#About_command_handlers|command handler]] does, just that it is different from event to event. Another important point is the ''source'' variable, that exists in handler functions. It doesn't have to be added to the parameter list of the function, but it still exists. It has a different value from event to event, for player events (as in the example above) it is the player element. As another example, you can take a look at the basic spawning player script in the first section to get an idea how ''source'' is used.

==Where to go from here==
You should now be familiar with the most basic aspects of MTA scripting and also a bit with the documentation. The [[Main Page]] provides you with links to more information, Tutorials and References that allow a deeper look into the topics you desire to learn about.
{{note|From here we recommend reading the [[debugging]] tutorial. Good debugging skills are an absolute necessity when you are making scripts. We also recommend you to use the [[predefined variables list]] to help you with certain tasks and make scripting easier and faster.}}
'''See also:'''
* [[Advanced Topics]]
[[es:Introducción a la Programación]]
[[it:Introduzione allo scripting]]
[[nl:Scripting_introductie]]
[[pt-br:Introdução ao Scripting]]
[[ru:Scripting Introduction]]
[[ar:مقدمه_في_البرمجه]]

User:Renkon

2013-12-24T02:33:22Z

AlexsSteel: Created page with "http://forum.mtasa.com/viewtopic.php?f=5&t=68603"

http://forum.mtasa.com/viewtopic.php?f=5&t=68603

DxDrawAnimWindow

2013-12-22T19:50:04Z

AlexsSteel: /* Use */

{{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 alto, int ancho, int color, string element font, string anim)</syntaxhighlight>

===Required Arguments===
* '''text:''' The text of the window
* '''alto:''' The height of the window
* '''ancho:''' 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,alto,ancho,color,font,anim)
local x,y = guiGetScreenSize()

btAncho = ancho
btAlto = alto/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, ancho, alto, 255, progress, anim)
local x2, y2, z2 = interpolateBetween ( 0, 0, 0, btAncho, btAlto, btAlto/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 remeber to define the "start" value with getTickCount()
<section name="Clientside example" class="client" show="true">
<syntaxhighlight lang="lua">
function start()
start = getTickCount()
end
addCommandHandler("gettick",start)
--
function dxDrawAnimWindow(text,alto,ancho,color,font,anim)
local x,y = guiGetScreenSize()

btAncho = ancho
btAlto = alto/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, ancho, alto, 255, progress, anim)
local x2, y2, z2 = interpolateBetween ( 0, 0, 0, btAncho, btAlto, btAlto/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>

Author: Bc#

==See Also==
{{Useful_Functions}}

IsElementMoving

2013-08-04T23:12:49Z

AlexsSteel: /* Code */

{{Useful Function}}
<lowercasetitle/>
__NOTOC__

This function checks if an element is moving.

==Syntax==
<syntaxhighlight lang="lua"> bool isElementMoving( element theElement ) </syntaxhighlight>

===Returns===
Returns true if the element is moving, otherwise false.

===Code===
<syntaxhighlight lang="lua">function isElementMoving(theElement)
if isElement(theElement)then --First check if the given argument is an element
local x, y, z = getElementVelocity(theElement) --Get the velocity of the element given in our argument
return x ~= 0 or y ~= 0 or z ~= 0 --When there is a movement on X, Y or Z return true because our element is moving
end
return false
end</syntaxhighlight>

===Example===
<section name="Client" class="client" show="true">
This script tells the moving state to the client on the bottom left of their screen
<syntaxhighlight lang="lua">
local screenWidth, screenHeight = guiGetScreenSize () -- Get the screen resolution (width and height)

function idleCheck ()
local state
if isElementMoving( getLocalPlayer() ) then --Check if it is the player "strolling"
state = "Moving"
elseif isElementMoving( getPedOccupiedVehicle ( getLocalPlayer() ) ) then --Player is not "Strolling" maybe the player is in a vehicle
state = "Moving"
else --The player not moving on feet or in a vehicle
state = "Idling"
end
--Write our state string to the lower left corner of the screen
dxDrawText ( state, 40, screenHeight - 40, screenWidth, screenHeight, tocolor ( 255, 255, 255, 255 ), 1, "default" )
end

addEventHandler ( "onClientRender", getRootElement(), idleCheck ) -- keep the text visible with onClientRender.
</syntaxhighlight>
</section>

==See Also==
{{Useful_Functions}}

OnClientChatMessage

2013-07-11T20:51:48Z

AlexsSteel: /* Example */

{{Client event}}
__NOTOC__
This event is triggered when any text is output to chatbox, including MTA's hardcoded messages.

==Parameters==
<syntaxhighlight lang="lua">
string text, int r, int g, int b
</syntaxhighlight>
*'''text:''' The text that was output to chatbox
*'''r:''' The amount of red in the color of the text.
*'''g:''' The amount of green in the color of the text.
*'''b:''' The amount of blue in the color of the text.

==Source==
The [[event system#Event source|source]] of this event is the root element.
==Cancel effect==
AS OF 1.3.2
If this event is [[Event system#Canceling|canceled]], the game's chat system won't deliver the posts. You may use [[outputChatBox]] to send the messages then.

==Example==
This example doesn't output anything to chatbox if it consists only of numbers
<syntaxhighlight lang="lua">
[lua]
function onClientChatMessageHandler(text)
if string.match(text,"%d+") --[[string.match searches for pattern "%d+", means decimals]] == text then -- if string.match and text itself are the same
cancelEvent() -- don't output it
end
end
addEventHandler("onClientChatMessage", getRootElement(), onClientChatMessageHandler)
</syntaxhighlight>

==See Also==

===Client other events===
{{Client_other_events}}
===Client event functions===
{{Client_event_functions}}

User:AlexsSteel

2013-05-05T21:50:25Z

AlexsSteel:

I Love Cookies :D

[[File:Galleta_del_dibujo_animado_escultura_fotografica-p153432631525827152bfnwk_400.jpg]]

File:Galleta del dibujo animado escultura fotografica-p153432631525827152bfnwk 400.jpg

2013-05-05T21:50:11Z

AlexsSteel: :D Cookie!

:D Cookie!

User:AlexsSteel

2013-05-05T21:47:36Z

AlexsSteel: Created page with "I Love Cookies :D Media:http://rlv.zcache.es/galleta_del_dibujo_animado_escultura_fotografica-p153432631525827152bfnwk_400.jpg"

I Love Cookies :D

[[Media:http://rlv.zcache.es/galleta_del_dibujo_animado_escultura_fotografica-p153432631525827152bfnwk_400.jpg]]

Meta.xml

2013-05-05T21:45:53Z

AlexsSteel: /* Tags */

The ''meta.xml'' file presents MTA with a set of metadata, such as the resource's name, the scripts to include, and which files to precache for sending to clients among other things. It is also the scope of "elements". It is written in XML, which is based on HTML and is the parent of XHTML.

=Tags=
XML is a textual data format which is widely used for the representation of data. MTA uses an XML-based language to describe the metadata for resources by using the tags below:

*'''<info />''' Information about this resource, possible parameters include (any arbitrary parameters can be used and read using [[getResourceInfo]]):
** '''author:''' The author of this resource
** '''version:''' The version of this resource
** '''name:''' The name of this resource
** '''description:''' A brief description of this resource
** '''type:''' The type of this resource, that can be "gamemode", "script", "map" or "misc".
*'''<script />''' Source code for this resource, possible parameters are:
** '''src:''' The file name of the source code
** '''type:''' The type of source code: "client", "server" or "shared".

**'''cache:''' When the script file type is "client", this setting controls whether the file is saved on the players hard drive. Default is "true". Using "false" will mean the file is not saved.
**'''validate:''' If set to "false", compatibility checks are skipped.
*'''<map />''' The map for a gamemode, possible parameters are:
**'''src:''' .map file name (can be path too eg. "maps/filename.map")
**'''dimension:''' Dimension in which the map will be loaded (optional)
*'''<file />''' A client-side file. Generally these are images, .txd, .col, .dff or .xml files. They'll be downloaded by clients when the resources is started (or on join)
**'''src:''' client-side file name (can be path too eg. "images/image.png")
**'''download:''' Whether or not to be sent to the client automatically (optional). Default is "true". Using "false" will mean they are not sent on resource start but could later be used by [[downloadFile]] (from version 1.4)
*'''<include />''' Include resources that this resource will use
**'''resource:''' Resource name that you want to start with this resource
**'''minversion:''' Minimum version that '''resource''' needs to be (optional)
**'''maxversion:''' Maximum version that '''resource''' needs to be (optional)
*'''<config />''' Config file (.xml) can be accessed by resource, possible parameters are:
**'''src:''' The file name of the config file
**'''type:''' The type of the config file: "client" or "server"
*'''<export />''' This exports functions from this resource, so other resources can use them with [[call]]
**'''function:''' The function name
**'''type''' Whether function is exported server-side or client-side (valid values are: "server" and "client")
**'''http:''' Can the function be called via HTTP (true/false)
*'''<html />'''
**'''src:''' The filename for the HTTP file (can be a path)
**'''default:''' The html file is one that is shown by default when visiting /resourceName/ on the server. Only one html can be default, the rest are ignored. (true/false)
**'''raw:''' The html file is not parsed by the LUA interpreter and is treated as binary data. Must be used for binary files (images mainly) (true/false)
*'''<settings> <setting name="" value=""/> </settings>:''' Most gamemodes use [[settings system]] to let server admins to configure it how they like. For instance you could set round time and then use [[get]] and [[set]] to get the value or change it, respectively.
*'''<min_mta_version />''' Minimum version requirements for this resource to run correctly. When authoring resources, the minimum version should usually be set to the current released version of MTA:SA (which at the moment is "{{Current Version|full}}"). See example for example.
**'''client:''' The minimum client version
**'''server:''' The minimum server version
*'''<aclrequest />''' A list of [[Access_Control_List|ACL]] rights this resource will need.
{{New items|3.0132|1.3.1 r4141|
*'''<sync_map_element_data />''' Controls whether map [[Element_data|element data]] such as "PosX" and "DoubleSided" are transferred to the client. This data is usually not required by most gamemodes or resources. (Map Editor and Interiors require this to be not set to false to work). When set in a gamemode meta.xml, the setting will apply to all maps loaded by that resource.
**'''false:''' Disable transfer of map element data. This can reduce map download times considerably.
**'''true:''' Enable transfer of map element data (default).
}}
{{New items|3.0140|1.4.0 r5313|
*'''<oop/>''' todo.
**'''false:''' todo.
**'''true:''' todo.
}}

== Example ==
Heres an example of a meta file using some of the tags mentioned:
{{#tag:code |
<meta>
<info author="Slothman" type="gamemode" name="Stealth" />
<config src="help.xml" type="client"/>

<min_mta_version client="{{Current Version|full}}" server="{{Current Version|full}}" />

<sync_map_element_data>false</sync_map_element_data>

<script src="stealthmain_server.lua" />
<script src="noiseblip.lua" />
<script src="mission_timer.lua" />
<script src="gadgets_server.lua" />
<script src="gadgets_client.lua" type="client"/>
<script src="stealthmain_client.lua" type="client"/>
<script src="noisebar.lua" type="client"/>
<script src="spycam.lua" type="client"/>
<script src="riemann_z_demonstration.lua" type="client" cache="false"/>

<file src="riot_shield.txd" />
<file src="riot_shield.dff" />
<file src="riot_shield.col" />
<file src="armor.png" download="true"/>
<file src="camera.png" download="false"/>
<file src="cloak.png" />
<file src="goggles.png" />
<file src="mine.png" />
<file src="radar.png" />
<file src="shield.png" />

<include resource="scoreboard" />
<include resource="killmessages" />
<include resource="maplimits" />

<settings>
<setting name="roundlimit" value="[6]" /> 
<setting name="teamdamage" value="[1]" /> 
<setting name="teambalance" value="[1]" /> 
<setting name="spazammo" value="[25]" /> 
<setting name="m4ammo" value="[100]" />
<setting name="shotgunammo" value="[25]" />
<setting name="sniperammo" value="[20]" />
<setting name="ak47ammo" value="[120]" />
<setting name="rifleammo" value="[40]" />
<setting name="deserteagleammo" value="[45]" />
<setting name="pistolammo" value="[132]" />
<setting name="uziammo" value="[150]" />
<setting name="tec9ammo" value="[150]" />
<setting name="silencedammo" value="[65]" />
<setting name="grenadeammo" value="[4]" />
<setting name="satchelammo" value="[4]" />
<setting name="teargasammo" value="[4]" />
<setting name="molatovammo" value="[4]" />
<setting name="isAllowedToShoot" value="true" />
</settings>

<aclrequest>
<right name="function.startResource" access="true" />
<right name="function.stopResource" access="true" />
<right name="function.setPlayerMuted" access="true" />
</aclrequest>

</meta>
|lang="xml"}}
[[Category:Scripting Concepts]]
[[cs:Meta.xml]]
[[de:Meta.xml]]
[[es:Sobre el archivo "meta.xml"]]
[[it:Meta.xml]]
[[pl:Meta.xml]]
[[ru:Meta.xml]]

ES/PlaySound3D

2013-04-21T23:38:05Z

AlexsSteel: /* Sintaxis */

== playSound3D ==

Crea un elemento de sonido en el ambiente de juego y lo reproduce inmediatamente después de la creación para el jugador local. setElementPosition es utilizable para este elemento.

''Nota'': Los formatos de audio soportados sólo son MP3, WAV, OGG, RIFF, MOD, XM, IT y S3M.

== Sintaxis ==
<syntaxhighlight lang="lua">element playSound3D ( string Archivo, float posX, float posY, float posZ [, bool repeticion = false ] )</syntaxhighlight>

== Argumentos Requeridos ==

*'''Archivo''': El archivo a reproducir.

*'''x''': El punto flotante que representa la coordenada X en el mapa.

*'''y''': El punto flotante que representa la coordenada Y en el mapa.

*'''z''': El punto flotante que representa la coordenada Z en el mapa.

== Argumentos Opcionales ==

*'''Repeticion''': Un boolean representando si el sonido se reproducirá de nuevo al terminar.

== Ejemplos ==
En este ejemplo se reproduce un archivo de audio en la pizzeria , cerca de de Pier 69 en San Fierro.
<syntaxhighlight lang="lua">
addEventHandler( 'onClientResourceStart', resourceRoot,
function( )
local uSound = playSound3D( 'sonidos/audio23.mp3', 2498, -1659, 12, true ) -- Se utiliza 'true' porque el sonido se repetirá infinidad de veces
setSoundMaxDistance( uSound, 100 )
end
)
</syntaxhighlight>

==Mira Tambien==
{{Client_audio_functions}}

ES/PlaySound3D

2013-02-25T16:38:21Z

AlexsSteel: /* Argumentos Opcionales */

== playSound3D ==

Crea un elemento de sonido en el ambiente de juego y lo reproduce inmediatamente después de la creación para el jugador local. setElementPosition es utilizable para este elemento.

''Nota'': Los formatos de audio soportados sólo son MP3, WAV, OGG, RIFF, MOD, XM, IT y S3M.

== Sintaxis ==
<syntaxhighlight lang="lua">element playSound3D ( string Archivo, float posX, float posY, float posZ, [ bool repeticion = false ] )</syntaxhighlight>

== Argumentos Requeridos ==

*'''Archivo''': El archivo a reproducir.

*'''x''': El punto flotante que representa la coordenada X en el mapa.

*'''y''': El punto flotante que representa la coordenada Y en el mapa.

*'''z''': El punto flotante que representa la coordenada Z en el mapa.

== Argumentos Opcionales ==

*'''Repeticion''': Un boolean representando si el sonido se reproducirá de nuevo al terminar.

== Ejemplos ==
En este ejemplo se reproduce un archivo de audio en la pizzeria , cerca de de Pier 69 en San Fierro.
<syntaxhighlight lang="lua">
addEventHandler( 'onClientResourceStart', resourceRoot,
function( )
local uSound = playSound3D( 'sonidos/audio23.mp3', 2498, -1659, 12, true ) -- Se utiliza 'true' porque el sonido se repetirá infinidad de veces
setSoundMaxDistance( uSound, 100 )
end
)
</syntaxhighlight>

==Mira Tambien==
{{Client_audio_functions}}

ES/PlaySound3D

2013-02-25T16:37:56Z

AlexsSteel: /* Argumentos Requeridos */

== playSound3D ==

Crea un elemento de sonido en el ambiente de juego y lo reproduce inmediatamente después de la creación para el jugador local. setElementPosition es utilizable para este elemento.

''Nota'': Los formatos de audio soportados sólo son MP3, WAV, OGG, RIFF, MOD, XM, IT y S3M.

== Sintaxis ==
<syntaxhighlight lang="lua">element playSound3D ( string Archivo, float posX, float posY, float posZ, [ bool repeticion = false ] )</syntaxhighlight>

== Argumentos Requeridos ==

*'''Archivo''': El archivo a reproducir.

*'''x''': El punto flotante que representa la coordenada X en el mapa.

*'''y''': El punto flotante que representa la coordenada Y en el mapa.

*'''z''': El punto flotante que representa la coordenada Z en el mapa.

== Argumentos Opcionales ==

*'''Repeticion''': Un boolean representando si el sonido se reproducirá de nuevo al terminar.
----

== Ejemplos ==
En este ejemplo se reproduce un archivo de audio en la pizzeria , cerca de de Pier 69 en San Fierro.
<syntaxhighlight lang="lua">
addEventHandler( 'onClientResourceStart', resourceRoot,
function( )
local uSound = playSound3D( 'sonidos/audio23.mp3', 2498, -1659, 12, true ) -- Se utiliza 'true' porque el sonido se repetirá infinidad de veces
setSoundMaxDistance( uSound, 100 )
end
)
</syntaxhighlight>

==Mira Tambien==
{{Client_audio_functions}}

ES/PlaySound3D

2013-02-25T16:37:37Z

AlexsSteel: /* Argumentos Opcionales */

== playSound3D ==

Crea un elemento de sonido en el ambiente de juego y lo reproduce inmediatamente después de la creación para el jugador local. setElementPosition es utilizable para este elemento.

''Nota'': Los formatos de audio soportados sólo son MP3, WAV, OGG, RIFF, MOD, XM, IT y S3M.

== Sintaxis ==
<syntaxhighlight lang="lua">element playSound3D ( string Archivo, float posX, float posY, float posZ, [ bool repeticion = false ] )</syntaxhighlight>

== Argumentos Requeridos ==

*'''Archivo''': El archivo a reproducir.

*'''x''': El punto flotante que representa la coordenada X en el mapa.

*'''y''': El punto flotante que representa la coordenada Y en el mapa.

*'''z''': El punto flotante que representa la coordenada Z en el mapa.

----

== Argumentos Opcionales ==

*'''Repeticion''': Un boolean representando si el sonido se reproducirá de nuevo al terminar.
----

== Ejemplos ==
En este ejemplo se reproduce un archivo de audio en la pizzeria , cerca de de Pier 69 en San Fierro.
<syntaxhighlight lang="lua">
addEventHandler( 'onClientResourceStart', resourceRoot,
function( )
local uSound = playSound3D( 'sonidos/audio23.mp3', 2498, -1659, 12, true ) -- Se utiliza 'true' porque el sonido se repetirá infinidad de veces
setSoundMaxDistance( uSound, 100 )
end
)
</syntaxhighlight>

==Mira Tambien==
{{Client_audio_functions}}

ES/PlaySound3D

2013-02-25T16:36:33Z

AlexsSteel: /* Argumentos Requeridos */

== playSound3D ==

Crea un elemento de sonido en el ambiente de juego y lo reproduce inmediatamente después de la creación para el jugador local. setElementPosition es utilizable para este elemento.

''Nota'': Los formatos de audio soportados sólo son MP3, WAV, OGG, RIFF, MOD, XM, IT y S3M.

== Sintaxis ==
<syntaxhighlight lang="lua">element playSound3D ( string Archivo, float posX, float posY, float posZ, [ bool repeticion = false ] )</syntaxhighlight>

== Argumentos Requeridos ==

*'''Archivo''': El archivo a reproducir.

*'''x''': El punto flotante que representa la coordenada X en el mapa.

*'''y''': El punto flotante que representa la coordenada Y en el mapa.

*'''z''': El punto flotante que representa la coordenada Z en el mapa.

----

== Argumentos Opcionales ==

*'''Bucle''': El bucle representa si el sonido se reproducirá de nuevo o No. De caso contrario usar false.

----

== Ejemplos ==
En este ejemplo se reproduce un archivo de audio en la pizzeria , cerca de de Pier 69 en San Fierro.
<syntaxhighlight lang="lua">
addEventHandler( 'onClientResourceStart', resourceRoot,
function( )
local uSound = playSound3D( 'sonidos/audio23.mp3', 2498, -1659, 12, true ) -- Se utiliza 'true' porque el sonido se repetirá infinidad de veces
setSoundMaxDistance( uSound, 100 )
end
)
</syntaxhighlight>

==Mira Tambien==
{{Client_audio_functions}}

ES/PlaySound3D

2013-02-25T16:26:57Z

AlexsSteel: /* Sintaxis */

== playSound3D ==

Crea un elemento de sonido en el ambiente de juego y lo reproduce inmediatamente después de la creación para el jugador local. setElementPosition es utilizable para este elemento.

''Nota'': Los formatos de audio soportados sólo son MP3, WAV, OGG, RIFF, MOD, XM, IT y S3M.

== Sintaxis ==
<syntaxhighlight lang="lua">element playSound3D ( string Archivo, float posX, float posY, float posZ, [ bool repeticion = false ] )</syntaxhighlight>

== Argumentos Requeridos ==

*'''El audio''': El archivo de audio que quieres reproducir. (agregar el tag <file> </file> en el archivo meta.xml).

*'''x''': El punto flotante que representa la coordenada X en el mapa.

*'''y''': El punto flotante que representa la coordenada Y en el mapa.

*'''z''': El punto flotante que representa la coordenada Z en el mapa.

----

== Argumentos Opcionales ==

*'''Bucle''': El bucle representa si el sonido se reproducirá de nuevo o No. De caso contrario usar false.

----

== Ejemplos ==
En este ejemplo se reproduce un archivo de audio en la pizzeria , cerca de de Pier 69 en San Fierro.
<syntaxhighlight lang="lua">
addEventHandler( 'onClientResourceStart', resourceRoot,
function( )
local uSound = playSound3D( 'sonidos/audio23.mp3', 2498, -1659, 12, true ) -- Se utiliza 'true' porque el sonido se repetirá infinidad de veces
setSoundMaxDistance( uSound, 100 )
end
)
</syntaxhighlight>

==Mira Tambien==
{{Client_audio_functions}}

ES/PlaySound3D

2013-02-25T16:26:12Z

AlexsSteel: /* playSound3D */

== playSound3D ==

Crea un elemento de sonido en el ambiente de juego y lo reproduce inmediatamente después de la creación para el jugador local. setElementPosition es utilizable para este elemento.

''Nota'': Los formatos de audio soportados sólo son MP3, WAV, OGG, RIFF, MOD, XM, IT y S3M.

== Sintaxis ==
<syntaxhighlight lang="lua">elemento playSound3D ( string el archivo de audio, posX, posY, posZ, [ bool bucle = false ] )</syntaxhighlight>

== Argumentos Requeridos ==

*'''El audio''': El archivo de audio que quieres reproducir. (agregar el tag <file> </file> en el archivo meta.xml).

*'''x''': El punto flotante que representa la coordenada X en el mapa.

*'''y''': El punto flotante que representa la coordenada Y en el mapa.

*'''z''': El punto flotante que representa la coordenada Z en el mapa.

----

== Argumentos Opcionales ==

*'''Bucle''': El bucle representa si el sonido se reproducirá de nuevo o No. De caso contrario usar false.

----

== Ejemplos ==
En este ejemplo se reproduce un archivo de audio en la pizzeria , cerca de de Pier 69 en San Fierro.
<syntaxhighlight lang="lua">
addEventHandler( 'onClientResourceStart', resourceRoot,
function( )
local uSound = playSound3D( 'sonidos/audio23.mp3', 2498, -1659, 12, true ) -- Se utiliza 'true' porque el sonido se repetirá infinidad de veces
setSoundMaxDistance( uSound, 100 )
end
)
</syntaxhighlight>

==Mira Tambien==
{{Client_audio_functions}}

IsElementMoving

2013-02-15T03:02:56Z

AlexsSteel: /* Code */

{{Useful Function}}
<lowercasetitle/>
__NOTOC__

This function checks if an element is moving.

==Syntax==
<syntaxhighlight lang="lua"> bool isElementMoving( element theElement ) </syntaxhighlight>

===Returns===
Returns true if the element is moving, otherwise false.

===Code===
<syntaxhighlight lang="lua">function isElementMoving(theElement)
if isElement(theElement)then --First check if the given argument is an element
local x, y, z = getElementVelocity(theElement) --Get the velocity of the element given in our argument
if x ~= 0 and y ~= 0 and z ~= 0 then --When there is a movement on X, Y or Z return true because our element is moving
return true
else return false
end
else return false
end
end</syntaxhighlight>

===Example===
<section name="Client" class="client" show="true">
This piece of client side code writes the moving state to the client his screen
<syntaxhighlight lang="lua">
local screenWidth, screenHeight = guiGetScreenSize () -- Get the screen resolution (width and height)

function idleCheck ()
if isElementMoving( getLocalPlayer() ) then --Check if it is the player "strolling"
state = "Moving"
elseif isElementMoving( getPedOccupiedVehicle ( getLocalPlayer() ) ) then --Player is not "Strolling" maybe the player is in a vehicle
state = "Moving"
else --The player not moving on feet or in a vehicle
state = "Idling"
end
--Write our state string to the lower left corner of the screen
dxDrawText ( state, 40, screenHeight - 40, screenWidth, screenHeight, tocolor ( 255, 255, 255, 255 ), 1, "default" )
end

addEventHandler ( "onClientRender", getRootElement(), idleCheck ) -- keep the text visible with onClientRender.
</syntaxhighlight>
</section>
==See Also==
{{Useful_Functions}}