Ошибки MTA Server и Lua: диагностика и исправление

Ошибки на сервере MTA:SA могут проявляться по-разному: ресурс не запускается, команда не работает, интерфейс не открывается, данные не сохраняются, база данных не подключается, а в консоли появляются предупреждения Lua. Иногда сервер продолжает работать, но отдельные системы начинают вести себя непредсказуемо.

Чтобы найти причину проблемы, не нужно хаотично переустанавливать сервер или удалять ресурсы. В большинстве случаев достаточно проверить сообщения отладчика, структуру meta.xml, права ACL, обработчики событий и соединение с базой данных.

В этом руководстве разберём основные ошибки MTA Server и серверных Lua-ресурсов, а также последовательность действий, которая поможет быстро найти и устранить неисправность.

С чего начинать поиск ошибки

Первое правило диагностики MTA — не пытаться исправлять код вслепую. Сервер практически всегда сообщает, в каком файле и на какой строке возникла проблема.

Перед проверкой ресурса выполните следующие действия:

• откройте серверную консоль;
• включите расширенный вывод ошибок;
• перезапустите проблемный ресурс;
• повторите действие, после которого возникает ошибка;
• посмотрите название файла и номер строки в сообщении.

Для управления ресурсами используются команды:

refresh
start resource_name
restart resource_name
stop resource_name

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

Как использовать debugscript

debugscript — основной инструмент для поиска ошибок Lua в MTA. Он показывает предупреждения, ошибки выполнения, неправильные аргументы функций и проблемы с обработчиками событий.

Для подробной диагностики обычно используется третий уровень:

debugscript 3

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

Типичное сообщение может выглядеть так:

ERROR: resource_name/server.lua:42: attempt to index local 'playerData' (a nil value)

Из сообщения можно получить три важных элемента:

• resource_name — название проблемного ресурса;
• server.lua:42 — файл и строка ошибки;
• nil value — переменная не содержит ожидаемого значения.

Основные уровни debugscript

Низкие уровни показывают только наиболее серьёзные ошибки. Третий уровень выводит дополнительную информацию и предупреждения, поэтому лучше подходит для разработки и тестирования.

На рабочем сервере постоянный подробный вывод может создавать большое количество сообщений. После завершения диагностики его можно отключить:

debugscript 0

Распространённые ошибки Lua

Attempt to index a nil value

Эта ошибка означает, что код пытается обратиться к таблице, элементу или значению, которое равно nil.

local account = getPlayerAccount(player)
outputChatBox(account.name, player)

Объект аккаунта не обязательно содержит поле name. Перед использованием значения его необходимо проверить и получить правильной функцией.

local account = getPlayerAccount(player)

if account and not isGuestAccount(account) then
 local accountName = getAccountName(account)
 outputChatBox(accountName, player)
end

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

Bad argument

Сообщение Bad argument появляется, когда функция получает неправильный тип данных.

setElementPosition(player, "100", 200, 10)

Координаты должны быть числами. Если данные пришли из XML, JSON, GUI или базы данных, их лучше преобразовать:

local x = tonumber(valueX)
local y = tonumber(valueY)
local z = tonumber(valueZ)

if x and y and z then
 setElementPosition(player, x, y, z)
end

Attempt to call global function

Ошибка возникает, если функция не существует, объявлена после места вызова или находится в другом ресурсе без настроенного экспорта.

openPlayerPanel(player)

Проверьте:

• правильно ли написано название функции;
• подключён ли файл с этой функцией в meta.xml;
• выполняется ли функция на нужной стороне — client или server;
• настроен ли экспорт, если функция вызывается из другого ресурса.

Проверка файла meta.xml

meta.xml определяет, какие файлы входят в ресурс, где они выполняются и какие дополнительные данные загружаются клиенту. Ошибка в этом файле может полностью заблокировать запуск ресурса.

Пример базовой структуры:

<meta>
 <info
 author="Developer"
 name="Example Resource"
 version="1.0"
 type="script"
 />

 <script src="server.lua" type="server" />
 <script src="client.lua" type="client" cache="false" />
 <script src="shared.lua" type="shared" />

 <file src="images/background.png" />
 <file src="sounds/click.mp3" />
</meta>

Что проверить в meta.xml

• совпадают ли названия файлов и папок;
• соблюдается ли регистр букв;
• правильно ли указан тип скрипта;
• закрыты ли все XML-теги;
• существуют ли подключённые изображения, звуки и модели;
• нет ли лишних символов перед тегом <meta>;
• сохранён ли файл в корректной кодировке.

На Linux-сервере регистр особенно важен. Файлы Server.lua и server.lua считаются разными.

Экспорт функций

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

<export function="getPlayerLevel" type="server" />

После этого функция вызывается через exports:

local level = exports.resource_name:getPlayerLevel(player)

Если ресурс не запущен или экспорт отсутствует, вызов завершится ошибкой.

Ресурс не запускается

Если после команды start ресурс сразу останавливается, проверьте первое сообщение об ошибке в консоли. Последующие ошибки могут быть лишь следствием первоначальной проблемы.

Основные причины:

• повреждён или неправильно составлен meta.xml;
• в Lua-файле есть синтаксическая ошибка;
• отсутствует обязательный файл;
• ресурс зависит от другой системы, которая не запущена;
• используется неправильное имя ресурса;
• сервер не имеет доступа к файлам;
• архив распакован с дополнительной вложенной папкой.

Правильная структура должна выглядеть примерно так:

resources/
└── example_resource/
 ├── meta.xml
 ├── server.lua
 ├── client.lua
 └── images/

Неправильный вариант:

resources/
└── example_resource/
 └── example_resource/
 ├── meta.xml
 └── server.lua

В таком случае MTA может не определить внешнюю папку как полноценный ресурс.

Синтаксические ошибки Lua

Синтаксическая ошибка возникает ещё до выполнения кода. Ресурс не сможет нормально запуститься, пока она не будет исправлена.

Чаще всего встречаются:

• пропущенный end;
• незакрытая скобка;
• незакрытая строка;
• лишняя запятая;
• неправильное использование then;
• ошибка внутри таблицы.

Пример:

addCommandHandler("heal", function(player)
 if isElement(player) then
 setElementHealth(player, 100)
 -- отсутствует end
end)

Исправленный вариант:

addCommandHandler("heal", function(player)
 if isElement(player) then
 setElementHealth(player, 100)
 end
end)

Редактор кода с подсветкой парных скобок и Lua-синтаксиса значительно упрощает поиск таких ошибок.

Ошибки ACL и недостаток прав

ACL управляет доступом ресурсов и пользователей к административным функциям MTA. Даже правильно написанный скрипт может не работать, если у ресурса отсутствует необходимое право.

Проблема часто возникает при использовании функций:

• управления игроками;
• запуска и остановки ресурсов;
• работы с аккаунтами;
• выполнения административных команд;
• доступа к защищённым серверным функциям.

Если в консоли появляется сообщение Access denied, проверьте ACL и группу, к которой привязан ресурс.

Объект ресурса указывается в формате:

resource.resource_name

Пример добавления ресурса в группу:

<group name="ResourceAdmin">
 <acl name="ResourceAdmin" />
 <object name="resource.resource_name" />
</group>

Не выдавайте ресурсу полный административный доступ без необходимости. Лучше разрешить только функции, которые действительно используются скриптом.

После изменения ACL может потребоваться перезапуск ресурса или сервера. Перед редактированием файла сохраните резервную копию.

Ошибки базы данных

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

Подключение SQLite

local database = dbConnect("sqlite", "database.db")

if not database then
 outputDebugString("Не удалось подключить SQLite", 1)
end

Подключение MySQL

local database = dbConnect(
 "mysql",
 "dbname=game;host=127.0.0.1;charset=utf8mb4",
 "username",
 "password",
 "share=1"
)

if not database then
 outputDebugString("Не удалось подключить MySQL", 1)
end

При ошибке подключения проверьте:

• адрес и порт базы данных;
• имя базы;
• логин и пароль;
• права пользователя MySQL;
• доступность сервера базы данных;
• наличие нужных таблиц;
• кодировку соединения.

Безопасные запросы

Не вставляйте пользовательские значения в SQL-запрос путём обычного объединения строк.

Неправильно:

dbExec(database,
 "UPDATE accounts SET money = " .. money ..
 " WHERE username = '" .. username .. "'"
)

Правильно:

dbExec(
 database,
 "UPDATE accounts SET money = ? WHERE username = ?",
 money,
 username
)

Параметры через знак ? снижают риск ошибок и SQL-инъекций.

Асинхронное получение данных

dbQuery(
 function(queryHandle, player)
 local result, rows, errorCode = dbPoll(queryHandle, 0)

 if not result then
 outputDebugString(
 "Ошибка запроса к базе. Код: " .. tostring(errorCode),
 1
 )
 return
 end

 if isElement(player) and rows > 0 then
 outputChatBox(
 "Данные успешно загружены",
 player,
 0,
 255,
 0
 )
 end
 end,
 {player},
 database,
 "SELECT * FROM accounts WHERE serial = ?",
 getPlayerSerial(player)
)

Перед работой с игроком внутри callback обязательно проверяйте, существует ли его элемент. Игрок может покинуть сервер до завершения запроса.

Ошибки событий client-server

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

Регистрация серверного события

addEvent("shop:buyItem", true)

addEventHandler("shop:buyItem", root, function(itemId)
 local player = client

 if not isElement(player) then
 return
 end

 if type(itemId) ~= "number" then
 return
 end

 -- серверная проверка и покупка предмета
end)

Вызов события с клиента

triggerServerEvent(
 "shop:buyItem",
 localPlayer,
 selectedItemId
)

Название события должно полностью совпадать с обеих сторон.

Почему нельзя доверять данным клиента

Клиентский код находится на компьютере игрока и может быть изменён. Поэтому нельзя принимать без проверки количество денег, уровень, права администратора, стоимость товара или идентификатор чужого игрока.

На сервере необходимо повторно проверять:

• наличие игрока;
• тип полученных аргументов;
• допустимый диапазон значений;
• наличие нужной суммы денег;
• доступ к функции;
• расстояние до маркера или объекта;
• частоту вызова события.

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

Обработчик события не срабатывает

Если событие зарегистрировано, но код внутри него не выполняется, проверьте:

• на какой стороне находится обработчик;
• правильно ли указан элемент события;
• совпадает ли название события;
• не был ли обработчик удалён;
• запущен ли ресурс;
• не возникает ли ошибка раньше нужной строки.

Для быстрой проверки добавьте временное сообщение:

outputDebugString("Событие shop:buyItem сработало")

Если сообщение не появляется, проблема находится в регистрации или вызове события. Если появляется, проверяйте код внутри обработчика поэтапно.

Конфликты между ресурсами

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

Типичные признаки конфликта:

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

Используйте уникальные названия событий и функций:

vehicleShop:open
vehicleShop:buy
vehicleShop:close

Это лучше, чем общие варианты:

open
buy
close

По возможности храните функции и переменные локально, чтобы они не попадали в глобальное пространство Lua.

Утечки производительности и зависание сервера

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

Опасный пример:

setTimer(function()
 for _, player in ipairs(getElementsByType("player")) do
 dbExec(database, "UPDATE accounts SET x = ?", getElementPosition(player))
 end
end, 100, 0)

Такой код выполняет запросы каждые 100 миллисекунд для всех игроков. На сервере с большим онлайном это создаст серьёзную нагрузку.

Лучше сохранять данные:

• при выходе игрока;
• через разумный интервал;
• после важных изменений;
• одним объединённым запросом;
• без постоянного повторного подключения к базе.

Пошаговый алгоритм исправления ресурса

1. Включите debugscript 3.
2. Перезапустите проблемный ресурс.
3. Найдите первое сообщение об ошибке.
4. Откройте указанный файл и строку.
5. Проверьте переменные, аргументы и существование элементов.
6. Проверьте подключение файла в meta.xml.
7. Убедитесь, что client-код не выполняется на сервере и наоборот.
8. Проверьте права ACL.
9. Проверьте подключение и запросы базы данных.
10. Проверьте названия событий и экспортов.
11. Перезапустите ресурс и повторите тест.
12. После исправления удалите временные отладочные сообщения.

Как предотвратить новые ошибки

Чтобы сервер оставался стабильным, соблюдайте несколько правил:

• делайте резервные копии перед обновлением ресурсов;
• тестируйте новые системы на отдельном сервере;
• не устанавливайте неизвестные зашифрованные ресурсы;
• проверяйте Lua-код перед запуском;
• не храните пароли от базы в клиентских файлах;
• проверяйте все данные, полученные от клиента;
• используйте уникальные названия событий;
• не выдавайте ресурсам лишние ACL-права;
• следите за нагрузкой таймеров и запросов;
• записывайте изменения версий ресурсов.

Заключение

Большинство ошибок MTA Server можно исправить без полной переустановки сервера. Главное — последовательно проверять сообщения debugscript, структуру meta.xml, права ACL, соединение с базой данных и передачу событий между клиентом и сервером.

Не начинайте диагностику с удаления файлов. Сначала найдите первое сообщение об ошибке, определите проблемный ресурс и проверьте указанную строку. Такой подход экономит время и позволяет устранить настоящую причину неисправности, а не её внешние последствия.

После исправления обязательно протестируйте ресурс с несколькими игроками, проверьте повторный вход, перезапуск сервера и сохранение данных. Это поможет убедиться, что система работает стабильно не только сразу после запуска, но и при длительной работе сервера.