Документация

Как всё устроено: стартер внедряет addon.dll в процесс игры, аддон патчит движок в памяти и перехватывает файловый ввод-вывод — оригинальные файлы «Проклятых земель» при этом остаются нетронутыми.

Что такое addon.dll

Это не мод, а расширение движка (engine extension) для оригинального game.exe «Проклятых земель» с патчем 1.06. Внутри библиотека называет себя Evil Islands Addon Engine.

  • Патчит движок в памяти при запуске. Каждый патч именованный и может включаться отдельно; целостность проверяется, поэтому аддон сообщает об ошибке, если игру уже пропатчил кто-то другой.
  • Перехватывает файловый ввод-вывод и подменяет ресурсы и конфиги — мод подкладывает свои .res-файлы, не трогая оригинальные.
  • Перенаправляет пути сохранений — у каждого мода свои сейвы.
  • Добавляет команды скриптового движка .mob-скриптов и новые консольные команды.
  • Содержит систему плагинов *.plg и собственный обработчик падений с записью минидампов.
Не путать: EI_Plugin — отдельное, более раннее расширение движка через ASI-загрузчик. Аддон умеет с ним сосуществовать и проверяет его версию при запуске; часть возможностей EI_Plugin со временем переехала в сам addon.dll.

Установка

Стартер ставится отдельной папкой — рядом с игрой или вообще на другом диске. Он не изменяет и не добавляет файлы игры и не трогает настройки реестра игры. Внедрение аддона в процесс выполняется через dinput.dll в папке игры.

Evil Islands\ ← игра, патч 1.06 game.exe dinput.dll ← загрузчик, через него подключается addon.dll Config\ai.reg Res\ Starter\ ← ставится отдельной папкой EIStarter.exe addon.dll addon.log Dumps\ ← минидампы при падении Mods\ <Имя мода>\ config.reg ← манифест мода (обязательный) addon.dll ← опционально: своя версия аддона под этот мод config\ ← переопределённые ai.reg и другие конфиги Res\ ← переопределённые .res-ресурсы maps\ ← карты мода saves\, mp\ ← сейвы, разложенные по модам
Обновление только библиотеки: распаковать содержимое архива addon.dll в папку стартера, подтвердив замену файлов. Если стартера ещё нет — ставьте инсталлятор стартера, он приносит аддон с собой.

Начиная с версии стартера 1.046.1 аддон можно класть внутрь папки конкретного мода — тогда мод раздаётся одной папкой вместе со своей версией библиотеки. Это нужно модам, которые разошлись по требованиям к версии аддона.

Конфигурация

config.reg — манифест мода. Это не текстовый .reg-файл Windows, а бинарный «нивальский» реестровый формат — тот же, что у ai.reg. Файл состоит из нескольких секций.

MOD
Метаданные и флаги мода: Title, Author, AuthorEmail, Date_DMY, Version, Single, ForceShowTutorial. Сюда же относятся AddonVersion — минимально требуемая версия аддона — и Plugin.
RES
Таблица подмены ресурсов вида «оригинальное имя → файл мода», например database.res → res\database_100.res. Аддон умеет подменять figures.res, menus.res, textures.res, redress.res, aiinfo.res, database.res, databaseLmp.res, gfx.res, materials.res, outro.res, sfx.res, speech.res, texts.res, textsLmp.res.
CONFIG
Подмена конфигов игры: ai.reg → config\ai.reg. Кроме него перехватываются Tutorial.ini, Lights.ini, Movie.ini, StreamSN.reg и Music.reg. Мод не правит ai.reg на месте, а подкладывает свою копию.

Ключи настроек аддона

Помимо манифеста у аддона есть собственный набор флагов. Наиболее заметные группы:

  • Геймплей и баланс: AttackAnimSpeed, NewRunes, FastTeleport, DisableCrippledHL, UnlockExperimentalSpells, UsePerkLimit, ShowAllQuests, UsePrototypeActionsForMobAttack, UsePrototypeActionsForMobCast.
  • Скрипты и консоль: AddNewScriptCommands, AddNewConsoleCommands, ImproveConsole, AllowScriptsInMainMenu, AllowScriptArgsInLoops, AutoExec.
  • Стабильность и отладка: AntiCrash, FullDump, DisableExitOnCrashReport, GameDebugFile, ChatHtmlFile.
  • Графика и интерфейс: WideScreen, LandscapeDrawRadius, ObjectsDrawRadius, ImproveInfoWindows, AdvancedDescriptions.
Часть пользовательских настроек живёт не в конфигах, а в реестре стартера — ветка HKEY_CURRENT_USER\Software\Gipat.Ru\EI_Starter: путь к игре, VIDEORESOLUTION, WideScreen, радиусы отрисовки, LogLevel, AutoRecover и другие.

Plugin API

Аддон сканирует папку Plugins и загружает файлы по маске *.plg — это нативные библиотеки. У плагина есть две точки входа, которые аддон вызывает и логирует:

EntryBeforePatch // вызывается до применения патчей движка EntryAfterPatch // вызывается после применения патчей

Стоит различать два разных API: нативный Plugin API (*.plg, для C/C++) и Lua API для мододелов без нативного кода — в новых ветках аддона встроен LuaJIT, и мод может переопределять формулы боя, опыта и цен скриптом main.lua.

Раздел неполон. Точные сигнатуры функций, версия ABI и заголовочный файл SDK в открытом доступе не опубликованы. За актуальным заголовком имеет смысл обращаться к разработчикам аддона на форуме, а не реконструировать интерфейс самостоятельно.

Скриптовые функции

Дополнительные команды .mob-скриптов включаются флагом AddNewScriptCommands. Точные сигнатуры и семантику смотрите в файле whatnews.htm внутри архива с аддоном — он идёт в комплекте каждой версии.

Строки
StrLen, StrCat, StrUpper, StrLower, StrMid, StrHas, StrToFloat, FloatToStr
Математика и случайность
Abs, Min, Max, Ceil, Floor, Round, Random, RandObj, RandStr
Переменные игроков
GSSetPlayerVar, GSGetPlayerVar, GSListPlayerVars — сетевой аналог GSSetVar / GSGetVar из сингла. Переменные с префиксом gvar. хранятся вечно: цепочки квестов, факты о персонаже и прочее.
Игроки и юниты
PlayerExists, GetPlayerOfUnit, GetUnitExp, GiveExp, GetStrength, GetDexterity, GetIntelligence, GetSkill, GetPerk, GetRace, GetUnitState, GetEncumbrance
Бой и магия
InflictDamageEx, CastSomeSpell, CastSomeSpellTarget, ResetTarget, DamageMainUnitWeapon, AddQuick2Unit, AckPotion
Геометрия и поиск
UnitsNearPoint, NearestUnit, DistancePointPoint
Служебное
ConsoleString, IsFileExists, GameOver, GameOverMSG, SendCurrentParty, Loot

Проверка скриптов

С версии 0.10.0.0 в комплекте идёт addon.bat с командой check — офлайновая проверка синтаксиса без запуска игры. Принимает пути до файлов и папок или шаблоны:

addon.bat check maps\zone*.mob

Ошибки в рантайме видны в консоли и логе в формате Script error: line N: ....

Устранение проблем

Логи и дампы

Основной лог — addon.log рядом с addon.dll. Уровень логирования задаётся из игровой консоли:

addon debug log {уровень} # уровень записи в addon.log addon debug console {уровень} # уровень вывода в игровую консоль addon info # версия ядра аддона и текущий мод

При падении аддон пишет минидамп в папку Dumps\ и показывает код и адрес ошибки. Настройка FullDump включает полный дамп вместо мини.

Частые проблемы

Игра не запускается на Windows 10/11
Запускать от имени администратора — игре нужно писать в свою папку. И не устанавливать её в C:\Program Files или Program Files (x86); подойдёт, например, C:\Games.
Режим совместимости с Windows 98
Не рекомендуется: на форуме прямо пишут, что он чаще вредит, чем помогает.
Ошибка «MSS DLL file is installed in Windows…»
Удалить Mss32.dll из C:\Windows\SysWOW64 с правами администратора.
Аддон вообще не работает, игра запускается «голой»
Скорее всего пропал dinput.dll из папки игры — его мог удалить антивирус или чистильщик. Без него функциональность addon.dll отключается целиком.
«Addon vX или новее требуется для запуска мода»
Мод объявляет минимальную версию в AddonVersion. Обновите аддон или стартер — старый стартер с новым аддоном совместимы не всегда.
«Patch … verification failed: game's memory was modified by someone else»
Признак того, что game.exe уже пропатчен сторонним инструментом или это не версия 1.06.
Широкоэкранные разрешения
В аддоне есть встроенный патч WideScreen, разрешение задаётся стартером. Смешивать его со сторонними widescreen-фиксами не стоит — патчи конфликтуют.
Версия от GOG
Чтобы завёлся стартер, применяют Evil Islands Repair Tool (EIRT). При слетевших реестровых настройках помогает eireger или Init Starter Registry.bat. Совместимость с GOG-версией появилась в стартере 1.045.0.
Мультиплеер
Игра использует UDP-порт 8888; для публичного сервера нужен «белый» IP и проброс порта. Мастер-сервер выбирается настройкой MPZone.
Статус документации. Это прототип: раздел собран по материалам форума gipath.org, справочника сообщества и строк самой библиотеки. Имена ключей и функций приведены дословно, но сигнатуры и точная семантика требуют сверки с whatnews.htm из архива соответствующей версии.