Ресурсы - ключевая часть MTA. Ресурс - папка или zip архив, который содержит набор файлов, также мета файл, который рассказывает серверу как нужно загружать ресурс и из каких файлов он состоит. Это как программа в операционной системе - может быть запущен и остановлен, а также могут работать несколько ресурсов одновременно. Всё содержымое скрипта находится в ресурсе

==Создаем простейший скрипт==
Для начала давайте сделаем команду "createvehicle" которая будет создавать машину рядом с игроком.
===Preparations===
As decribed above, a resource is a folder or zip file, so first you should create a folder. The folder name is the name of the resource, that is used to start or stop it or reference in scripts. In our example, we shall call it ''commands''.

What every resource has and needs is the ''meta.xml'' file. In our case, we want to create a script that provides some simple commands to the user, thus we need to tell the server to load a script file, we name ''script.lua'' in our case.
<syntaxhighlight lang="xml">
<meta>
<info author="YourName" description="A few simple commands" />
<script src="script.lua" />
</meta>
</syntaxhighlight>
Now we have to create the ''script.lua'' file we defined above in the same directory as the meta.xml. Now we have the both files:
<syntaxhighlight lang="xml">
/commands/meta.xml
/commands/script.lua
</syntaxhighlight>

===Writing the script===
Let's start with the contents 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, vehicle
function createVehicleForPlayer(thePlayer, command, vehicle)
-- 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>

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">
createVehiceForPlayer(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. 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 functions' 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.

==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) somwhere 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 theoratical 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.

===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(getClientName(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.

==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.

Главная страница

2008-01-11T20:03:41Z

StailS: /* Начало */

__NOTOC__
<div style="float:left;"><div style="float:right;">[[Image:Scripting.jpg]]</div>Добро пожаловать в Multi Theft Auto: San Andreas Deathmatch developer wiki. В этом wiki вы найдёте множество полезной информации по разработке режимов и карт для Multi Theft Auto.

Мы выпускаем предрелизные превью потому что нам нужна ваша помощь! Существует множество [[How you can help|способов помочь нам]] доработать и выпустить полностью законченную и отполированную версию MTA:SA DM. Создавайте режимы и карты, помогайте зафиксировать скриптинговые функци, пишите примеры, учебники или просто-напросто играйте и сообщайте обо всех ошибках MTA на форумах.

Если у вас возникли вопросы на тему скриптинга, свяжитесь с нами на нашем [[IRC Channel|IRC канале]].

'''Чтобы редактировать этот wiki вам нужна учётная запись mtabeta.com.''' Зарегистрируйтесь на http://www.mtabeta.com и затем войдите в учётную запись wiki с тем же именем и паролем.

Этот wiki теперь поддерживает '''[http://gears.google.com/ Google Gears]''', который позволяет просматривать wiki вне сети (и быстро). Всего лишь установите Google Gears и нажмите ссылку "Уйти в оффлайн" внизу любой страницы. Подождите пока приложение загрузит содержание wiki на ваш компьютер и после этого текущая на момент загрузки версия wiki будет доступна без подключения к серверу.

<div style="border: 2px dotted navy; padding: 4px; margin: 10px">Новейшая версия '''Multi Theft Auto: San Andreas Deathmatch''' - '''{{Current Version|full}}'''. Посетите [http://www.mtasa.com/dp.html страницу загрузки], чтобы скачать её.</div>

</div>

<div style="clear:both;"></div>
{| width="100%" cellspacing="0" cellpadding="0"
| colspan="2" |

|-
| width="50%" style="vertical-align:top;" |
<div style="border: 1px dotted #AAAAAA;padding:4px 8px 8px 8px;margin:10px;">
====Начало====

* [[Deathmatch_Client_Manual|Deathmatch Client Manual]]
* [[Deathmatch_Server_Manual|Deathmatch Server Manual]]
* [[Known_Issues_-_FAQ|Known issues in MTA:SA DM]]
* [[RU/Scripting Introduction|Вступление в скриптинг]]
* [[Debugging|Debugging Tutorial]] - Как найти ошибки в вашем скрипте
* [[MTA Classes]] - Detailed descriptions of all MTA custom types
** [[Element|MTA Elements]] / [[Element tree]]
* [[Resources|Introduction to Resources]]
** [[Resource Web Access]]
* [[Writing_Gamemodes|Writing Gamemodes]]

</div>

<div style="border: 1px dotted #AAAAAA;padding:4px 8px 8px 8px;margin:10px;">

====Базы данных====
В этой части описаны все возможности LUA, которые предоставляют MTA или resources.
* [[Map manager|Менеджер карт]] - Используйте это для своих режимов
* [[Client side scripts|Скрипты для клиента]]
</div>
<div style="border: 1px dotted #AAAAAA;padding:4px 8px 8px 8px;margin:10px;">

====Помощь по Lua вообще====
Страницы-учебники, цель которых - повысить ваш уровень понимания языка LUA
*[http://www.lua.org/pil/index.html Учебник "Программирование на LUA"]
*[http://lua-users.org/wiki/TutorialDirectory LUA Wiki]
</div>

| width="50%" style="vertical-align:top;" |
<div style="border: 1px dotted #AAAAAA;padding:4px 8px 8px 8px;margin:10px; background:#CCCCFF;">
====Reference====
* [[Client Scripting Functions|Client-side Functions]]
* [[Client Scripting Events|Client-side Events]]
* [[Server Scripting Functions|Server-side Functions]]
* [[Server Scripting Events|Server-side Events]]

</div>

<div style="border: 1px dotted #AAAAAA;padding:4px 8px 8px 8px;margin:10px;">

====ID Lists====
* [[Character Skins]] ([[All Skins Page]])
* [[CJ Clothes]]
* [[Template:Projectiles|Projectiles]]
* [[Template:Blip_Icons|Radar Blips]]
* [[Template:Sounds|Sounds]]
* [[Vehicle IDs|Vehicles]]
* [[Vehicle_default_colors|Vehicle Default Coloring Index]]
* [[Template:Vehicle_colors|Vehicle Color Palette]]
* Vehicle Upgrades
* [[Weapons|Weapons]]
* [[Weather|Weather]]
</div>

|-
| colspan="2" |
|}