Union SDK - Краткий мануал

[Gratt]

Русский English

• 
  Тема посвящена адептам движка ZenGin и C++.
  Тут будут выложены самые ключевые этапы разработки плагина, а также упомянуты основные инструменты для работы с движком.
  
• 
  The topic is dedicated to the ZenGin engine and C ++.
  In this topic we will cover main stages of plugins development, as well as the main tools for working with the engine.
  

 

[Gratt]

Русский English

• 
  Начало работы с Union SDK
  1. Установка
  
  Спойлер

  Через Менеджер ресурсов или автономный установщик инсталлировать шаблон Union плагина, а также сопутствующие инструменты SDK.
  

  

  
  
  В Visual Studio в меню создания проекта найти шаблон Union плагина.
  

  

  
  
  
  В свойствах проекта выбрать подходящий Вам Набор инструментов платформы.
  

  
  
  2. Рабочее пространство
  
  Спойлер

  Добавьте в проект новые файлы исходного кода через специальное меню создания ‘Union’. Таким образом файлы будут автоматически добавлены в Интерфейс плагина. Добавленные в интерфейс файлы могут быть скомпилированы в мультиплатформенном режиме (см файлы headers.h & sources.h).
  

  

  
  
  
  В интерфейсные файлы не обязательно включать заголовочные файлы, а вносить изменения следует в блок GOTHIC_ENGINE. Имя пространства имен будет подобрано автоматически в зависимости от выбранных Вами платформ для компиляции.
  

  

  
  
  
  Для включения заголовочный файлов рекомендуется использовать файл interface.cpp сразу после включения UnionAfx.h. Добавленные сюда включения будут распространяться на все файлы интерфейса.
  

  
  
  3. Сборка проекта и запуск
  
  Спойлер

  Выберите платформу, под которую следует скомпилировать плагин. При выборе MP (multiplatform) соберется совместимая с 4 движками библиотека: Gothic 1, Gothic Sequel, Gothic 2, Gothic 2 NoTR.
  

  

  
  
  
  Положите готовый DLL плагин в папку System\Autorun или VDF:[любая папка]\Autorun для автоматического запуска плагина (другие варианты подключения см в теме Union).
• 
  Getting started with the Union SDK
  1. Installation
  
  Спойлер

  Via the Resource Manager or standalone installer, install the Union plugin template, as well as the accompanying SDK tools.
  

  

  
  
  In Visual Studio, in the project creation menu, find the Union plugin template.
  

  

  
  
  
  In the project properties, select the Platform Toolkit that suits you.
  

  
  
  2. Workspace
  
  Спойлер

  Add new source code files to the project through the special 'Union' creation menu. Thus, the files will be automatically added to the Plugin Interface. Files added to the interface can be compiled in multi-platform mode (see headers.h & sources.h files).
  

  

  
  
  
  It is not necessary to include header files in interface files, but changes should be made in the GOTHIC_ENGINE block. The namespace name will be picked up automatically depending on the platforms you have chosen for compilation.
  

  

  
  
  
  To include header files, it is recommended to use the interface.cpp file immediately after including UnionAfx.h. Inclusions added here will apply to all interface files.
  

  
  
  3. Building the project and running
  
  Спойлер

  Select the platform for which you want to compile the plugin. When choosing MP (multiplatform), a library compatible with 4 engines will be built: Gothic 1, Gothic Sequel, Gothic 2, Gothic 2 NoTR.
  

  

  
  
  
  Put the DLL plugin in the System\Autorun or VDF:[any folder]\Autorun folder to automatically launch the plugin (for other options, see the topic Union).

 

[Gratt]

Русский English

• 
  Инструментарий
  1. Основные события движка
  
  Спойлер

  В файле Plugin.cpp находятся функции, вызываемые автоматически в конкретные игровые события. Эти события можно определить исходя из названий функций. Порядок вызова некоторых функций описан в комментарии внизу файла. Вызов происходит благодаря объекту CApplication, вызывающему стандартные функции одновременно для всех плагинов.
  
  2. Добавление методов в игровые классы
  
  Спойлер

  Для добавления методов или переменных во все 4 движка в одно действие используйте каталог UserAPI. Найдите необходимый класс по фильтру. Добавленные элементы будут расценены intellisense как ошибка, но это лишь недочет технологии. Реализовать элементы можно в любом удобном месте программы.
  

  

  

  
  
  В силу особенностей классов, Вы можете добавлять только НЕвиртуальные методы, статические функции и статические переменные. Все остальное может нарушить размерность класса и виртуальные таблицы.
  
  3. Перехват функций и методов
  
  Спойлер

  Для перехвата используйте слово HOOK + AS (средства MS Detours) или HOOK + PATCH (изменение вызова путем патчинга вызывающей инструкции). Для вызова оригинальной функции объект хука может быть использован в качестве указателя на функцию. Для вызова метода класса потребуется привести указатель к виду функции-члена (например this->*Hookname), либо для упрощения читаемости используйте макрос THISCALL как в примере ниже.
  

  

  
  
  - Для правильного перехвата необходимо, чтобы сигнатура перехватывающей функции была совместима с сигнатурой перехватываемой. В случае неправильного перехвата движок может потерпеть аварию. Для предотвращения подобных ситуаций Union при старте игры укажет на допущенную в перехвате ошибку и потребует ее устранить.
  
  - При перехвате двумя или более плагинами одной и той же функции, вызовы будут поставлены в очередь. Таким образом несколько плагинов одновременно могут получать доступ к выполнению общих процедур без нарушения работы программы.
  
  - В качестве перехватываемой функции можно указывать как имя функции, так и ее адрес.
  
  - Плюсы и минусы способов перехвата:
  Выбрать метод перехвата довольно просто. Вначале следует попробовать метод PATCH как абсолютно совместимый тип с любыми другими расширениями. Однако PATCH не всегда способен распознать адрес функции в байткоде, поскольку тот может быть задан неявно. Тогда в консоль (SystemPack.ini -> ShowDebugWindow) будет показано сообщение с ошибкой перехвата. Такие случае очень редки, но если Вам не повезет, то следует поменять метод хука на AS.
  

  	AS​	PATCH​
  Гарантия, что функция 100% будет перехвачена	Да​	Нет, если адрес вызова передается неявно​
  Гарантия, что такой хук прекрасно уживется с другими расширителями и патчами	Нет​	Да​
  Области действия хука	Весь процесс​	Модуль Gothic.exe​

  
  С обновлением SDK появились 2 вариации хуков: HOOK + AS_IF и HOOK + PATCH_IF. Третий аргумент в этой конструкции может служить условием, определяющим, будет ли производиться перехват. Если третий аргумент будет False, то можно произвести отложенный хук, если для неактивного объекта вызвать метод Commit.
• 
  Tools
  1. Main engine events
  
  Спойлер

  The Plugin.cpp file contains functions that are called automatically in specific game events. These events can be identified based on the function names. The order of calling some functions is described in the comment at the bottom of the file. The call is made thanks to the CApplication object, which calls standard functions simultaneously for all plugins.
  
  2. Adding Methods to the Game Class
  
  Спойлер

  To add methods or variables to all 4 engines in one step, use the UserAPI directory. Find the required class by filter. The added elements will be regarded by intellisense as a bug, but this is just a technology flaw. You can implement elements in any convenient place in the program.
  

  

  

  
  
  Due to the nature of classes, you can only add non-virtual methods, static functions, and static variables. Anything else can break class dimension and virtual tables.
  
  3. Hooking functions and methods
  
  Спойлер

  To hook, use the word HOOK + AS (MS Detours tools) or HOOK + PATCH (change call by patching the calling instruction). To call the original function, the hook object can be used as a function pointer. To call a class method, you need to cast the pointer to the form of a member function (for example, this->*Hookname), or to simplify readability, use the THISCALL macro as in the example below.
  

  

  
  
  - For correct hooking, it is necessary that the signature of the hook function be compatible with the signature of the hooked function. In case of incorrect hook, the engine may crash. To prevent such situations, Union at the start of the game will point out the mistake made in the hook and demand to eliminate it.
  
  - When hooked by two or more plugins of the same function, the calls will be queued. Thus, several plug-ins can simultaneously access the execution of common procedures without disrupting the program.
  
  - Both the name of the function and its address can be specified as a hooked function.
  
  - Pros and cons of hooking methods:
  Choosing a hook method is quite simple. You should first try the PATCH method as a completely compatible type with any other extensions. However, PATCH is not always able to recognize the address of a function in the bytecode, since it can be given implicitly. Then the console (SystemPack.ini -> ShowDebugWindow) will show a message with a hook error. Such cases are very rare, but if you are not lucky, then you should change the hook method to AS.
  

  	AS​	PATCH​
  Guarantee that the function will be 100% hooked	Yes​	No, if the call address is passed implicitly​
  Guarantee that such a hook will get along well with other extenders and patches	No​	Yes​
  Hook scopes	The whole process​	Module Gothic.exe​

  
  With the SDK update, 2 hook variations appeared: HOOK + AS_IF and HOOK + PATCH_IF. The third argument in this construct can serve as a condition that determines whether hook will occur. If the third argument is False, then a delayed hook can be performed by calling the Commit method on an inactive object.