====== Функции игрового движка ======
===== get_response =====
=== Краткое описание: ===
Возвращает готовую строку из пакета отправленного сервером клиенту. Получить ответ от сервера в специальном формате строки.
=== Использование: ===
get_response( flag )
=== Обязательные аргументы: ===
* 1 : (integer -- число)
===== createFileRecovery =====
=== Краткое описание: ===
Создает служебный файл игрового движка
=== Использование: ===
-- Восстановление настроек запуска движка
function goRecovery()
...
-- Создание файла после некорректного выхода
cl_exec( "createFileRecovery", "../cache.dat" )
end
Создает файл в данном случае **cache.dat** с текстом внутри:
recoveryMode=1
=== Обязательные аргументы: ===
* 1 : <имя файла> (строка)
===== declareRecovery =====
=== Краткое описание: ===
Сообщает игровому движку о файле
cl_exec( "declareRecovery", "../cache.dat" )
=== Обязательные аргументы: ===
* 1 : <имя файла> (строка)
===== getRecoveryFile =====
=== Краткое описание: ===
Получает назначенный файл от игрового движка
cl_exec( "getRecoveryFile" )
===== wait =====
=== Краткое описание: ===
Создает временную задержку в миллисекундах
=== Пример использования: ===
cl_exec( "wait", 100 )
=== Обязательные аргументы: ===
* 1 : <длительность> (мс)
===== yield =====
=== Краткое описание: ===
Создает в потоке временную задержку (используется для снижения нагрузки на процессор)
=== Пример использования: ===
cl_exec( "yield" )
===== quitApp =====
=== Краткое описание: ===
Игровой движок завершает работу. Выход из приложения
=== Пример использования: ===
cl_exec( "quitApp" )
===== existsFile =====
=== Краткое описание: ===
Возвращает **true** или **false** при проверке на существование файла
=== Пример использования: ===
cl_exec( "existsFile", filename )
=== Обязательные аргументы: ===
* 1 : <имя файла> (строка)
===== msg =====
=== Краткое описание: ===
Создает диалоговое окно с вопросом и отработкой кнопок
=== Пример использования: ===
cl_exec( "msg", "Предыдущий запуск: MotionEngine завершился некорректно.\nЗапустить в безопасном режиме?\n\nЭто рекомендуется сделать большинству пользователей.",
"Запустить в безопасном режиме?", "MB_YESNOCANCEL", "MB_ICONWARNING" )
=== Полный пример использования: ===
-- Создание MessageBox
messagebox = cl_exec( "msg", "Предыдущий запуск: MotionEngine завершился некорректно.\nЗапустить в безопасном режиме?\n\nЭто рекомендуется сделать большинству пользователей.",
"Запустить в безопасном режиме?", "MB_YESNOCANCEL", "MB_ICONWARNING" )
-- 6, 7, 2
if(cl_exec( "getMsgID", messagebox ) == "IDYES") then
cl_exec( "deleteFile", cl_exec( "getRecoveryFile" ) )
end
if(cl_exec( "getMsgID", messagebox ) == "IDNO") then
cl_exec( "deleteFile", cl_exec( "getRecoveryFile" ) )
end
if(cl_exec( "getMsgID", messagebox ) == "IDCANCEL") then
end
кусок кода из C++ (согласно: [[https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-messagebox|https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-messagebox]])
// Кнопки
#define MB_ABORTRETRYIGNORE 0x00000002L
#define MB_CANCELTRYCONTINUE 0x00000006L
#define MB_HELP 0x00004000L
#define MB_OK 0x00000000L
#define MB_OKCANCEL 0x00000001L
#define MB_RETRYCANCEL 0x00000005L
#define MB_YESNO 0x00000004L
#define MB_YESNOCANCEL 0x00000003L
// Иконки
#define MB_ICONEXCLAMATION 0x00000030L
#define MB_ICONWARNING 0x00000030L
#define MB_ICONINFORMATION 0x00000040L
#define MB_ICONASTERISK 0x00000040L
#define MB_ICONQUESTION 0x00000020L
#define MB_ICONSTOP 0x00000010L
#define MB_ICONERROR 0x00000010L
#define MB_ICONHAND 0x00000010L
=== Обязательные аргументы: ===
* 1 : <текст> (строка)
* 2 : <заголовок окна> (строка)
* 3 : <кнопки> (строка)
* 4 : <иконка> (строка)
===== getMsgID =====
=== Краткое описание: ===
Возвращает строку. Преобразует число в ID события
=== Пример использования: ===
cl_exec( "getMsgID", messagebox )
=== Может возвращать ===
* 1 **IDOK**
* 2 **IDCANCEL**
* 3 **IDABORT**
* 4 **IDRETRY**
* 5 **IDIGNORE**
* 6 **IDYES**
* 17 **IDNO**
* 10 **IDTRYAGAIN**
* 11 **IDCONTINUE**
=== Обязательные аргументы: ===
* 1 : (integer -- число) Ответ от диалогового окна
===== readTable =====
=== Краткое описание: ===
Аналог стандартной функции **require** ([[#require]]). Для подключения модулей в отдельных потоках.
=== Пример создания таблицы: ===
local ServerType = {
name = "ExampleServer",
version = "1.0"
}
function ServerType:greet()
print( "Hello from " .. self.name )
end
function ServerType:greet2()
print( "Test from " .. self.name )
end
return ServerType
=== Пример использования таблицы: ===
local ServerType = cl_exec( "readTable" , "mp._servertype" )
for k, v in pairs( ServerType ) do
print( "Key:", k, "Value:", v )
end
=== Обязательные аргументы: ===
* 1 : <имя файла> (строка). Путь вместо **'**/**'**, пишется точка.
===== joinServer =====
=== Краткое описание: ===
Подключение к серверу, указывается IP-адрес и порт.
**Возвращает integer:**
* 0 -- если не указан IP-адрес сервера для подключения
* 1 -- если IP-адрес был указан и модуль сетевой готов подключится
=== Пример использования: ===
cl_exec( "joinServer", "192.168.138.128", 28600 )
=== Обязательные аргументы: ===
* 1 : (строка).
* 2 : (integer -- число).
===== disconnect =====
=== Краткое описание: ===
Производит отключение от сервера.
=== Пример использования: ===
cl_exec( "disconnect" )
=== Примечание ===
Рекомендуем использовать внутри условия [[#isActiveServer]], что активно подключение к серверу
if cl_exec( "isActiveServer" ) then
-- тут
end
===== createPacket =====
=== Краткое описание: ===
Создает и отправляет пакет серверу
=== Пример использования: ===
cl_exec( "createPacket", flag, int_table( _serverType, "LOW" ), "getPosition()" )
=== Обязательные аргументы: ===
* 1 : <тип> (integer -- число). Тип пакета
* 2 : <критичность> (integer -- число). Критичность пакета
* 3 : <контент> (строка). Текст пакета
=== Примечание ===
Рекомендуем использовать внутри условия [[#isActiveServer]]
if cl_exec( "isActiveServer" ) then
-- тут
end
===== getActivePlayer =====
=== Краткое описание: ===
Возвращает текущего игрока (за которого мы играем!) а именно его ID в модуле сервера
=== Пример использования: ===
cl_exec( "getActivePlayer" )
=== Примечание ===
Рекомендуем использовать внутри условия [[#isActiveServer]]. Возвращать функция может ID строку либо пустая строка.
if cl_exec( "isActiveServer" ) then
-- тут
end
===== isActiveServer =====
=== Краткое описание: ===
Возвращает:
* 0 -- если нет соединенися с сервером
* 1 -- если уже подключены к серверу
=== Пример использования: ===
if cl_exec( "isActiveServer" ) then
...
end
===== PropsLoading =====
=== Краткое описание: ===
Задает режим игровому движку. Используется для создания новых объектов моделей на сцене. **Функция устаревшая (не понятно работает или нет)**
=== Пример использования: ===
cl_exec( "PropsLoading", )
=== Обязательные аргументы: ===
* 1 : (число). (0 -- начать работу с объектами или 1 -- закончить работу с объектами)
===== PropRemove =====
=== Краткое описание: ===
Добавляет в список для дальнейшего удаления объекта. После добавления необходимо произвести удаление с помощью функции [[#PropProcessRemove]]
=== Пример использования: ===
cl_exec( "PropRemove", "db07dc8054b761be7db7e22227cc2787" )
=== Обязательные аргументы: ===
* 1 : (строка). Указывается ID созданного объекта который на сцене
===== PropProcessRemove =====
=== Краткое описание: ===
Удаляет объекты со сцены. Смотрите функцию [[#PropProcessRemove]]
=== Пример использования: ===
cl_exec( "PropProcessRemove" )
===== propCreate =====
=== Краткое описание: ===
Добавляет в список для дальнейшего создания объекта. После добавления необходимо произвести создание моделей с помощью функции [[#propProcessCreate]].
Функция возвращает ID нового объекта.
=== Пример использования: ===
Создается одна модель:
* задается в список
* производится процесс создания модели на сцене
modelpic = cl_exec( "propCreate",
0, -- слой
foundFile[i], -- файл mep-модели
"", -- скин
"0.0;0.0;0.0", -- позиция XYZ
"-90.0;0.0;90.0", -- поворот XYZ
0.1 -- масштаб
)
cl_exec( "propProcessCreate" )
=== Обязательные аргументы: ===
* 1 : (integer -- число). слой у сцены (начинается с 0)
* 2 : (строка). Указывается имя файла mep-модели
* 3 : (строка). Указывается имя файла скина .mtx
* 4 : (строка). позиция в формате: X;Y;Z
* 5 : (строка). поворот в формате: X;Y;Z
* 6 : (float -- число с плавающей точкой). Масштаб объекта
===== propCreateId =====
=== Краткое описание: ===
Добавляет в список для дальнейшего создания объекта. После добавления необходимо произвести создание моделей с помощью функции [[#propProcessCreate]].
Существует другой аналог функции [[#propCreateId]], [[#propCreate]] которая возвращает случайный ID новой 3д-модели
=== Пример использования: ===
Создается одна модель:
* задается в список
* производится процесс создания модели на сцене
cl_exec( "propCreateId",
0, -- слой
"db07dc8054b761be7db7e22227cc2787", -- id-объекта
"bed_05.mep", -- файл mep-модели
"bed_03_blanket.ME2.s0.mtx", -- скин
"0.0;0.0;0.0", -- позиция XYZ
"-90.0;0.0;90.0", -- поворот XYZ
0.1 -- масштаб
)
cl_exec( "propProcessCreate" )
=== Обязательные аргументы: ===
* 1 : (integer -- число). слой у сцены (начинается с 0)
* 2 : (строка). Указывается имя файла mep-модели
* 3 : (строка). Указывается имя файла скина .mtx
* 4 : (строка). позиция в формате: X;Y;Z
* 5 : (строка). поворот в формате: X;Y;Z
* 6 : (float -- число с плавающей точкой). Масштаб объекта
===== propProcessCreate =====
=== Краткое описание: ===
Создает объекты на сцене. Смотрите функцию [[#propCreate]] и [[#propCreateId]]
=== Пример использования: ===
cl_exec( "propProcessCreate" )
===== propTransform =====
=== Краткое описание: ===
Изменяет трансформацию объекта на сцене
=== Пример использования: ===
cl_exec( "propTransform", "db07dc8054b761be7db7e22227cc2787",
string.format("%.2f;%.2f;%.2f", self.x, (self.y-230), self.z),
string.format("%.2f;%.2f;%.2f", -90.0, 0.0, ((-self.yaw)+180)),
"0.1;0.1;0.1"
)
=== Обязательные аргументы: ===
* 1 : (строка). ID-объекта на сцене
* 2 : (строка). Позиция в формате: X;Y;Z
* 3 : (строка). Поворот в формате: X;Y;Z
* 4 : (строка). Масштаб в формате: X;Y;Z
===== goScreenshot =====
=== Краткое описание: ===
Создает скриншот игрового движка
=== Пример использования: ===
cl_exec( "goScreenshot", 0 )
=== Обязательные аргументы: ===
* 1 : (integer -- число).
- если 0, то сохранение в файл идёт ../screenshot<порядковый номер скриншота>.png
- если 1, то сохраняется в base64 кодировке вывести можно код функцией [[#getScreenshotData]]
===== getScreenshotData =====
=== Краткое описание: ===
Возвращает строку с данными base64 созданного скриншота (ранее создан с помощью [[#goScreenshot]])
=== Пример использования: ===
scrnData = cl_exec( "getScreenshotData" )
====== Основные функции скриптов ======
===== print =====
=== Краткое описание: ===
Выводит сообщение одной строкой, либо выводит строки с расстоянием между собой (похоже на табуляцию \t) но одной строкой
=== Пример использования: ===
обычный подход
print("[Lua] Test complete.")
-- вывод:
-- [Lua] Test complete.
вывод с помощью пробелов напоминающую табуляцию
print("test1", "test2", "test3")
-- вывод:
-- test1 test2 test3
===== function =====
=== Краткое описание: ===
Стандартная функция в языке программирования Lua. Можно использовать функцию как отдельный поток ([[#thread]])
=== Пример использования: ===
обычное объявление функции
function fn1( var1 )
...
end
объявление одной строкой
fn1 = function(x) print(x) end
=== Использование: ===
fn1( 11122 )
===== for как бесконечный цикл =====
=== Краткое описание: ===
В Lua для **i = 1 math.huge do** создает цикл, который повторяется бесконечно, поскольку **math.huge** представляет собой наибольшее положительное число, которое может представить Lua, фактически действуя как бесконечность.
=== Пример использования: ===
for i = 1, math.huge do
print("Бесконечный цикл работает...")
end
===== coroutine =====
=== Краткое описание: ===
Механизм, позволяющий выполнять функции асинхронно и приостанавливать их выполнение на определённых этапах. В отличие от потоков, корутины не поддерживают параллелизм, но предоставляют удобный способ управлять асинхронным или частичным выполнением кода.
* **coroutine.resume** -- запускает или возобновляет выполнение корутины.
* **coroutine.yield** -- приостанавливает выполнение корутины до следующего вызова **resume**, сохраняя состояние.
=== Пример использования: ===
co1 = coroutine.create(function ()
tes = 1
while true do
print("co1 " .. tes)
tes = tes + 1
coroutine.yield() -- Приостанавливаем выполнение корутины
tes = tes + 1
end
end)
coroutine.resume(co1) -- запуск/возобновление
coroutine.resume(co1)
coroutine.resume(co1)
вывод:
* co1 1
* co1 3
* co1 5
=== Разбор примера: ===
-- Создаем корутину
co1 = coroutine.create(function ()
tes = 1 -- начальное значение
while true do -- бесконечный цикл
print("co1 " .. tes) -- вывод: 1, 3, 5...
tes = tes + 1 -- увеличиваем на 1
coroutine.yield() -- стоп, ждём resume
tes = tes + 1 -- продолжаем, увеличиваем ещё на 1
end
end)
-- Запускаем/возобновляем корутину 3 раза
coroutine.resume(co1)
-- Вывод: co1 1
coroutine.resume(co1)
-- Вывод: co1 3
coroutine.resume(co1)
-- Вывод: co1 5
1. Выполнение **coroutine.resume(co1)**
* Запуск функции: tes = 1
* вывод **"co1 1"**
* tes = 2
* coroutine.yield()
* остановка функции
2. Выполнение **coroutine.resume(co1)**
* Продолжение после yield(): tes = 3
* вывод **"co1 3"**
* tes = 4
* yield()
* остановка функции
3. Выполнение **coroutine.resume(co1)**
* Продолжение после yield(): tes = 5
* вывод **"co1 5"**
* tes = 6
* yield()
* остановка функции
===== thread =====
=== Краткое описание: ===
Создаёт отдельные последовательности выполнения кода, которые могут выполняться параллельно. Выполнение нескольких задач одновременно, существенно повышает производительность и реакцию программы.
=== Пример использования: ===
отдельный поток
function test1()
...
end
-- вызов:
thread( test1 )
отдельный поток с несколькими аргументами
function test1( var1, var2 )
...
end
-- вызов:
thread( function() test1(11, 22) end )
отдельный поток с использованием бесконечного цикла
function test1()
while( true )
do
...
yield() -- необходимо использовать задержку для избежания нагрузки на CPU
end
end
-- вызов:
thread( test1 )
=== Примечание ===
Отдельный поток не может работать со стандартным **require** ([[#require]]), альтернатива позволяет использовать таблицы ([[#readTable]]). Также не умеет работать с глобальными **metatable** (решение: локальные **metatable** можно создавать)
=== Ошибка: при использовании require в отдельном потоке ===
local ServerType = require( "mp/_servertype" )
-- attempt to call a nil value (method '...')
===== require =====
=== Краткое описание: ===
Стандартная Lua функция, которая загружает модули (файлы со скриптами). Она делает следующее:
* Проверяет, не был ли модуль уже загружен ранее (чтобы не загружать его дважды).
* Если модуль ещё не загружен, ищет файл с именем, соответствующим переданной строке.
* Выполняет этот файл.
* Возвращает результат загрузки модуля.
=== Пример использования: ===
Пример создания модуля для **require** с последующим созданием переменной:
local TestModule = {
KEY1 = 1,
KEY2 = 10,
KEY3 = 256
}
return TestModule
Создание переменной в основном скрипте
local TestModule = require("mp/testmodule.lua")
Подключение скрипта
require("_utility")
====== Базовые функции (на основе _<скриптов>.lua) ======
===== int_table =====
* Местоположение файла: **/lua/_utility.lua**
=== Краткое описание: ===
Возвращает значение строки из таблицы в виде числа
=== Пример использования: ===
int_table( <таблица>, <ключ> )
...
local flag = int_table( _packetType, "PLAYER" )
...
=== Обязательные аргументы: ===
* 1 : <таблица> (таблица)
* 2 : <ключ> (строка)
===== str_table =====
* Местоположение файла: **/lua/_utility.lua**
=== Краткое описание: ===
Возвращает значение строки из таблицы
=== Пример использования: ===
str_table( <таблица>, <ключ> )
...
local name = str_table( _tableTest, "PLAYER" )
...
=== Обязательные аргументы: ===
* 1 : <таблица> (таблица)
* 2 : <ключ> (строка)
===== debug_str_table =====
* Местоположение файла: **/lua/_utility.lua**
=== Краткое описание: ===
Выводит сообщение со строкой из таблицы
=== Пример использования: ===
debug_str_table( <таблица>, <ключ> )
=== Обязательные аргументы: ===
* 1 : <таблица> (таблица)
* 2 : <ключ> (строка)
===== debug_table =====
* Местоположение файла: **/lua/_utility.lua**
=== Краткое описание: ===
Выводит сообщение со всеми ключами и значениями
=== Пример использования: ===
debug_table( <таблица> )
-- вывод
-- Key: Firstname Value: Mark
=== Обязательные аргументы: ===
* 1 : <таблица> (таблица)
===== add_table =====
* Местоположение файла: **/lua/_utility.lua**
=== Краткое описание: ===
Добавление нового значения в таблицу
=== Пример использования: ===
add_table( <таблица>, <ключ> )
...
add_table( players, _local )
...
=== Обязательные аргументы: ===
* 1 : <таблица> (таблица)
* 2 : <ключ> (строка)
===== player_get_pos =====
* Местоположение файла: **/lua/_utility.lua**
=== Краткое описание: ===
Возвращает строку позиции игрока в специальном формате (используется при передаче в пакет)
=== Пример использования: ===
player_get_pos( , , , , )
...
-- присваиваем координаты нашего персонажа
playerCurrent = player_get_pos(
camera:getPosX(), -- x
camera:getPosY(), -- y
camera:getPosZ(), -- z
camera:getYaw(), -- поворот
camera:getPitch() -- наклон
)
...
=== Обязательные аргументы: ===
* 1 : (мировая координата X)
* 2 : (мировая координата Y)
* 3 : (мировая координата Z)
* 4 : (поворот камеры игрока)
* 5 : (наклон камеры игрока)
===== wait =====
* Местоположение файла: **/lua/_utility.lua**
=== Краткое описание: ===
Создает временную задержку в миллисекундах
=== Пример использования: ===
wait( <мс> )
=== Обязательные аргументы: ===
* 1 : <длительность> (мс)
===== yield =====
* Местоположение файла: **/lua/_utility.lua**
=== Краткое описание: ===
Создает в потоке временную задержку (используется для снижения нагрузки на процессор)
=== Пример использования: ===
yield()
===== shuffle =====
* Местоположение файла: **/lua/_utility.lua**
=== Краткое описание: ===
Случайное перемешивание значений таблицы
=== Пример использования: ===
shuffle( <таблица> )
=== Обязательные аргументы: ===
* 1 : <таблица> (таблица)