Union Framework Union API beta

GitLab: Union Framework / Union API
Wiki: Home · Union Framework / Union API
Текущий прогресс: около 90%

Union Framework — это мощный набор инструментов с открытым исходным кодом, предназначенный для глубокой модификации кода игр серии Gothic, основанных на движке ZenGin. Он позволяет разработчикам создавать собственные плагины, напрямую взаимодействующие с памятью игры, изменять её поведение и встраивать новые функции без необходимости предварительной установки каких-либо сторонних расширений, включая классический Union.

Основные возможности Union Framework:

• Перехват процедур и функций с гибкой настройкой
• Прямое изменение памяти (патчинг инструкций)
• Отслеживание событий загрузки библиотек
• Общая память между плагинами, включая общие синглтоны
• Работа с VDFS (виртуальной файловой системой Gothic)
• Инструменты для работы со строками и их локализацией

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

Методы перехвата (Hooking):
Union Framework реализует три подхода к перехвату функций, в зависимости от контекста и задач:

1. HOOK + AS (MS Detours):
   • Изменяет пролог целевой функции, переадресуя её вызов на вашу. Это мощный способ вмешательства, охватывающий весь процесс.
2. HOOK + PATCH:
   • Переопределяет все инструкции вызова конкретной функции, перенаправляя их на новую реализацию. Работает в пределах одного модуля, но совместим с другими расширителями.
3. Частичный хук (Partial Hook):
   • Позволяет встроить C++-функцию прямо в середину целевой функции. Полезно, когда необходимо вмешаться в конкретный участок логики, не перехватывая всё поведение целиком.

Также доступны условные хуки: HOOK + AS_IF и HOOK + PATCH_IF — с возможностью отложенного применения при помощи метода Commit.

Общая память и синхронизация:
Для обеспечения стабильности и совместимости между плагинами Union Framework предоставляет механизм общей памяти, позволяющий:

• Использовать единые методы аллокации
• Создавать глобальные синглтоны, видимые сразу всем плагинам
• Согласовывать доступ к общим данным и точкам входа

Актуально для тех сценариев, где один и тот же участок кода может быть изменён несколькими расширениями. Union Framework берёт на себя управление очередностью и совместимостью хуков.

Union API — это центральная часть Union Framework, предоставляющая полноценный интерфейс для работы с объектами игры в памяти. Он позволяет нативным плагинам:

• Получать доступ к структурам ZenGin (в том числе актёрам, объектам мира, GUI и т. д.)
• Использовать шаблон декоратор для расширения функциональности игры
• Работать с памятью напрямую, без ограничений

В связке с ним используется отдельный Gothic API, содержащий заголовочные файлы ZenGin с привязкой к адресам памяти под конкретные версии игр Gothic.

Сборка и использование:
Union API реализован как проект на Visual Studio 2022 и поддерживает сборку в разных форматах:

• DLL — динамически подключаемая библиотека (рекомендуется)
• LIB — статическая библиотека
• EXE — консольное приложение для отладки вне игры

Создание плагина требует подключения union-api к своему проекту C++, добавления соответствующих include-путей и определения макросов: _UNION_API_DLL или _UNION_API_LIB, в зависимости от способа подключения.

Полная документация, примеры и инструкции находятся в официальной Wiki Union API.