====== API игрового движка через DLL ======

Данная статья описывает публичный API, доступный через динамически подключаемые библиотеки (DLL).

API разделён на две основные части:
  - ''me_crypto.h'' — функции криптографии и строковых преобразований.
  - ''me_engine.h'' — функции управления движком, окном, камерой и объектами.

====== Типы переменных ======
Все типы переменных в API перечислены в файле "sources/API/me_interface.h"
<Code cpp [start_line_numbers_at=18]>
// ...
#define CONST			const
#define ME_DEF			typedef
#define ME_CALL			__stdcall*
#define ME_Int			int
#define ME_Bool			bool
#define ME_Char			char
#define ME_CharSign		unsigned char*
#define ME_Void			void
#define ME_String		std::string
#define ME_WString		std::wstring
#define ME_Size			size_t
#define ME_UInt			unsigned int
#define ME_Float		float
// ...
</Code>

===== me_crypto =====

==== MESplit ====
Разделяет строку на значения по указанному символу-разделителю.

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>size_t MESplit(CONST ME_String& txt, std::vector<ME_String>& strs, char ch)</Code>

**Параметры:**
  * ''txt'' — входная строка.
  * ''strs'' — ссылка на вектор массив (результат: в массиве появятся разделенные строки).
  * ''ch'' — символ-разделитель.

**Возвращает:** количество полученных подстрок.

**Пример:**
<Code cpp [start_line_numbers_at=1]>
std::vector<std::string> list;
MESplit("a;b;c", list, ';');
std::cout << "a=" << list[0].c_str() << std::endl;
std::cout << "b=" << list[1].c_str() << std::endl;
std::cout << "c=" << list[2].c_str() << std::endl;
</Code>

==== ReadFileME ====
Читает содержимое файла и возвращает его как строку.

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>ME_String ReadFileME(CONST ME_String& str)</Code>

**Параметры:**
  * ''str'' — путь к файлу.
**Возвращает:** содержимое файла в виде строки текст или ошибку "error".

==== getRegisterAccount ====
Возвращает уникальный идентификатор пользователя (User ID).

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>ME_String getRegisterAccount()</Code>

**Возвращает:** строку с идентификатором пользователя.
==== ConvertToWSTR ====
Преобразует тип строки ''ME_String'' в ''ME_WString'''.

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>ME_WString ConvertToWSTR(const ME_String& str)</Code>

**Параметры:**
  * ''str'' — входная строка.

**Возвращает:** ME_WString.
==== ConvertToString ====
Преобразует тип строки ''ME_WString'' в ''ME_String''.

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>ME_String ConvertToString(const ME_WString& wstr)</Code>

**Параметры:**
  * ''wstr'' — исходная ME_WString строка.

**Возвращает:** строка ME_String.

==== ConvertToSign ====
Преобразует тип строки ''ME_String'' в ''ME_CharSign''.

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>ME_CharSign ConvertToSign(CONST ME_String& str)</Code>

**Параметры:**
  * ''str'' — входная строка.

**Возвращает:** ME_CharSign.

==== ToBase64 ====
Кодирует массив байтов в строку Base64.

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>ME_String ToBase64(ME_CharSign bytes_to_encode, ME_Size len, ME_Bool url)</Code>

**Параметры:**
  * ''bytes_to_encode'' — ME_CharSign.
  * ''len'' — длина массива.
  * ''url'' — если "true", используется URL-безопасный вариант Base64.

**Возвращает:** закодированная строка Base64.

==== ofBase64 ====
Декодирует строку Base64 обратно в ''ME_String''.

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>ME_String ofBase64(ME_String CONST& s, ME_Bool remove_linebreaks)</Code>

**Параметры:**
  * **s** — строка ME_String в формате Base64.
  * **remove_linebreaks** — если "true", удаляются символы переноса строк перед декодированием.

**Возвращает:** декодированная строка ME_String.
==== ToHex ====
Преобразует 32-битное целое число в шестнадцатеричную строку, представляя его как последовательность байтов в **младшем порядке (little-endian)**. Каждый байт кодируется двумя шестнадцатеричными символами в нижнем регистре без префикса `0x`.


**Синтаксис:**
<Code cpp [enable_line_numbers=0]>ME_String ToHex(ME_UInt value)</Code>

**Параметры:**
  * ''value'' — число для преобразования.
  * ''value'' — 32-битное целое число без знака для преобразования (тип ME_UInt).

**Возвращает:** строка ME_String в формате HEX (без префикса "0x", в нижнем регистре).
==== ToMD5 ====
Вычисляет MD5-хеш от заданной строки ME_String.

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>ME_String ToMD5(ME_String str)</Code>

**Параметры:**
  * ''str'' — исходная строка ME_String.

**Возвращает:** MD5-хеш в виде 32-символьной шестнадцатеричной строки.
==== genMD5 ====
Генерирует случайный MD5-хеш.

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>ME_String genMD5()</Code>

**Возвращает:** случайный MD5-хеш с типом ME_String.






===== me_engine =====

==== meInitialize ====
Инициализирует игровой движок.

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>ME_Int meInitialize(CONST ME_Int mode)</Code>

**Параметры:**
  * ''mode'' — режим инициализации (по умолчанию 0).
    * режим игры: 0
    * режимы редактора: 1, 2

**Возвращает:** 0 при успехе.

==== meExit ====
Завершает работу движка.

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>ME_Void meExit()</Code>

==== meSetWindow ====
Устанавливает окно для рендеринга.

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>ME_Int meSetWindow(HWND hWnd, ME_Int width, ME_Int height, ME_Bool noDops)</Code>

**Параметры:**
  * ''hWnd'' — указывается дескриптор окна Windows.
  * ''width'', ''height'' — размеры клиентской области.
  * ''noDops'' — если "true", то происходит изменения размера как для редактора карт.

**Возвращает:** ME_Int: успешно = 0, если неудачно = 1.

==== meSetFullscreen ====
Переключает полноэкранный режим.

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>ME_Void meSetFullscreen(ME_Bool fullscreen = true)</Code>

**Параметры:**
  * ''fullscreen'' — (по умолчанию "true") для включения полноэкранного режима.

==== meSetSceneCallBack ====
Устанавливает callback-функцию для обработки событий сцены. Работает только при полностью запущеном игровом движке в режиме редактора.

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>ME_Int meSetSceneCallBack(EditorSceneCallback callback)</Code>

**Параметры:**
  * ''callback'' — указатель на функцию типа "EditorSceneCallback".

**Тип callback:**
<Code cpp [enable_line_numbers=0]>ME_Void(ME_CALL EditorSceneCallback)(CONST ME_Char* id, ME_Int action)</Code>

**Возвращает:** ME_Int: успешно = 0, если неудачно = 1.

==== meLoadLevel ====
Загружает или очищает текущий уровень.

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>ME_Int meLoadLevel(CONST ME_Char* name)</Code>

**Параметры:**
  * ''name'' — имя уровня. 
    * если "nullptr" — очищает текущий уровень.
    * если функция "meLoadLevel" запускается в режиме редактора, и указанного уровня не существует, то возвращает 1.

**Возвращает:** ME_Int: 0 обычно.

==== meGetHWND ====
Возвращает дескриптор окна, используемого движком.

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>HWND meGetHWND()</Code>

**Возвращает:** ''HWND'' дескриптор окна или "NULL".

==== meCameraAt ====
Телепортирует камеру в заданную точку.

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>ME_Int meCameraAt(ME_Float x, ME_Float y, ME_Float z)</Code>

**Параметры:**
  * ''x'', ''y'', ''z'' — координаты позиции камеры.

**Возвращает:** ME_Int: успешно = 0, если неудачно = 1.

==== meGetCameraAt ====
Получает текущие координаты и направление камеры.

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>ME_Int meGetCameraAt(ME_Float& x, ME_Float& y, ME_Float& z, ME_Float& yaw)</Code>

**Параметры:**
  * ''x'', ''y'', ''z'' — указываются ссылки куда будут записаны координаты камеры.
  * ''yaw'' — угол поворота камеры в радианах.

**Возвращает:** ME_Int: успешно = 0, если неудачно = 1.

==== GetObjectAt ====
Возвращает список объектов в заданной области.

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>CONST ME_Char* GetObjectAt(ME_Float x, ME_Float y, ME_Float z, ME_Int radius)</Code>

**Параметры:**
  * ''x'', ''y'', ''z'' — центр области. Если все нули — используется позиция камеры.
  * ''radius'' — радиус поиска (в условных единицах).

**Возвращает:** строка с идентификаторами объектов (разделённых символом ";"), иначе пустая строка.

==== meSetPos ====
Устанавливает позицию окна на экране. (работает в режиме редактора)

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>ME_Void meSetPos(ME_Int x, ME_Int y)</Code>

**Параметры:**
  * ''x'', ''y'' — координаты левого верхнего угла окна.

==== meIsOpen ====
Проверяет, открыто ли окно игрового движка.

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>ME_Bool meIsOpen()</Code>

**Возвращает:** "true", если окно открыто и активно.

==== meBoolAction ====
Выполняет логическое действие (вкл/выкл) над системными функциями.

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>ME_Bool meBoolAction(meActions type, ME_Int set = -1)</Code>

**Параметры:**
  * ''type'' — тип действия (см. "enum class meActions"):
    * ''UI_FPS'' — отображение FPS. **(устарело)**
    * ''UI_FULLSCREEN'' — полноэкранный режим. **(устарело)**
    * ''VM_LIGHTS'' — показывать освещение. **(устарело)**
    * ''VW_WIREFRAME'' — каркасный режим отображения мира.
    * ''VM_ACT'' — включение или отключение рендера (пауза).
      * **set** — если "0" = выкл, "1" = вкл, иначе переключает текущее состояние.
    * ''VM_TOOLS'' — показ технических объектов редактора.
  * ''set'' — применяется только для ''VM_ACT''.

**Возвращает:** ME_Bool: новое состояние ("true"/"false").

==== meImgStream ====
Выполняет создание скриншота

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>ME_Void meImgStream(ME_Bool answer)</Code>

**Параметры:**
  * ''answer'' — аргумент остался от старой реализации, но его нужно указывать "true"

==== meImgData ====
Возвращает последний сделанный скриншот с помощью функции "meImgStream" в формате Base64.

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>CONST ME_Char* meImgData()</Code>

**Возвращает:** строка Base64 с изображением png, либо пустая строка.

==== meGetTitle ====
Возвращает заголовок окна (Windows).

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>LPWSTR meGetTitle()</Code>

**Возвращает:** LPWSTR строка.

==== meGetTitleScript ====
Возвращает заголовок окна который был присвоен с помощью скрипта.

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>CONST ME_Char* meGetTitleScript()</Code>

**Возвращает:** ME_Char строка.

==== meWindowHide ====
Скрывает или показывает окно игрового движка.

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>ME_Void meWindowHide(ME_Bool visible)</Code>

**Параметры:**
  * ''visible'' — "true" для отображения, "false" для скрытия.

==== meClickCamera ====
Включает/отключает управление камерой нажатием мыши.

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>ME_Void meClickCamera(ME_Bool enabled)</Code>

**Параметры:**
  * **enabled** — `true` для включения режима управлением камеры (камеру поворачивать можно с помощью нажатия мыши).

==== meWindowState ====
Устанавливает состояние окна (свёрнуто, развёрнуто и т.д.).

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>ME_Void meWindowState(ME_Int mode)</Code>

**Параметры:**
  * ''mode'' — код состояния:
    * если 1 - показать окно
    * если 0 - скрыть окно

==== mePauseEditor ====
Режим редактора на паузе или активен.

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>ME_Void mePauseEditor(ME_Bool paused)</Code>

**Параметры:**
  * ''paused'' — "true" для паузы.

==== meManipulate ====
Выполняет манипуляции с объектами сцены (в режиме редактора).

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>ME_Void meManipulate(ME_Int type, CONST ME_Char* arguments)</Code>

**Параметры:**
  * ''type'' — тип манипуляции.
  * ''arguments'' — строка с параметрами, указывается в формате "<под тип>;<параметры для манипуляции>".

**Работа с параметрами** [''type'' = 0 — Взаимодействие с объектами, ''type'' = 1 — Взаимодействие с миром]
^ ''type'' ^ ''<подтип>'' ^ описание ^ формат ^
| 0 | 1 | режим выделения (если <id-объекта> = -1, убрать выделение) | 1;<группа>;<id-объекта> |
| 0 | 2 | изменение оси вращения | 2;<цифра: X = 0, Y = 1, Z = 2> |
| 0 | 3 | новый или изменить объект подгрузить из файла objects.json | 3;<id-объекта> |
| 0 | 5 | удалить объект | 5;<id-объекта> |
| 0 | 6 | удалить группу вместе с объектами | 6;<группа |
| 0 | 7 | создать новую группу с названием | 7;<название группы>|
| 0 | 8 | обновить трансформацию у объекта | 8;<id-объекта> |
| 1 | 1 | ambient | 1;0.1 |
| 1 | 2 | _color | 2;0.5;0.5;0.5 |
| 1 | 3 | sunColor | 3;0.75;0.901961;1.0 |
| 1 | 4 | sunLight | 4;0.6 |
| 1 | 5 | sunRadiosity | 5;0.6 |
| 1 | 6 | sunDiffuseColor | 6;0.5;0.5;0.5 |
| 1 | 7 | diffuseFraction | 7;0.583333 |
| 1 | 8 | sunDirection | 8;-30.0;42.0;0.0 |
| 1 | 9 | sunIsPrimaryLight | 9;1 |
| 1 | 10 | radiosityScale | 10;0.8 |
| 1 | 11 | contrastGain | 11;1.0 |
| 1 | 12 | shadowIsOutdoor | 12;1 |
| 1 | 13 | shadowSize | 13;2.0 |
| 1 | 14 | shadowOpacity | 14;0.5 |
==== meGetObjData ====
Получает трансформацию объекта: позицию, поворот, масштаб.

**Синтаксис:**
<Code cpp [enable_line_numbers=0]>CONST ME_Char* meGetObjData(ME_Int type, CONST ME_Char* id)</Code>

**Параметры:**
  * ''type'' — группа объектов.
    * если знаем группу в которой состоит объект, указываем (обычно начинается с нуля).
    * если не знаем в какой существует объект группе, указываем "-1".
  * ''id'' — идентификатор объекта.

**Возвращает:** ME_Char*: строка с данными в формате, \\
например: "position.x;position.y;position.z;rotation.x;rotation.y;rotation.z;scale.x;scale.y;scale.z" \\
или пустой ответ: "0;0;0;0;0;0;0;0;0".

===== Примечания =====
  - Все типы `ME_*` (например, `ME_String`, `ME_Int`, `ME_Bool`) определены в ''me_interface.h''.
  - На Windows используется ''HWND'', ''LPWSTR'' и другие типы Windows API.
  - Для использования API необходимо подключить соответствующие заголовочные файлы и линковать с DLL движка.