Описание экспортируемых функций ERA

Ниже будут описаны основые функции и процедуры ERA. Более полная технической документации располагается в каталоге Игра\Tools\Era\, или же вы можете задать конкретные вопросы непосредственно на официальном форуме проекта.

• PROCEDURE Hook (HandlerAddr: POINTER; HookType: INTEGER; PatchSize: INTEGER; CodeAddr: POINTER); STDCALL;
  Универсальная функция для установки программных перехватчиков в коде. Наиболее удобный и автоматизированный режим: HookType = HOOKTYPE_BRIDGE, при котором низкоуровневый переходник к высокоуровневой функции будет сгенерирован автоматически.
  Пример высокоуровневой функции:

  PROCEDURE Hook_X (Context: PHookHandlerArgs): LONGBOOL; STDCALL;

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

• PROCEDURE ApiHook; STDCALL;
  Определяет минимальный размер заплатки самостоятельно, в отличие от функции Hook.
  И ApiHook, и Hook функции возвращают новый адрес затёртого кода в режиме моста (BRIDGE), что позволяет вызывать также и оригинальные функции, минуя установленные перехватчики.

• PROCEDURE ClearAllIniCache; STDCALL;
  

• PROCEDURE ClearIniCache; STDCALL;
  Полностью очищает кэш загруженных в память ini-файлов.

• PROCEDURE ExecErmCmd (CmdStr: PCHAR); STDCALL;
  Выполняет указанную одиночную ERM команду в формате XX:... без условий.
  Пример:

  ExecErmCmd('IF:L^Hello, World!^;');

• PROCEDURE ExtractErm; STDCALL;
  Экспортирует все стандартные скрипты (00..99) в папку Data\s\ExtractedScripts.

• PROCEDURE FatalError (Err: PCHAR); STDCALL;
  Отображает сообщение о критической ошибке и тихо завершает текущий процесс.

• PROCEDURE FireEvent (EventName: PCHAR; {n} EventData: POINTER; DataSize: INTEGER); STDCALL;
  Генерирует событие и извещает о нём всех подписанных обработчиков. EventData указывает на блок параметров события (если есть), а DataSize определяет размер этого блока. Посредством данного механизма можно передавать обработчикам ценную информацию о событии.

• PROCEDURE FireErmEvent (EventID: INTEGER); STDCALL;
  Генерирует новое ERM событие путём вызова ERM функции с указанным номером. Такой вызов не сохраняет отрицательные z-переменные.
  ERA обязует создателей плагинов сохранять предыдущие параметры событий (SN:X) через функцию SaveEventParams ДО вызова FireErmEvent и восстанавливать через функцию RestoreEventParams ПОСЛЕ вызова, чтобы каждое новое событие обладало своим набором SN:X параметров.

• PROCEDURE ForceTxtUnload (Name: PCHAR); STDCALL;
  Заставляет игру выгрузить txt-таблицу из памяти.
  Замечание: используйте с осторожностью!

• FUNCTION GetButtonID (ButtonName: PCHAR): INTEGER; STDCALL;
  Функция даёт возможность получить уникальный идентификатор (ID) пользовательской кнопки по указанному имени в игровом диалоге. Если такое имя не было зарегистрировано, то функция вернёт -1.
  Подробнее (показать)
  В ERA cтало возможным иметь пользовательские кнопки в большинстве игровых диалогах. Пользовательские кнопки описываются в *.btn файлах, которые подгружаются из папки Data\Buttons при старте игры. Каждый *.btn файл (чистый txt-формат) содержит строки (по одной на кнопку) в следующем формате:

  Экран кнопки;Уникальное имя кнопки;DEF кнопки;X;Y;Ширина;Высота;Длинное описание;Короткое описание;Код горячей клавиши

  , где [Экран кнопки] может принимать одно из следующих значений:

  • Advmap (для карты приключений)
  • Town (для города)
  • Hero (для экрана героя)
  • Heroes (для экрана встречи героев)
  • Battle (для экрана битвы)
  • Dummy (если кнопка не используется)

  Каждой такой настроенной кнопке автоматически назначается свой уникальный ID.
  Пример:

  Hero;SecSkills.ScrollUp;ScrollUp.def;300;303;12;44;sss.scroll_up;sss.scroll_up;38

• PROCEDURE GetGameState (VAR GameState: TGameState); STDCALL;
  Получает текущее состояние игры в виде пары идентификаторов диалогов: главного родительского и текущего дочернего (0 = диалоги ещё не созданы).
  Функция полезна для определения, в каком диалоге происходит нажатие клавиши.
  По умолчанию от функции ID текущего диалога будет помещён в переменную v1.
  Пример (показать)
  Расшифровка примера: SN:F вызывает внешнюю функцию GetGameState. ?y1 означает передачу в качестве параметра адрес y1 в памяти (y1 занимает 4 байта, y2 тоже четыре). А функция на самом деле работает с адресом структуры в 8 байт из двух полей:
  - родительский диалог (ID); приходится на y1
  - дочерний (текущий) диалог (ID); приходится на y2
  Если текущий диалог – экран боя и нажата клавиша Q, то отменяем обработку нажатия, установив 2ой параметр события OnKeyPressed в 1.

• FUNCTION GetRealAddr (Addr: POINTER): POINTER; STDCALL;
  

• PROCEDURE KillThisProcess; STDCALL;
  Тихо убивает текущий процесс.

• FUNCTION LoadImageAsPcx16 (FilePath, PcxName: PCHAR; Width, Height, MaxWidth, MaxHeight, ResizeAlg: INTEGER): {OU} Heroes.PPcx16Item; STDCALL;
  Функция даёт возможность загружать любые PNG/JPG/BMP-файлы как игровые PCX-картинки, подходящие для замены внутриигровых изображений или для показа в диалогах. Она поддерживает ограничение размера (0 - без ограничений) и алгоритмы масштабирования.

  RESIZE_ALG_NO_RESIZE = 0; // Не применять никакие ограничения и не менять размер картинки
  RESIZE_ALG_STRETCH = 1; // Задать ширину и высоту картинки для ширины и высоты окна, масштабировать непропорционально
  RESIZE_ALG_CONTAIN = 2; // Изменить размер картинки так, чтобы по крайней мере один из её размеров стал таким же, как размер окна, а другой стал меньше или равным размеру окна
  RESIZE_ALG_DOWNSCALE = 3; // Только пропорционально сжимать картинки, не растягивать маленькие картинки
  RESIZE_ALG_UPSCALE = 4; // Только пропорционально масштабировать маленькие картинки, большие картинки оставлять как есть
  RESIZE_ALG_COVER = 5; // НЕ РЕАЛИЗОВАНО
  RESIZE_ALG_FILL = 6; // Использовать картинку как плитка для заполнения всего окна
  Используйте ALG_STRETCH для установки фиксированных размеров, ALG_FILL - для заполнения окна плитками и ALG_DOWNSCALE - для настраиваемых диалогов, чтобы пропорционально сужать большие картинки.

  
  Пример (показать)
  Давайте возмём свою JPG-картинку для DL-диалога.

• FUNCTION LoadTxt (Name: PCHAR): {n} PTxtFile; STDCALL;
  Загружает txt-таблицу средствами игры.

• PROCEDURE NameColor (Color32: INTEGER; Name: PCHAR); STDCALL;
  Функция должна вызываться в событии OnAfterCreateWindow и предназначена для создания или переопределения названий цветов для цветного текста ERA.
  Пример:

  NameColor($000000, 'bl'); теперь можно использовать {~bl}...{~} для чёрного текста

• FUNCTION PatchExists (Name: STRING): BOOLEAN; STDCALL;
FUNCTION PluginExists (Name: STRING): BOOLEAN; STDCALL;
  Проверяют наличие патча/плагина в ERA.
  Пример (показать)

• FUNCTION ReadSavegameSection (DataSize: INTEGER; {n} Dest: POINTER; SectionName: PCHAR): INTEGER; STDCALL;
  Функция должна вызываться в событии OnSavegameRead и служит для чтения пользовательских данных из именованной файловой секции. Последовательное чтение из одной и той же секции допустимо. Возвращает количество прочитанных байт.

• PROCEDURE WriteSavegameSection (DataSize: INTEGER; {n} Data: POINTER; SectionName: PCHAR); STDCALL;
  Функция должна вызываться в событии OnSavegameWrite и служит для записи пользовательских данных в именованную файловую секцию. Допускается последовательная запись в одну и ту же секцию.

• FUNCTION ReadStrFromIni (Key, SectionName, FilePath, Res: PCHAR): BOOLEAN; STDCALL;
  Считывает значение из указанного ini-файла в буфер Res. При первом же чтении ini-файл анализируется, кэшируется и дальнейшие запросы приводят к выборкам из ассоциативного массива, которые происходят очень быстро и без обращения к жёсткому диску.

• FUNCTION WriteStrToIni (Key, Value, SectionName, FilePath: PCHAR): BOOLEAN; STDCALL;
  Записывает значение в ini-файл. Каждый вызов функции приводит к записи всего файла на диск.

• FUNCTION RecallAPI (Context: PHookHandlerArgs; NumArgs: INTEGER): INTEGER; STDCALL;
  

• PROCEDURE RedirectFile (OldFileName, NewFileName: PCHAR); STDCALL;
  

• PROCEDURE GlobalRedirectFile (OldFileName, NewFileName: PCHAR); STDCALL;
  

• PROCEDURE RedirectMemoryBlock (OldAddr: POINTER; BlockSize: INTEGER; NewAddr: POINTER); STDCALL;
  

• PROCEDURE RegisterHandler (Handler: TEventHandler; EventName: PCHAR); STDCALL;
  Регистрирует обработчик указанного события. Обработчики вызываются в порядке их регистрации. Список событий можно просмотреть в файле Tools\Era\SDK\triggers.txt. Два ключевых события, в которым должен быть расположен код инициализации модулей и регистрации обработчиков: OnBeforeWoG, OnAfterWoG.

• PROCEDURE ReloadErm; STDCALL;
  Вызывает полную перезагрузку и перекомпиляцию всех erm/ert скриптов (00..99). Аналогична нажатию клавиши F12.

• PROCEDURE SaveEventParams; STDCALL;
  Сохраняет SN:X параметры события в стековой структуре.

• PROCEDURE RestoreEventParams; STDCALL;
  Восстанавливает сохранённые SN:X параметры из стековой структуры.

• FUNCTION SaveIni (FilePath: PCHAR): BOOLEAN; STDCALL;
  

• PROCEDURE WriteAtCode (Count: INTEGER; Src, Dst: POINTER); STDCALL;
  Производит безопасное копирование блока памяти из источника в место назначения.