Введение в скриптинг

Описание

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

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

Создание работающего скрипта

Для начала мы узнаем, как пошагово сделать простой скрипт, который позволит игроку прогуливаться по городу.

Где находятся все скрипты?

Давайте взглянем на файловую структуру скрипта. Зайдите в папку сервера MTA и пройдите по следующему пути:

/server/mods/deathmatch/resources/

Вы увидите множество .zip-архивов, являющихся упакованными пробными скриптами, поставляемыми с MTA DM. Каждый файл - это "ресурс", все они будут распакованы и загружены сервером при его старте. Чтобы создать свой собственный ресурс, просто создайте папку и назовите ее так, как хотите. В нашем случае мы назовем ее "myserver".

Теперь вам нужно зайти в эту папку:

/server/mods/deathmatch/resources/myserver/

Идентификация вашего ресурса

Чтобы сервер мог узнать о содержимом того или иного ресурса, в нем должен быть создан файл meta.xml, перечисляющий его содержимое. Этот файл должен быть расположен в корневой директории ресурса, в нашем случае - это папка "myserver". Просто создайте текстовый файл, назовите его "meta.xml" и откройте с помощью Блокнота (notepad).

В файл meta.xml введите следующий код:

<meta>
     <info author="YourName" type="gamemode" name="Kontol memek" description="My Mta Sa" />
     <script src="script.lua" type="server"/>
</meta>

В теге <info /> есть поле "type", которое говорит о том, что данный ресурс - gamemode ("мод", игровой режим), а не обычный include или map (карта), о которых мы поговорим чуть позже. Gamemode - то, что вам нужно, чтобы создать независимый сервер.

Тег <script /> оговаривает сценарии (скрипты), которые содержит ресурс, о них мы сейчас и поговорим. Поле "type" говорит о том, что данный скрипт "script.lua" будет выполняться на стороне сервера.

Создание простого скрипта

Заметьте, что в теге <script /> 'script.lua' - файл не находится в какой-либо вложенной директории. Следовательно, мы создадим файл в той же папке, что и meta.xml. Теперь можно скопировать и вставить в script.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)

Этот скрипт заспавнит вас по координатам (x, y, z), указанным выше, когда вы зайдете на сервер. Обратите внимание, что функция fadeCamera обязательно должна быть, иначе экран будет черным. К тому же, в релизах новее DP2 вам нужно установить цель для камеры (иначе все, что увидит игрок - синее небо).

Переменная source указывает на того, кто вызвал срабатывание события. Так как данный код срабатывает при заходе какого-либо игрока, эта переменная используется для установления того, кто зашел. Так что спавнить будет именно этого игрока, а не всех сразу или кого-нибудь случайно.

Если присмотреться к addEventHandler, вы заметите три вещи: 'onPlayerJoin', указывающий на то, когда (почему) произойдет срабатывание; getRootElement(), который показывет благодаря кому/чему может произойти срабатывание (getRootElement() - это все/всё) и joinHandler, который отвечает за функцию, на которую произойдет переключение при срабывании события. Остальные подробности будут изложены позже и на отдельном примере, а теперь давайте просто запустим сервер и попрактикуемся!

Запуск скрипта

Чтобы запустить сервер, просто запустите исполняемый файл (на Windows - .exe) по адресу MTA San Andreas x.x/server, где x.x - номер версии MTA. Сначала будут показаны данные сервера; запомните номер порта (server port), который понадобится вам при подключении. Затем сервер загрузит все ресурсы в папку mods/deathmatch/resources/ и позже будет "ready to accept connections!", то есть готов принимать игроков.

Перед тем, как вы подключитесь к серверу, нужно обязательно запустить мод (gamemode). Введите "start myserver" и нажмите Enter. Сервер запустит мод, который вы только что создали, а также начнет отображать различные ошибки и предупреждения, если таковые будут. Теперь можно запустить клиент MTA DM и подключиться через "Quick Connect", воспользовавшись IP-адресом вашего сервера и номером порта, на который мы ранее обратили ваше внимание. Если все пройдет по плану, через несколько секунд ваш персонаж сможет пройтись по улицам Los Santos'а.

Затем мы добавим в скрипт команду, которую игроки смогут использовать для того, чтобы спавнить рядом с собой транспортное средство. Вы можете это пропустить и взглянуть на статью про более продвинутый скриптинг с использованием Map Manager, которая продолжит это руководство. Еще одним ответвлением данного руководства является Введение в скриптинг GUI: прочитав его, вы узнаете, как рисуется и программируется Graphical User Interface в MTA:DM.

Создание простой команды

Давайте вернемся к содержимому файла script.lua. Как уже было сказано, мы хотим предоставить команду для создания трансортного средства рядом с вашей текущей позицией в игре. Во-первых, нам понадобится создать функцию, которую мы будем вызывать, и обработчик команды, который сделает команду доступной для выбора игроком посредством ввода ее в консоли.

-- создаем функцию, вызываемую обработчиком команды, с аргументами: thePlayer, command, vehicleModel
function createVehicleForPlayer(thePlayer, command, vehicleModel)
   -- создаем транспортное средство и другое
end

-- создаем обработчик команды
addCommandHandler("createvehicle", createVehicleForPlayer)

Заметка: Клик по названию функции в образце кода перенаправит на соответствующую страницу с ее описанием.

Про обработчики команд

Первый аргумент addCommandHandler - имя команды, которая будет доступна игроку, второй аргумент - функция, на которую произойдет переключение, в данном случае - это createVehicleForPlayer.

Если у вас уже есть опыт в скриптинге, вы знаете, что функции вызываются примерно следующим образом:

functionName(argument1, argument2, argument3, ..)

functionName(thePlayer, commandName, argument3, ..)

Присмотревшись ко второму образцу (выше), мы увидим, что argument1 - thePlayer, а argument2 - commandName. thePlayer - тот, кто набрал команду, так что как бы вы ее не вводили, переменная будет содержать игрока, который ее активировал. commandName - команда, которую ввели. Так что при вводе "/greet", этот аргумент будет содержать "greet". Argument 3 - еще что-то, введенное игроком после, об этом вы узнаете чуть позже из данного руководства. Никогда не забывайте, что первые 2 аргумента являются стандартными, но назвать вы их можете по своему усмотрению. То есть важен порядок, а не название.

Мы уже вызывали таким образом функцию addCommandHandler, и так как createVehicleForPlayer - также функция, ее тоже можно так вызвать. Но мы для этого используем обработчик команд, который вызывает ее схожим образом, только внутренне.

Например: Кто-то вводит "createvehicle 468" в игровой консоли, чтобы заспавнить Sanchez, обработчик команд вызывает функцию createVehicleForPlayer, как если бы мы имели в скрипте следующую строку кода:

createVehicleForPlayer(thePlayer,"createvehicle","468") -- thePlayer - элемент типа player игрока, который ввел команду

Как можно заметить, предоставляются несколько параметров: игрок, который вызвал команду, сама команда, которую он ввел, и какой-нибудь текст, который он после нее ввел, в данном случае - "468" в качестве id трансопртного средства, отвчечающего за Sanchez. Первые два параметра одинаковы для всех обработчиков команд, о них вы можете почитать на странице addCommandHandler. Фактически, вам всегда придется определять как минимум эти два параметра, чтобы смочь использовать какие-нибудь другие, идущие после них (например, для обработки текста, введенного после команды, как id модели транспортного средства в нашем случае).

Заметка: Обработчик команды надо добавлять именно ПОСЛЕ функции, на которую он сошлется, иначе она не будет найдена. Порядок имеет значение!

Написание функции

Чтобы заполнить созданную нами функцию, нам следует подумать, что нам предстоит сделать:

• Получить позицию игрока, чтобы знать, где спавнить ТС (мы хотим, чтобы оно появлялось прямо рядом с игроком)
• Вычислить позицию, на которой мы хотим заспавнить ТС (мы же не хотим его появления на голове у игрока)
• Собственно, заспавнить ТС
• Проверить, заспавнилось ли оно успешно, в противном случае - вывести сообщение в чат

Чтобы разрешить все поставленные задчаи, нам понадобится задействовать несколько функций. А чтобы найти нужные нам функции, нужно перейти ко списку серверных функций. Для начала нам понадобится функция, которая получит координаты игрока. Так как все игроки являются элементами, мы сразу выбираем Element functions, где и находим функцию getElementPosition. Кликнув по имени функции из списка, вы получите ее описание. Там можно увидеть синтаксис, что она возвращает и, как правило, пример использования. Синтаксис сообщает какие аргументы мы можем или должны ей передать.

Для getElementPosition синтаксис таков:

float, float, float getElementPosition ( element theElement )

Три float перед именем функции и есть типы значений, которые она возвращает. В данном случае это значит, что функция возвращает три числа с плавающей точкой (x, y и z). Внутри круглых скобок указаны аргументы, которые ей необходимо передать. В данном случае это только элемент, чью позицию вы хотите получить, у нас он представлен игроком.

function createVehicleForPlayer(thePlayer, command, vehicleModel)
    -- get the position and put it in the x,y,z variables
    -- (local означает, что переменные существуют только здесь, в этой области, внутри этой функции)
    local x,y,z = getElementPosition(thePlayer)
end

Затем нам надо сделать так, чтобы ТС не спавнилось прямо внутри игрока, поэтому мы прибавим небольшое число к переменной x, что повлечет за собой спавн ТС чуть восточнее самого игрока.

function createVehicleForPlayer(thePlayer, command, vehicleModel)
    local x,y,z = getElementPosition(thePlayer) -- получаем позицию игрока
    x = x + 5 -- прибавляем число 5 к позиции по оси x
end

Теперь нам понадобится другая функция, чтобы непосредственно заспавнить транспортное средство. Мы снова ищем ее в списке серверных функций, на этот раз, так как мы говорим о транспорте - в разделе Vehicle functions, где выберем createVehicle. В синтаксисе этой функции указано только одно возвращаемое значение (что встречается наиболее часто) - элемент типа vehicle, представляющий только что созданное ТС. Также мы видим, что часть аргументов заключена в [ ], следовательно, они необязательны.

Внутри нашей функции у нас уже есть все аргументы, которые нужны функции createVehicle: Только что вычисленная позиция в переменных x,y,z и id модели, который мы получили через команду ("createvehicle 468"), он доступен внутри функции в качестве переменной vehicleModel.

function createVehicleForPlayer(thePlayer, command, vehicleModel)
    local x,y,z = getElementPosition(thePlayer) -- получаем позицию игрока
    x = x + 5 -- прибавляем число 5 к позиции по оси x
    -- создаем ТС и сохраняем возвращенный элемент типа vehicle в переменной ''createdVehicle''
    local createdVehicle = createVehicle(tonumber(vehicleModel),x,y,z)
end

Этот код, конечно же, можно усовершенствовать различными путями, но как минимум мы добавим проверку на то, было ли ТС успешно создано. Как можно прочитать на странице createVehicle под Returns, функция возвращает false, если ТС создать не получилось. Стало быть, мы проверяем значение переменной createVehicle.

Теперь у нас есть готовый скрипт:

function createVehicleForPlayer(thePlayer, command, vehicleModel)
    local x,y,z = getElementPosition(thePlayer) -- получаем позицию игрока
    x = x + 5 -- прибавляем число 5 к позиции по оси x
    local createdVehicle = createVehicle(tonumber(vehicleModel),x,y,z)
    -- проверяем, является ли возвращаемое значение ''false''
    if (createdVehicle == false) then
        -- если да, то выводим сообщение в чат, но только для игрока, который спавнил ТС.
        outputChatBox("Failed to create vehicle.",thePlayer)
    end
end
addCommandHandler("createvehicle", createVehicleForPlayer)

Как вы уже, наверное, заметили, вашему взору предстала новая функция - outputChatBox. Теперь вы самостоятельно можете изучить содержимое ее страницы-документации. Чтобы узнать больше о продвинутом скриптинге, почитайте про Map Manager.

Что вам следует знать

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

Клиентские и серверные скрипты

Может быть, вы уже заметили эти или схожие термины (сервер/клиент) где-либо на данной вики, наиболее вероятно, вкупе с функциями. MTA не только поддерживает работающие на сервере скрипты, предоставляет команды (типа как мы писали выше) и другие возможности, но также и скрипты, выполняющиеся на клиенте MTA, который игроки используют для подключения к серверу. Причиной этому служит то, что некоторые предоставляемые MTA функции не могут быть серверными (например, GUI - Graphical User Interface, т.е. графический интерфейс пользователя), другие там просто работают лучше, но другим все же лучше быть серверными или попросту не работать на клиентской стороне.

Большинство сделанных вами скриптов (модов, карт), вероятно, будут серверными, как и та, которую мы написали в первом разделе. Если вы столкнетесь с чем-то, что не может быть реализовано на серверной стороне, возможно, вы сможете реализовать это на клиентской. Для написания клиентского скрипта, создайте обычный файл-скрипт (например, названный client.lua) и укажите его в meta.xml так:

<script src="client.lua" type="client" />

Атрибут type по умолчанию установлен на 'server', так что надобность указывать его существует только для клиентских скриптов. После этого, клиентский скрипт будет загружаться на компьютеры игроков при заходе. Подробнее о клиентских скриптах.

Более сложные ресурсы

Предыдущий раздел вкратце изложил, как добавлять в ресурс клиентские скрипты, но возможностей на самом деле намного больше. Как написано в самом начале статьи, ресурсы могут быть чем угодно. Их назначение определяется тем, что они делают. Давайте теоретически вообразим некоторые ресурсы, глядя на их файлы-содержимое, meta.xml и подумаем, что они могут делать:

Первый пример - Вспомогательный скрипт

/admin_commands
    /meta.xml
    /commands.lua
    /client.lua

<meta>
    <info author="Someguy" description="admin commands" />
    <script src="commands.lua" />
    <script src="client.lua" type="client" />
</meta>

• commands.lua предоставляет некоторые администраторские команды, такие как бан и заглушение игроков или еще что-нибудь, что может быть доступно для администраторов сервера
• client.lua предоставляет GUI, чтобы возможно было с легкостью выполнять вышеуказанные действия

Этот пример может выполняться все время (даже автозапускаться со стартом сервера), так как является полезным на протяжении всего игрового процесса и не конфликтует с ним, если администратор, конечно, сам этого не захочет.

Второй пример - Мод

/counterstrike
    /meta.xml
    /counterstrike.lua
    /buymenu.lua

<meta>
    <info author="Someguy" description="Counterstrike remake" type="gamemode" />
    <script src="counterstrike.lua" />
    <script src="buymenu.lua" type="client" />
</meta>

• counterstrike.luaсодержит схожие с нижеперечисленными функции:
  • Позволить игрокам выбирать свою команду и спавниться
  • Обеспечить их оружием, целями и инструкциями (возможно, взятыми из игровой карты, см. ниже)
  • Определить правила игры, напр., когда кончается раунд, что происходит при смерти игрока
  • .. и, может быть, что-то еще
• buymenu.lua - клиентский скрипт, создающий меню для покупки оружия

Этот образец может быть назван модом, так как не только влияет на игровой процесс, но, по сути, и задает его рамки. Атрибут type говорит о том, что этот пример работает с Map Manager, уже другим ресурсом, написанным QA Team для управлениями модами и подгрузки карт. Очень рекомендуется основывать свои моды на предоставляемом им функционале.

Это также означает, что мод, возможно, не запустится без карты. Моды всегда должны пользоваться общим функционалом настолько широко, насколько это возможно. Образец карты - в следующем примере.

Третий пример - Карта

/cs-airport
    /meta.xml
    /airport.map
    /airport.lua

<meta>
    <info author="Someguy" description="Counterstrike airport map" type="map" gamemodes="counterstrike" />
    <map src="airport.map" />
    <script src="airport.lua" />
</meta>

• airport.map- XML-файл, предоставляющий моду информацию о карте, что включает в себя:
  • Где игроки должны спавниться, с каким оружием, какие имеются команды
  • Какие имеются цели
  • Погода, время, ограничение по времени
  • Предоставляемый транспорт
• airport.luaможет содержать присущий данной карте функционал, что включает в себя:
  • Открытие каких-либо дверей, подрыв чего-нибудь при определенных условиях
  • Создание или передвижение определенных игровых объектов, или управление теми, что были созданы через .map-файл
  • .. все что еще угодно, связанное с картами

Как вы уже заметили, атрибут type поменялся на 'map', сообщая Map Manager, что этот ресурс - карта, в то время как атрибут gamemodes говорит, с какими модами эта карта совместима, в данном случае - это мод из примера выше. Сюрпризом может показаться то, что в ресурс-карту также входит и скрипт. Конечно, это совсем не обязательно для карты, но открывает широкий спектр возможностей для их создателей, позволяя создавать собственный мир с правилами мода, на котором он основывается.

Файл airport.map может выглядеть примерно так:

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

Когда мод запускается с картой, ресурс-карта автоматически запускается mapmanager'ом, и информация, которую он содержит, может быть прочитана ресурсом-модом. При смене карты, текущий ресурс-карта останавливается, а следующий - запускается. Для более детального разъяснения и образцов того, как ресурсы-карты используются основным скриптом, посетите страницу RU/Writing Gamemodes.

События

События - способ MTA сообщать скриптам о происходящем. Например, при смерти игрока, срабатывает событие onPlayerWasted. Чтобы при смерти игрока что-то происходило, вам придется проделать действия, схожие с добавлением обработчика команд, как об этом рассказано в первом разделе.

Этот пример будет выводить сообщение с именем игрока, который умер:

function playerDied(totalAmmo, killer, killerWeapon, bodypart)
    outputChatBox(getPlayerName(source).." умер!")
end
addEventHandler("onPlayerWasted",getRootElement(),playerDied)

Вместо того, чтобы сначала вывести список требуемых аргументов, страница документации для событий отображает, какие параметры передаются функции-обработчику, так же, как делает обработчик команд, просто это разнится от события к событию. Другим важным моментом является существующая в функциях-обработчиках переменная source. Ее необязательно добавлять в список параметров функции, но она, тем не менее, существует. Ее значение меняется от события к событию, для событий, связанных с игроком (как в образце выше), это - элемент типа player. В качестве другого образца служит базовый скрипт для респавна игрока в первом разделе, на его примере можно понять, как используется source.

Что делать теперь

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

Также смотрите:

• Продвинутый функционал