diff --git a/docs/ru/scripting/server/latest-server-reference.md b/docs/ru/scripting/server/latest-server-reference.md new file mode 100644 index 00000000..a350320d --- /dev/null +++ b/docs/ru/scripting/server/latest-server-reference.md @@ -0,0 +1,1317 @@ +!!! предупреждение "Этот сайт находится в стадии разработки!" + +``` +This site is being actively worked on. + +Feel you could help? Please do by clicking on the page with a pencil on the right! + +This can be done on any page too. +``` + +# Справочник по серверным скриптам + +## Версия сервера 3.X + +### Введение + +Выпуск BeamMP-Server v3.0.0 вносит радикальные изменения в работу системы плагинов Lua. Нет возможности использовать старый lua с новым сервером, поэтому вам придется мигрировать. + +Система плагинов сервера использует [Lua 5.3](https://www.lua.org/manual/5.3/) . В этом разделе подробно описывается, как начать писать плагины, изучаются некоторые базовые концепции и начинается работа с вашим первым плагином. **Рекомендуется прочитать этот раздел, даже если вы знакомы с системой до версии 3.0.0, так как некоторые вещи кардинально изменились** . + +Руководство по миграции с lua до версии 3.0.0 см. в разделе [«Миграция со старой версии Lua»](#migrating-from-old-lua) . + +### Структура каталога + +Серверные плагины, в отличие от модов, располагаются (по умолчанию) в `Resources/Server` , тогда как моды, которые пишутся для BeamNG.drive и отправляются клиентам, находятся в `Resources/Client` . Каждый плагин должен иметь свою собственную подпапку в `Resources/Server` , например, для плагина с именем "MyPlugin" структура будет следующей: + +``` +Resources +└── Server + ├── MyPlugin + │ └── main.lua + └── SomeOtherPlugin + └── ... +``` + +Здесь мы также отображаем другой плагин под названием "SomeOtherPlugin", чтобы проиллюстрировать, как ваша папка `Resources/Server` может иметь несколько различных папок плагинов. Мы продолжим использовать эту структуру каталогов в качестве примера на протяжении всего этого руководства. + +Вы также заметите `main.lua` . У вас может быть столько файлов Lua `.lua` , сколько вам нужно. Все файлы Lua в главном каталоге вашего плагина загружаются в *алфавитном порядке* (поэтому `aaa.lua` запускается перед `bbb.lua` ). + +### Файлы Lua + +Каждый файл Lua `.lua` в папке плагина загружается при запуске сервера. Это означает, что операторы вне функций оцениваются («запускаются») немедленно. + +Файлы Lua в подпапках игнорируются, но могут быть `require()` . + +Например, наш `main.lua` выглядит так: + +```lua +function PrintMyName() + print("I'm 'My Plugin'!") +end + +print("What's up!") +``` + +Когда сервер запустится и загрузится `main.lua` , он *немедленно* запустит `print("What's up!")` , но пока **НЕ** *вызовет* функцию `PrintMyName` (потому что она не была вызвана)! + +### События + +Событие — это что-то вроде «игрок присоединяется», «игрок отправил сообщение в чате», «игрок создал транспортное средство». + +Вы можете отменить события (если они отменяемы), вернув `1` из обработчика. + +В Lua вы обычно хотите реагировать на некоторые из них. Для этого вы можете зарегистрировать "Handler". Это функция, которая вызывается, когда происходит событие, и получает некоторые аргументы. + +Пример: + +```lua +function MyChatMessageHandler(sender_id, sender_name, message) + -- censoring only the exact message 'darn' + if message == "darn" then + -- cancel the event by returning 1 + return 1 + else + return 0 + end +end + +MP.RegisterEvent("onChatMessage", "MyChatMessageHandler") +``` + +Это фактически гарантирует, что любое сообщение, которое в точности равно "darn", не будет отправлено и не будет показано в чате (обратите внимание, что для настоящего фильтра ненормативной лексики вам нужно будет проверить, *содержит* ли сообщение "darn", а не *является* ли оно "darn"). Отмена события приводит к тому, что оно не происходит, например, сообщение чата не будет показано никому другому, транспортное средство не будет создано и т. д. + +### Пользовательские события + +Вы можете зарегистрироваться на любое понравившееся вам мероприятие, например: + +```lua +MP.RegisterEvent("MyCoolCustomEvent", "MyHandler") +``` + +Затем вы можете инициировать эти пользовательские события: + +```lua +-- call all event handlers to this in ALL plugins +MP.TriggerGlobalEvent("MyCoolCustomEvent") +-- call all event handlers to this in THIS plugin +MP.TriggerLocalEvent("MyCoolCustomEvent") +``` + +С событиями можно делать гораздо больше, но эти возможности будут подробно рассмотрены ниже в справочнике по API. + +### Таймеры событий («Потоки») + +До версии 3.0.0 Lua имела концепцию "потоков", которые запускались X раз в секунду. Такое наименование было немного обманчивым, поскольку они были синхронными. + +v3.0.0 Lua вместо этого имеет "Таймеры событий". Это таймеры, которые работают внутри сервера, и как только они заканчиваются, они запускают событие (глобально). Это также синхронно. Пожалуйста, имейте в виду, что второй аргумент - это интервал в миллисекундах. + +Пример: + +```lua +local seconds = 0 + +function CountSeconds() + seconds = seconds + 1 +end + +-- create a custom event called 'EverySecond' +-- and register the handler function 'CountSeconds' to it +MP.RegisterEvent("EverySecond", "CountSeconds") + +-- create a timer for this event, which will fire every 1000ms (1s) +MP.CreateEventTimer("EverySecond", 1000) +``` + +Это приведет к тому, что "CountSeconds" будет вызываться каждую секунду. Вы также можете отменить таймеры событий с помощью `MP.CancelEventTimer` (см. справочник API). + +С консоли сервера вы можете запустить `status` , чтобы увидеть, сколько таймеров событий запущено в данный момент, а также информацию об ожидающих обработчиках событий. Эта команда покажет больше информации в будущем. + +### Отладка + +Lua трудно отлаживать. К сожалению, для встроенного Lua не существует отладчика промышленного уровня, такого как `gdb` . + +В общем случае вы, конечно, можете в любое время просто `print()` значения, которые хотите проверить. + +В версии 3.0.0 сервер предоставляет вам возможность внедрить интерпретатор в плагин и впоследствии запустить Lua внутри него в реальном времени. Это самое близкое, что у нас есть к отладчику. + +Предположим, у вас есть плагин, который мы назвали `MyPlugin` , вы можете войти в его состояние Lua следующим образом: + +``` +> lua MyPlugin +``` + +Здесь важны заглавные буквы, поэтому будьте внимательны, чтобы они были введены правильно. Вывод будет примерно таким: + +``` +lua @MyPlugin> +``` + +Как видите, мы перешли в состояние Lua для `MyPlugin` . С этого момента и до тех пор, пока мы не войдем в `exit()` (с версии 3.1.0 `:exit` ), мы будем в `MyPlugin` и сможем выполнить Lua там. + +Например, если у нас есть глобальный объект с именем `MyValue` , мы можем вывести это значение следующим образом: + +``` +lua @MyPlugin> print(MyValue) +``` + +Здесь вы можете вызывать функции и делать все, что вам нужно. + +Начиная с версии 3.1.0: Вы можете нажать клавишу TAB для автодополнения функций и переменных. + +ВНИМАНИЕ: К сожалению, если состояние Lua в данный момент занято выполнением другого кода (например, цикла `while` ), это может полностью повесить консоль до тех пор, пока она не завершит эту работу, поэтому будьте очень осторожны, переключаясь на состояния, которые могут ожидать чего-то. + +Кроме того, вы можете запустить `status` в обычной консоли ( `>` ), которая покажет вам, среди прочего, некоторую статистику о Lua. + +### Пользовательские команды + +Для реализации пользовательских команд для консоли сервера можно использовать событие `onConsoleInput` . Это может быть полезно, когда вы хотите добавить способ для владельца сервера подать сигнал на ваш плагин или отобразить внутреннее состояние пользовательским способом. + +Вот пример: + +```lua +function handleConsoleInput(cmd) + local delim = cmd:find(' ') + if delim then + local message = cmd:sub(delim+1) + if cmd:sub(1, delim-1) == "print" then + return message + end + end +end + +MP.RegisterEvent("onConsoleInput", "handleConsoleInput") +``` + +Это позволит вам выполнять следующие действия в консоли сервера: + +``` +> print hello, world +hello, world +``` + +Мы реализовали собственную `print` . В качестве упражнения попробуйте создать функцию, подобную `say` , которая отправляет сообщение чата всем игрокам или даже конкретному игроку (с помощью `MP.SendChatMessage` ). + +**Внимание:** для ваших собственных плагинов обычно рекомендуется "пространство имен". Наш пример `print` в плагине с именем `mystuff` может называться `mystuff.print` или `ms.print` или что-то подобное. + +### Ссылка на API + +Формат документации: `function_name(arg_name: arg_type, arg_name: arg_type) -> return_types` + +### Встроенные функции + +#### `print(...)` , `printRaw(...)` + +Выводит сообщение на консоль сервера с префиксом `[DATE TIME] [LUA]` . Если вам не нужен этот префикс, вы можете использовать `printRaw(...)` . + +Пример: + +```lua +local name = "John Doe" +print("Hello, I'm", name, "and I'm", 32) +``` + +Он может принимать столько аргументов произвольных типов, сколько вам нужно. Он также с радостью выгрузит таблицы! + +Это похоже на `print` интерпретатора lua, поэтому она будет вставлять символы табуляции между аргументами. + +#### `exit()` + +Корректно завершает работу сервера. Вызывает срабатывание события `onShutdown` . + +### Функции МП + +#### `MP.CreateTimer() -> Timer` + +Создает объект таймера, который можно использовать для отслеживания того, сколько времени заняло что-то / сколько времени прошло. Он запускается после создания и может быть сброшен/перезапущен с помощью `mytimer:Start()` . + +Текущее прошедшее время в секундах можно получить с помощью `mytimer:GetCurrent()` . + +Пример: + +```lua +local mytimer = MP.CreateTimer() +-- do stuff here that needs to be timed +print(mytimer:GetCurrent()) -- print how much time elapsed +``` + +Таймеры не нужно останавливать (и их невозможно остановить), они не создают накладных расходов. + +#### `MP.GetOSName() -> string` + +Возвращает имя текущей ОС: `Windows` , `Linux` или `Other` . + +#### `MP.GetServerVersion() -> number,number,number` + +Возвращает текущую версию сервера в формате major, minor, patch. Например, версия v3.0.0 вернет `3, 0, 0` . + +Пример: + +```lua +local major, minor, patch = MP.GetServerVersion() +print(major, minor, patch) +``` + +Выход: + +``` +2 4 0 +``` + +#### `MP.RegisterEvent(event_name: string, function_name: string)` + +Запоминает функцию с именем Имя `Function Name` как обработчик события с именем `Event Name` . + +Вы можете зарегистрировать столько обработчиков события, сколько захотите. + +Список событий, предоставляемых сервером, можно посмотреть [здесь](#events-1) . + +Если событие с таким именем не существует, оно создается, и, таким образом, RegisterEvent не может завершиться неудачей. Это можно использовать для создания пользовательских событий. Подробнее см. в разделах [Пользовательские события](#custom-events) и [События](#events) . + +Пример: + +```lua +function ChatHandler(player_id, player_name, msg) + if msg == "hello" then + print("Hello World!") + return 0 + end +end + +MP.RegisterEvent("onChatMessage", "ChatHandler") +``` + +#### `MP.CreateEventTimer(event_name: string, interval_ms: number, [strategy: number (since v3.0.2)])` + +Запускает таймер внутри сервера, который запускает событие `event_name` каждые `interval_ms` миллисекунд. + +Таймеры событий можно отменить с помощью `MP.CancelEventTimer` . + +Интервалы <25 мс не рекомендуются, так как несколько таких интервалов, скорее всего, не будут обслуживаться вовремя надежно. Хотя несколько таймеров могут быть запущены для одного и того же события, рекомендуется создавать как можно меньше таймеров событий. Например, если вам нужно одно событие, которое запускается каждые полсекунды, и одно, которое запускается каждую секунду, рассмотрите возможность создания просто события каждые полсекунды и запуска триггера every-second-functiosecond. + +Вы также можете использовать `MP.CreateTimer` для создания таймера и измерения времени, прошедшего с момента последнего вызова события, чтобы минимизировать таймеры событий, хотя это не обязательно рекомендуется, поскольку это значительно увеличивает сложность кода. + +**Начиная с версии 3.0.2:** + +Необязательный `CallStrategy` может быть указан в качестве третьего аргумента. Это может быть: + +- `MP.CallStrategy.BestEffort` (по умолчанию): попытается запустить событие с указанным интервалом, но откажется ставить обработчики в очередь, если выполнение обработчика займет слишком много времени. +- `MP.CallStrategy.Precise` : будет ставить обработчики событий в очередь с точным указанным интервалом. Может привести к заполнению очереди, если обработчику требуется больше времени, чем интервал. Используйте только если вам НУЖЕН точный интервал. + +#### `MP.CancelEventTimer(event_name: string)` + +Отменяет все таймеры для события с именем `event_name` В некоторых случаях таймер может сработать еще один раз, прежде чем будет отменен, из-за особенностей асинхронного программирования. + +#### `MP.TriggerLocalEvent(event_name: string, ...) -> table` + +Синхронный триггер событий локального плагина. + +Запускает локальное событие, которое приводит к вызову всех обработчиков этого события *в текущем состоянии lua* (обычно в текущем плагине, если состояние не было передано через PluginConfig.toml). + +Вы можете передать этой функции аргументы ( `...` ), которые копируются и отправляются всем обработчикам как аргументы функции. + +Этот вызов является синхронным и вернет управление после завершения всех обработчиков событий. + +Возвращаемое значение — это таблица всех результатов. Если обработчик вернул значение, оно будет в этой таблице, неаннотированное и неименованное. Это можно использовать для «сбора» вещей или регистрации подобработчиков для событий, которые можно отменить. Это практически массив. + +Пример: + +```lua +local Results = MP.TriggerLocalEvent("MyEvent") +print(Results) +``` + +#### `MP.TriggerGlobalEvent(event_name: string, ...) -> table` + +Глобальный асинхронный триггер событий. + +Запускает глобальное событие, которое приводит к вызову всех обработчиков этого события *во всех плагинах* (включая *этот* плагин). + +Вы можете передать этой функции аргументы ( `...` ), которые копируются и отправляются всем обработчикам как аргументы функции. + +Этот вызов асинхронный и возвращает объект, подобный будущему. Локальные обработчики (обработчики в том же плагине, что и вызывающий) запускаются синхронно и немедленно. + +Возвращаемая таблица имеет две функции: + +- `IsDone() -> boolean` сообщает, все ли обработчики завершились. Вы можете подождать, пока это не станет правдой, проверив это и `MP.Sleep` -ing на некоторое время в цикле. +- `GetResults() -> table` возвращает неаннотированную неименованную таблицу со всеми возвращаемыми значениями всех обработчиков. Это практически массив. + +Обязательно вызывайте их с помощью синтаксиса `Obj:Function()` ( `:` , NOT `.` ). + +Пример: + +```lua +local Future = MP.TriggerGlobalEvent("MyEvent") +-- wait until handlers finished +while not Future:IsDone() do + MP.Sleep(100) -- sleep 100 ms +end +local Results = Future:GetResults() +print(Results) +``` + +Имейте в виду, что обработчик, регистрирующийся здесь в "MyEvent" и никогда не возвращающийся, может заблокировать ваш плагин. Вероятно, вы захотите отслеживать, как долго вы ждали, и прекратить ожидание через несколько секунд. + +#### `MP.Sleep(time_ms: number)` + +Ожидает в течение указанного в миллисекундах времени. + +Это не приведет к выполнению состояния lua, и в состоянии сна ничего не будет выполнено. + +ВНИМАНИЕ: НЕ засыпайте более чем на 500 мс, если у вас зарегистрированы обработчики событий, если вы *точно* не знаете, что делаете. Это предназначено для использования в режиме сна на 1-100 мс, чтобы дождаться результатов или чего-то подобного. Заблокированное (спящее) состояние lua может существенно замедлить работу всего сервера, если не соблюдать осторожность. + +#### `MP.SendChatMessage(player_id: number, message: string)` + +Отправляет сообщение чата, которое может видеть только указанный игрок (или все, если идентификатор `-1` ). В игре это не будет отображаться как направленное сообщение. + +Вы можете использовать это, например, чтобы сообщить игроку *, почему* вы отменили появление его транспортного средства, отправить сообщение в чате или что-то подобное, или чтобы отобразить некоторую информацию о вашем сервере. + +Пример: + +```lua +function ChatHandler(player_id, player_name, msg) + if string.match(msg, "darn") then + MP.SendChatMessage(player_id, "Please do not use profanity.") -- If the player sends a message containing "darn", notify the player and cancel the message + return 1 + else + return 0 + end +end + +MP.RegisterEvent("onChatMessage", "ChatHandler") +``` + +Пример 2: + +```lua +function ChatHandler(player_id, player_name, msg) + if msg == "hello" then + MP.SendChatMessage(-1, "Hello World!") -- If the player sends the exact message "hello", announce to the entire server "Hello World!" + return 0 + end +end +``` + +#### `MP.TriggerClientEvent(player_id: number, event_name: string, data: string) -> boolean` + +*до версии 3.1.0* + +#### `MP.TriggerClientEvent(player_id: number, event_name: string, data: string) -> boolean,string` + +*начиная с версии 3.1.0* + +#### `MP.TriggerClientEventJson(player_id: number, event_name: string, data: table) -> boolean,string` + +*начиная с версии 3.1.0* + +Вызовет указанное событие с указанными данными на указанном клиенте (-1 для трансляции). Это событие затем может быть обработано в клиентском lua mod, см. документацию "Client Scripting" для этого. + +Вернет `true` если сообщение удалось отправить (для `id = -1` , поэтому для трансляций это всегда `true` ), и `false` если игрок с таким идентификатором не существует или отключен, но у него все еще есть идентификатор (это известная проблема). + +Если возвращается `false` , нет смысла повторять это событие, и не следует ожидать ответа (если таковой ожидался). + +Начиная с версии 3.1.0, второе возвращаемое значение содержит сообщение об ошибке, если функция не удалась. Также, начиная с этой версии, версия функции `*Json` принимает таблицу в качестве аргумента данных и преобразует ее в json. Это просто сокращение для `MP.TriggerClientEvent(..., Util.JsonEncode(mytable))` . + +#### `MP.GetPlayerCount() -> number` + +Возвращает количество игроков, находящихся в данный момент на сервере. + +#### `MP.GetPositionRaw(pid: number, vid: number) -> table,string` + +Возвращает текущую позицию транспортного средства `vid` (идентификатор транспортного средства) игрока `pid` (идентификатор игрока) и строку ошибки, если произошла ошибка. + +Таблица декодируется из пакета позиции, поэтому она содержит разнообразные данные, включая позицию и поворот (именно поэтому эта функция имеет постфикс «Raw»). + +Пример: + +```lua +local player_id = 4 +local vehicle_id = 0 + +local raw_pos, error = MP.GetPositionRaw(player_id, vehicle_id) + +if error == "" then + print(raw_pos) +else + print(error) +end +``` + +Выход: + +```json + { + tim: 49.824, // Time since spawn + rvel: { // Rotational velocity + 1: -1.33564e-05, + 2: -9.16553e-06, + 3: 8.33364e-07, + }, + vel: { // Velocity + 1: -4.29755e-06, + 2: -5.79335e-06, + 3: 4.95236e-06, + }, + pos: { // Position + 1: 269.979, + 2: -759.068, + 3: 46.554, + }, + ping: 0.0125, // Vehicle latency + rot: { // Rotation + 1: -0.00559953, + 2: 0.00894832, + 3: 0.772266, + 4: 0.635212, + }, +} +``` + +Пример 2: + +```lua +local player_id = 4 +local vehicle_id = 0 + +local raw_pos, error = MP.GetPositionRaw(player_id, vehicle_id) +if error = "" then + local x, y, z = table.unpack(raw_pos["pos"]) + + print("X:", x) + print("Y:", y) + print("Z:", z) +else + print(error) +end +``` + +Выход: + +``` +X: -603.459 +Y: -175.078 +Z: 26.9505 +``` + +#### `MP.IsPlayerConnected(player_id: number) -> boolean` + +Подключен ли игрок и получил ли сервер от него UDP-пакет. + +Пример: + +```lua +local player_id = 8 +print(MP.IsPlayerConnected(player_id)) -- Check if player with ID 8 is properly connected. +``` + +Выход: + +```lua +true +``` + +#### `MP.GetPlayerName(player_id: number) -> string` + +Получает отображаемое имя игрока. + +Пример: + +```lua +local player_id = 4 +print(MP.GetPlayerName(player_id)) -- Get the name of the player with ID 4 +``` + +Выход: + +``` +ilovebeammp2004 +``` + +#### `MP.RemoveVehicle(player_id: number, vehicle_id: number)` + +Удаляет указанное транспортное средство для указанного игрока. + +Пример: + +```lua +local player_id = 3 +local player_vehicles = MP.GetPlayerVehicles(player_id) + +-- Loop over all of player 3's vehicles and delete them +for vehicle_id, vehicle_data in pairs(player_vehicles) do + MP.RemoveVehicle(player_id, vehicle_id) +end +``` + +#### `MP.GetPlayerVehicles(player_id: number) -> table` + +Возвращает таблицу всех транспортных средств, которые в данный момент есть у игрока. Каждая запись в таблице представляет собой сопоставление идентификатора транспортного средства с данными о транспортном средстве (которые в настоящее время являются необработанной строкой json). + +Пример: + +```lua +local player_id = 3 +local player_vehicles = MP.GetPlayerVehicles(player_id) + +for vehicle_id, vehicle_data in pairs(player_vehicles) do + local start = string.find(vehicle_data, "{") + local formattedVehicleData = string.sub(vehicle_data, start, -1) + print(Util.JsonDecode(formattedVehicleData)) +end +``` + +Выход: + +```json +{ + pid: 0, + pro: "0", + rot: { + 1: 0, + 2: 0, + 3: 0.776866, + 4: 0.629665, + }, + jbm: "miramar", + vcf: { + parts: { + miramar_exhaust: "miramar_exhaust", + miramar_shock_R: "miramar_shock_R", + miramar_taillight: "miramar_taillight", + miramar_door_RL: "miramar_door_RL" + // ... continue + }, + paints: { + 1: { + roughness: 1, + metallic: 0, + clearcoat: 1, + baseColor: { + 1: 0.85, + 2: 0.84, + 3: 0.8, + 4: 1.2, + }, + clearcoatRoughness: 0.09, + } // ... continue + }, + partConfigFilename: "vehicles/miramar/base_M.pc", + vars: {}, + mainPartName: "miramar", + }, + pos: { + 1: 283.669, + 2: -754.332, + 3: 48.2151, + }, + vid: 64822, + ign: 0, +} +``` + +#### `MP.GetPlayers() -> table` + +Возвращает таблицу всех подключенных игроков. Эта таблица сопоставляет идентификаторы с именами, например: + +```json +{ + 0: "LionKor", + 1: "JohnDoe" +} +``` + +#### `MP.IsPlayerGuest(player_id: number) -> boolean` + +Является ли игрок гостем. Гость — это тот, кто не вошел в систему, а вместо этого решил играть как гость. Обычно его имя — `guest` за которым следует длинный номер. + +Поскольку гости анонимны, вы можете запретить им присоединяться. В этом случае рекомендуется использовать аргумент [`onPlayerAuth`](#onplayerauth) `is_guest` . + +#### `MP.DropPlayer(player_id: number, [reason: string])` + +Выгоняет игрока с указанным ID. Параметр причины необязателен. + +```lua +function ChatHandler(player_id, player_name, message) + if string.match(message, "darn") then + MP.DropPlayer(player_id, "Profanity is not allowed") + return 1 + else + return 0 + end +end +``` + +#### `MP.GetStateMemoryUsage() -> number` + +Возвращает использование памяти текущим состоянием Lua в байтах. + +#### `MP.GetLuaMemoryUsage() -> number` + +Возвращает использование памяти всеми состояниями lua в байтах. + +#### `MP.GetPlayerIdentifiers(player_id: number) -> table` + +Возвращает таблицу с информацией об игроке, такой как идентификатор форума BeamMP, IP-адрес и идентификатор учетной записи Discord. Discord ID будет возвращен только в том случае, если пользователь связал его со своей учетной записью форума. + +Вы можете найти идентификатор форума пользователя, перейдя по адресу `https://forum.beammp.com/u/USERNAME.json` и выполнив поиск по запросу `"user": {"id": 123456}` . Идентификатор BeamMP уникален для проигрывателя и не может быть изменен в отличие от имени пользователя. + +Пример: + +```lua +local player_id = 5 +print(MP.GetPlayerIdentifiers(player_id)) +``` + +Выход: + +```json +{ + ip: "127.0.0.1", + discord: "12345678987654321", + beammp: "1234567", +} +``` + +*До версии 3.1.0 поле `ip` было неверным и не работало как задумано. Исправлено в версии 3.1.0.* + +#### `MP.Set(setting: number, ...)` + +Временно устанавливает параметр ServerConfig. Для этого полезна таблица `MP.Settings` . + +Пример: + +```lua +MP.Set(MP.Settings.Debug, true) -- Turns on debug mode +``` + +#### `MP.Settings -> table` + +Таблица карты настройки идентификаторов для имени. Используется с `MP.Set` для изменения настроек ServerConfig. + +Пример: + +```lua +print(MP.Settings) +``` + +Выход: + +```json +{ + MaxPlayers: 3, + Debug: 0, + Name: 5, + Description: 6, + MaxCars: 2, + Private: 1, + Map: 4, +} +``` + +### Утилитарные функции + +#### `Util.Json*` + +Начиная с BeamMP-Server `v3.1.0` . + +Это встроенная библиотека JSON, которая обычно намного быстрее любой библиотеки Lua JSON. За кулисами используется библиотека C++ `nlohmann::json` , которая совместима с JSON, полностью протестирована и постоянно подвергается фаззингу. + +#### `Util.JsonEncode(table: table) -> string` + +Кодирует таблицу Lua в строку JSON, рекурсивно (таблицы внутри таблиц внутри таблиц ... работают как и ожидалось). Все примитивные типы учитываются, функции, пользовательские данные и т. п. игнорируются. + +Полученный JSON минимизируется и может быть красиво выведен с помощью `Util.JsonPrettify` для его наглядности. + +Пример: + +```lua +local player = { + name = "Lion", + age = 69, + skills = { "skill A", "skill B" } +} +local json = Util.JsonEncode(player) +``` + +Результаты в: + +```json +{"name":"Lion","age":69,"skills":["skill A","skill B"]} +``` + +#### `Util.JsonDecode(json: string) -> table` + +Декодирует JSON в таблицу Lua. Возвращает `nil` если это не удалось, и выводит ошибку. + +Пример: + +```lua +local json = "{\"message\":\"OK\",\"code\":200}" +local tbl = Util.JsonDecode(json) +``` + +Результаты в: + +```lua +{ + message = "OK", + code = 200, +} +``` + +#### `Util.JsonPrettify(json: string) -> string` + +Добавьте отступы и новые строки в JSON, чтобы сделать его более читабельным для людей. + +Пример: + +``` +local myjson = Util.JsonEncode({ name="Lion", age = 69, skills = { "skill A", "skill B" } }) + +print(Util.JsonPrettify(myjson)) +``` + +Результаты в: + +```json +{ + "age": 69.0, + "name": "Lion", + "skills": [ + "skill A", + "skill B" + ] +} +``` + +#### `Util.JsonMinify(json: string) -> string` + +Удаляет отступы, переносы строк и любые другие пробелы. Не обязательно, если вы не вызвали `Util.JsonPrettify` , так как весь вывод из `Util.Json*` уже минифицирован. + +Пример: + +```lua +local pretty = Util.JsonPrettify(Util.JsonEncode({ name="Lion", age = 69, skills = { "skill A", "skill B" } })) + +print(Util.JsonMinify(pretty)) +``` + +Результаты в: + +```json +{"age":69.0,"name":"Lion","skills":["skill A","skill B"]} +``` + +#### `Util.JsonFlatten(json: string) -> string` + +Создает объект JSON, ключи которого сводятся к указателям JSON в соответствии с RFC 6901. Вы можете восстановить оригинал с помощью `Util.JsonUnflatten()` . Чтобы это работало, все значения должны быть примитивами. + +Пример: + +```lua +local json = Util.JsonEncode({ name="Lion", age = 69, skills = { "skill A", "skill B" } }) +print("normal: " ..json) +print("flattened: " .. Util.JsonFlatten(json)) +print("flattened pretty: " .. Util.JsonPrettify(Util.JsonFlatten(json))) + +``` + +Результаты в: + +```json +normal: {"age":69.0,"name":"Lion","skills":["skill A","skill B"]} +flattened: {"/age":69.0,"/name":"Lion","/skills/0":"skill A","/skills/1":"skill B"} +flattened pretty: { + "/age": 69.0, + "/name": "Lion", + "/skills/0": "skill A", + "/skills/1": "skill B" +} +``` + +#### `Util.JsonUnflatten(json: string) -> string` + +Восстанавливает произвольную вложенность значения JSON, которое было сглажено перед использованием функции `Util.JsonFlatten()` . + +#### `Util.JsonDiff(a: string, b: string) -> string` + +Создает разницу JSON в соответствии с RFC 6902 (http://jsonpatch.com/). Затем эту разницу можно применить как патч через `Util.JsonDiffApply()` . Возвращает разницу. + +#### `Util.JsonDiffApply(base: string, diff: string) -> string` + +Применяет JSON `diff` к `base` как JSON patch (RFC 6902, http://jsonpatch.com/). Возвращает результат. + +### `Util.Random*` + +Начиная с BeamMP-Server `v3.1.0` . + +#### `Util.Random() -> float` + +Возвращает число с плавающей точкой от 0 до 1. + +Пример: + +```lua +local rand = Util.Random() +print("rand: " .. rand) +``` + +Результаты в: + +```lua +rand: 0.135477 +``` + +#### `Util.RandomIntRange(min: int, max: int) -> int` + +Возвращает целое число от минимума до максимума. + +Пример: + +```lua +local randInt = Util.RandomIntRange(1, 100) +print("randInt: " .. randInt) +``` + +Результаты в: + +```lua +randInt: 69 +``` + +#### `Util.RandomRange(min: number, max: number) -> float` + +Возвращает число с плавающей точкой между минимумом и максимумом. + +Пример: + +```lua +local randFloat = Util.RandomRange(1, 1000) +print("randFloat: " .. randFloat) +``` + +Результаты в: + +```lua +randFloat: 420.6969 +``` + +#### `Util.LogInfo(params: ...)` и др. (начиная с версии 3.3.0) + +```lua +Util.LogInfo("Hello, World!") +Util.LogWarn("Cool warning") +Util.LogError("Oh no!") +Util.LogDebug("hi") +``` + +производит + +``` +[19/04/24 11:06:50.142] [Test] [INFO] Hello, World! +[19/04/24 11:06:50.142] [Test] [WARN] Cool warning +[19/04/24 11:06:50.142] [Test] [ERROR] Oh no! +[19/04/24 11:06:50.142] [Test] [DEBUG] hi +``` + +Поддерживает ту же самую печать/сброс данных, что и `print()` . + +#### `Util.DebugExecutionTime() -> table` + +Когда код Lua выполняется на сервере, выполнение каждого обработчика событий хронометрируется. Минимальное, максимальное, среднее (среднее) и стандартное отклонение этих времен выполнения вычисляются и возвращаются в таблице этой функцией. Расчет происходит пошагово, поэтому каждый раз, когда запускается обработчик событий, минимальное, максимальное, среднее и стандартное отклонение обновляются. Таким образом, `Util.DebugExecutionTime()` обычно не занимает значительного времени для выполнения (менее 0,25 мс). + +Возвращает таблицу следующего вида: + +```lua +[[table: 0x7af6d400aca0]]: { + printStuff: [[table: 0x7af6d400be60]]: { + mean: 0.250433, + n: 76, + max: 0.074475, + stdev: 0.109405, + min: 0.449274, + }, + onInit: [[table: 0x7af6d400b130]]: { + mean: 0.033095, + n: 1, + max: 0.033095, + stdev: 0, + min: 0.033095, + }, +} +``` + +Для каждого *обработчика* событий возвращаются следующие данные: + +- `n` : Количество раз, когда событие срабатывало и был вызван обработчик +- `mean` : среднее значение всех времен выполнения, в мс +- `max` .: Максимальное время выполнения, в мс. +- `min` .: Наименьшее время выполнения, в мс. +- `stdev` : стандартное отклонение всех средних значений времени выполнения в мс + +Вот функция, которую можно использовать для наглядной распечатки этих данных: + +```lua +function printDebugExecutionTime() + local stats = Util.DebugExecutionTime() + local pretty = "DebugExecutionTime:\n" + local longest = 0 + for name, t in pairs(stats) do + if #name > longest then + longest = #name + end + end + for name, t in pairs(stats) do + pretty = pretty .. string.format("%" .. longest + 1 .. "s: %12f +/- %12f (min: %12f, max: %12f) (called %d time(s))\n", name, t.mean, t.stdev, t.min, t.max, t.n) + end + print(pretty) +end +``` + +Вы можете вызвать его следующим образом для отладки кода, если он работает медленно: + +```lua +-- event to print the debug times +MP.RegisterEvent("printStuff", "printDebugExecutionTime") +-- run every 5000 ms = 5 seconds (or 10, or 60, whatever makes sense for you +MP.CreateEventTimer("printStuff", 5000) +``` + +### Функции ФС + +Функции `FS` — это функции **файловой** **системы** , которые стремятся превзойти возможности Lua по умолчанию. + +Пожалуйста, всегда используйте `/` в качестве разделителя при указании путей, так как это кроссплатформенно (windows, linux, macos, ...). + +#### `FS.CreateDirectory(path: string) -> bool,string` + +Создает указанный каталог и любые родительские каталоги, если они не существуют. Поведение примерно эквивалентно обычной команде linux `mkdir -p` . + +В случае успеха возвращает `true` и `""` . Если создание каталога не удалось, возвращается `false` и сообщение об ошибке ( `string` ). + +Пример: + +```lua +local success, error_message = FS.CreateDirectory("data/mystuff/somefolder") + +if not success then + print("failed to create directory: " .. error_message) +else + -- do something with the directory +end + +-- Be careful not to do this! This will ALWAYS be true! +if error_message then + -- ... +end +``` + +#### `FS.Remove(path: string) -> bool,string` + +Удаляет указанный файл или папку. + +Возвращает `true` , если произошла ошибка, с сообщением об ошибке во втором возвращаемом значении. + +Пример: + +```lua +local error, error_message = FS.Remove("myfile.txt") + +if error then + print("failed to delete myfile: " .. error_message) +end +``` + +#### `FS.Rename(pathA: string, pathB: string) -> bool,string` + +Переименовывает (или перемещает) `pathA` в `pathB` . + +Возвращает `true` , если произошла ошибка, с сообщением об ошибке во втором возвращаемом значении. + +#### `FS.Copy(pathA: string, pathB: string) -> bool,string` + +Копирует `pathA` в `pathB` . + +Возвращает `true` , если произошла ошибка, с сообщением об ошибке во втором возвращаемом значении. + +#### `FS.GetFilename(path: string) -> string` + +Возвращает последнюю часть пути, которая обычно является именем файла. Вот несколько примеров входов + выходов: + +```lua +input -> output + +"my/path/a.txt" -> "a.txt" +"somefile.txt" -> "somefile.txt" +"/awesome/path" -> "path" +``` + +#### `FS.GetExtension(path: string) -> string` + +Возвращает расширение файла или пустую строку, если расширения нет. Вот несколько примеров входов + выходов + +```lua +input -> output + +"myfile.txt" -> ".txt" +"somefile." -> "." +"/awesome/path" -> "" +"/awesome/path/file.zip.txt" -> ".txt" +"myexe.exe" -> ".exe" +``` + +#### `FS.GetParentFolder(path: string) -> string` + +Возвращает путь к родительскому каталогу, т. е. папке, в которой содержится файл или папка. Вот несколько примеров входных и выходных данных: + +```lua +input -> output + +"/var/tmp/example.txt" -> "/var/tmp" +"/" -> "/" +"mydir/a/b/c.txt" -> "mydir/a/b" +``` + +#### `FS.Exists(path: string) -> bool` + +Возвращает `true` если путь существует, `false` если нет. + +#### `FS.IsDirectory(path: string) -> bool` + +Возвращает `true` , если указанный путь является каталогом, `false` если нет. Обратите внимание, что `false` НЕ подразумевает, что путь является файлом (см. `FS.IsFile()` ). + +#### `FS.IsFile(path: string) -> bool` + +Возвращает `true` , если указанный путь является обычным файлом (не символической ссылкой, жесткой ссылкой, блочным устройством и т. д.), `false` если нет. Обратите внимание, что `false` НЕ подразумевает, что путь является каталогом (см. `FS.IsDirectory()` ). + +#### `FS.ListDirectories(path: string) -> table` + +Возвращает таблицу всех каталогов по указанному пути. + +Пример: + +```lua +print(FS.ListDirectories("Resources")) +``` + +Результаты в: + +```lua +{ + 1: "Client", + 2: "Server" +} +``` + +#### `FS.ListFiles(path: string) -> table` + +Возвращает таблицу всех файлов по указанному пути. + +Пример: + +```lua +print(FS.ListFiles("Resources/Server/examplePlugin")) +``` + +Результаты в: + +```lua +{ + 1: "example.json", + 2: "example.lua" +} +``` + +#### `FS.ConcatPaths(...) -> string` + +Складывает (объединяет) все аргументы с предпочитаемым разделителем пути системы. + +Пример: + +```lua +FS.ConcatPaths("a", "b", "/c/d/e/", "/f/", "g", "h.txt") +``` + +результаты в + +``` +a/b/c/d/e/f/g/h.txt +``` + +Также разрешает `..` , если он существует в пути в любой точке. Эта функция безопаснее, чем конкатенация строк в lua, и учитывает разделители платформы. + +Пожалуйста, всегда используйте `/` в качестве разделителя при указании путей, так как это кроссплатформенно (windows, linux, macos, ...). + +### События + +#### Объяснение + +- Аргументы: Список аргументов, переданных обработчикам этого события. +- Отменяемое: Можно ли отменить событие. Если его можно отменить, обработчик может сделать это, вернув `1` , например `return 1` . + +#### Краткое изложение событий + +Присоединение игрока вызывает следующие события в указанном порядке: + +1. `onPlayerAuth` +2. `onPlayerConnecting` +3. `onPlayerJoining` +4. `onPlayerJoin` + +#### Системные события + +##### `onInit` + +Аргументы: НЕТ Отменяемо: НЕТ + +Срабатывает сразу после инициализации всех файлов в плагине. + +##### `onConsoleInput` + +Аргументы: `input: string` Отменяемость: НЕТ + +Срабатывает, когда консоль BeamMP получает входной сигнал. + +##### `onShutdown` + +Аргументы: НЕТ Отменяемо: НЕТ + +Срабатывает при отключении сервера. В настоящее время происходит после того, как все игроки были выгнаны. + +#### События, связанные с игрой + +##### `onPlayerAuth` + +Аргументы: `player_name: string` , `player_role: string` , `is_guest: bool` , `identifiers: table -> beammp, ip` Возможность отмены: ДА + +Первое событие, которое срабатывает, когда игрок хочет присоединиться. Игроку может быть отказано в присоединении, если вернуть `1` или причину ( `string` ) из функции-обработчика. + +```lua +function myPlayerAuthorizer(name, role, is_guest, identifiers) + return "Sorry, you cannot join at this time." +end +MP.RegisterEvent("onPlayerAuth", "myPlayerAuthorizer") +``` + +##### `onPlayerConnecting` + +Аргументы: `player_id: number` Возможность отмены: НЕТ + +Срабатывает, когда игрок впервые начинает подключение, после `onPlayerAuth` . + +##### `onPlayerJoining` + +Аргументы: `player_id: number` Возможность отмены: НЕТ + +Срабатывает, когда игрок завершил загрузку всех модов, после `onPlayerConnecting` . + +##### `onPlayerDisconnect` + +Аргументы: `player_id: number` Возможность отмены: НЕТ + +Срабатывает при отключении игрока. + +##### `onChatMessage` + +Аргументы: `player_id: number` , `player_name: string` , `message: string` Возможность отмены: ДА + +Срабатывает, когда игрок отправляет сообщение в чате. При отмене сообщение в чате не будет показано никому, даже игроку, который его отправил. + +##### `onVehicleSpawn` + +Аргументы: `player_id: number` , `vehicle_id: number` , `data: string` Возможность отмены: ДА + +Срабатывает, когда игрок создает новое транспортное средство. Аргумент `data` содержит конфигурацию автомобиля и данные о положении/вращении для транспортного средства в виде строки json. + +##### `onVehicleEdited` + +Аргументы: `player_id: number` , `vehicle_id: number` , `data: string` Возможность отмены: ДА + +Срабатывает, когда игрок редактирует свое транспортное средство и применяет редактирование. Аргумент `data` содержит обновленную конфигурацию автомобиля в виде строки json, но **не** включает данные о положении или вращении. Вы можете использовать [MP.GetPositionRaw](#mpgetpositionrawpid-number-vid-number-tablestring) для получения данных о положении и вращении. + +##### `onVehicleDeleted` + +Аргументы: `player_id: number` , `vehicle_id: number` Возможность отмены: НЕТ + +Срабатывает, когда игрок удаляет свое транспортное средство. + +##### `onVehicleReset` + +Аргументы: `player_id: number` , `vehicle_id: number` , `data: string` Возможность отмены: НЕТ + +Срабатывает, когда игрок сбрасывает свое транспортное средство. `data` — это обновленное положение и вращение автомобиля, однако **не** включают конфигурацию транспортных средств. Вы можете использовать [MP.GetPlayerVehicles](#mpgetplayervehiclesplayer_id-number-table) , чтобы получить конфигурацию транспортных средств. + +##### `onFileChanged` + +*начиная с версии 3.1.0* + +Аргументы: `path: string` Возможность отмены: НЕТ + +Срабатывает при изменении файла в каталоге `Resources/Server` *или любом его подкаталоге* . + +Любое изменение файла в каталоге `Resources/Server/` (не в его подпапке) вызовет перезагрузку состояния Lua и событие `onFileChanged` . + +Любой файл в подпапках `Resources/Server/` , например `Resources/Server//lua/stuff.lua` , не вызовет перезагрузку состояния, а только вызовет событие `onFileChanged` . Таким образом, вы можете перезагрузить его самостоятельно правильным образом (или не перезагружать). + +Это относится ко всем файлам, а не только к файлам `.lua` . + +`path` указывается относительно корня сервера, например `Resources/Server/myplugin/myfile.txt` . Вы можете выполнить дальнейшую обработку этой строки с помощью семейства функций `FS.*` , например, извлечь имя или расширение ( `FS.GetExtension(...)` , `FS.GetFilename(...)` , ...). + +Примечание: файлы, добавленные после запуска сервера, *не* отслеживаются, начиная с версии 3.1.0. + +### Миграция со старого Lua + +Это краткий обзор основных шагов, которые необходимо предпринять для перехода со старого на новый lua. + +#### Понять, как работает новый lua + +Для этого внимательно прочтите раздел [«Введение»](#how-to-start-writing-a-plugin) и все его подразделы. Необходимо правильно выполнить следующие шаги. + +#### Найти и заменить + +Сначала вам следует выполнить поиск и замену всех функций MP. Подстановка должна добавить `MP.` перед всеми функциями MP, за исключением `print()` . + +Пример: + +```lua +local players = GetPlayers() +print(#players) +``` + +становится + +```lua +local players = MP.GetPlayers() +print(#players) -- note how print() doesn't change +``` + +#### Прощайте, темы, привет, таймеры событий! + +Как обсуждалось во введении, потоки — это таймеры событий. Для любых вызовов `CreateThread` замените его вызовом `CreateEventTimer` . Внимательно проверьте время, которое имел ваш старый CreateThread (число было X в секунду), и подумайте о том, какое значение тайм-аута таймера событий для этого (которое указывается в миллисекундах). Также имейте в виду, что вместо имени функции он принимает имя события, поэтому вам придется также зарегистрировать событие. + +Пример: + +```lua +CreateThread("myFunction", 2) -- calls "myFunction" twice per second +``` + +становится + +```lua +MP.RegisterEvent("myEvent", "myFunction") -- registering our event for the timer +MP.CreateEventTimer("myEvent", 500) -- 500 milliseconds = 2 times per second +``` + +Если у вас много таймеров событий, имеет смысл попробовать объединить их, например, создав событие "ежеминутное" и зарегистрировав в нем несколько функций, которые нужно вызывать каждую минуту, вместо того, чтобы иметь несколько таймеров событий. Каждый таймер событий требует от сервера немного времени для срабатывания. + +#### Больше никаких неявных вызовов событий + +Вам нужно регистрировать все ваши события. Вы не можете полагаться на имена функций. В старом lua это было неясно, но в новом lua это обычно соблюдается. Хороший шаблон: + +```lua +MP.RegisterEvent("onChatMessage", "chatMessageHandler") +-- or +MP.RegisterEvent("onChatMessage", "handleChatMessage") +``` + +Это лучше, чем называть обработчик тем же, что и событие, что вводит в заблуждение и сбивает с толку.