Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 37 additions & 7 deletions docs/zengin/union/index.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,42 @@
# Union
Union is a system to patch and extend Gothic's engine the ZenGin. It allows you to load `.dll` files - ZenGin extensions created using the Gothic/Union SDK and `.patch` files - files designed to patch the game's executable. The Union installer also contains the SystemPack a collection of bug fixes and engine edits that improve performance.

## [Plug-ins](plugins/index.md)
Union plugins are shipped in the form of a `.dll` library. This library contains the compiled C++ code with the Union SDK and an embedded `.patch` file.
<div class="grid cards" markdown>

## [Union SDK](sdk/index.md) & Gothic API
Union software development kit is a collection of tools and the Gothic API that allow you to create Union plugins and alter the engine's behavior.
Gothic API is a set of 4 interfaces (each for one different ZenGin version) that allow you to interface with the engine, access the engine objects, change their behavior and introduce new classes and functionality.
- :octicons-plug-16:{ .lg .middle } __Plugins__

## [PATCH file format](patch.md)
The `.patch` file contains one or more small programs that are designed to change the engine code (game executable). This is usually done to fix bugs. Union plug-ins contain an embedded `.patch` file and this file usually contains changes to the binary necessary for the proper function of the plug-in.
---

Union plugins are shipped in the form of a `.dll` library. This library contains the compiled C++ code that interfaces with game engine.

[:octicons-arrow-right-24: Read more](plugins/index.md)


- :material-code-block-tags:{ .lg .middle } __Union SDK__

---

Create plugins with Union SDK, a community-made software development kit for ZenGin.

[:octicons-arrow-right-24: Read more](sdk/index.md)

- :material-tools:{ .lg .middle } __PATCH file format__

---

The `.patch` file contains one or more small programs that are designed to change the engine code (game executable). This is usually done to fix bugs.

[:octicons-arrow-right-24: Read more](patch.md)



- :material-download:{ .lg .middle } __Install Union__

---

Install the latest Union and enjoy the bug-free gameplay.

[:octicons-arrow-right-24: Download installer](https://drive.google.com/drive/u/0/folders/1SMY3PuSZnZuAlov8GKKXtv5lny-jZl-a)
Comment thread
kamilkrzyskow marked this conversation as resolved.


</div>
18 changes: 13 additions & 5 deletions docs/zengin/union/patch.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,15 @@
# Patch files
`.patch` files are scripts that are used to change memory values or committing some actions when starting the engine. Files patches are launched from any directories monitored by the file system (System, Saves, _Work and any others at the request of the engine). The launch is performed both from physical directories and from VDF & MOD. If physical and virtual directories contain identical patches with identical paths, physical copies will have read priority.
`.patch` files are scripts that are used to patch game executable. They are especially useful when fixing engine bugs.

!!! Info
An additional [patch name] .MAP file can be created. This happens when the patch file has at least one patch marked 'static' (see the description of the patch format for more details). This file allows you to immediately download all previously made changes to process memory, skipping re-parsing of static blocks. By default, the file cannot be seen through standard files explorer. To make the file hidden, but visible, set the value SystemPack.ini -> ShowHiddenFiles = true.

[Description of the patch format](https://worldofplayers.ru/threads/42178/)
## Loading
Patches could be launched from any directory monitored by the file system (`System`, `Saves`, `_work` etc.). The launch is performed both from physical directories and from VDF/MOD volumes. If physical and virtual directories contain identical patches with identical paths, physical copies will have read priority.

## Documentation
The description of the patch format could be found [here](https://worldofplayers.ru/threads/42178/).

## Community patches
Following repositories contain collections of various patches:

- [:fontawesome-brands-github: Gothic-Modding-Community/zengin-patches](https://github.com/Gothic-Modding-Community/zengin-patches)
- [:fontawesome-brands-github: UnresolvedExternal/Gothic-Patches](https://github.com/UnresolvedExternal/Gothic-Patches)
- [:fontawesome-brands-github: VaanaCZ/gothic-engine-patches](https://github.com/VaanaCZ/gothic-engine-patches)
11 changes: 8 additions & 3 deletions docs/zengin/union/plugins/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: Plugins
---
# Union Plugins
Plugins are libraries dynamically loaded via Union. They can be used to modify the behavior of the game, add new features, and fix bugs. Plugins are written in C++ and compiled into DLL files. The [Union SDK](../sdk/index.md) and Gothic API provide a set of functions and classes that can be used to create plugins.
Plugins are libraries dynamically loaded via Union. They can be used to modify the behavior of the game, add new features, and fix bugs. Plugins are written in C++ and compiled into DLL files. The [Union SDK](../sdk/index.md) or [Union Framework](../framework.md) could be used to create plugins.

!!! Warning
The plugin system is also a potential source of errors. If the plugin is written incorrectly, it can cause the game to crash or behave incorrectly. Therefore, when using plugins, you should be careful and follow the instructions of the plugin authors.
Expand All @@ -11,16 +11,21 @@ Plugins are libraries dynamically loaded via Union. They can be used to modify t
Loading can be done both Physically and from VDF or MOD volumes. There are three options for loading libraries:

### Systempack.ini
The classic way is to specify the list of library names in SystemPack.ini -> PluginList separated by commas. Also through this parameter you can control the priority of launching plugins:
The classic way is to specify the list of library names in `SystemPack.ini` PluginList separated by commas. Also through this parameter you can control the priority of launching plugins:

1. If you specify two asterisks (plugin.dll**) at the end of the library name, then it will be loaded earlier than the Virtual file system. But in this case it cannot be loaded from VDF or MOD volume.

2. If you specify one asterisk (plugin.dll*) at the end of the library name, then it will be launched immediately after the Virtual file system. At this stage the library can be loaded from VDF or MOD volume.

3. If the name of the library is specified without changes (plugin.dll), then it will be loaded simultaneously with the game. At this stage libraries have the ability to use global instances of Gothic classes.

```ini
[PLUGINS]
PluginList = First.dll**, Second.dll*, Third.dll
```

### Autorun
If the library is located in the Physical Directory `System/Autorun` or in the Virtual Directory `*/Autorun`, then the library will be loaded along with the engine, as in step 1.III. In current versions of Union, the order of loading plugins from this folder is determined by the dependencies of the libraries on each other. This means that if one plugin imports symbols from another, then the Exporting will be loaded first, and then the Importing.
If the library is located in the Physical Directory `System/Autorun` or in the Virtual Directory `*/Autorun`, then the library will be loaded along with the engine, as in step 3 of Systempack.ini. In current versions of Union, the order of loading plugins from this folder is determined by the dependencies of the libraries on each other. This means that if one plugin imports symbols from another, then the Exporting will be loaded first, and then the Importing.

### Patch File
The patch files start automatically. This means that plugins can also run patches along with them. There are two script functions: `LoadLibrary("plugin.dll")` and `LoadPlugins("plugin1.dll", ..., "pluginN.dll")`.
2 changes: 1 addition & 1 deletion docs/zengin/union/plugins/zmultilogue.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# zMultilogue

zMultilogue is a plugin that implements Multi-NPC dialog system for Gothic 1 and Gothic 2 NotR. Its working principle is based on the solution from [AFSP Trialogue package](https://github.com/Bad-Scientists/AF-Script-Packet/blob/main/Standalone-Packages/G12-Trialogue/trialogue.d). The main project goal is to replace Trialog packages based on [Ikarus](https://github.com/Lehona/Ikarus) and [LeGo](https://github.com/Lehona/LeGo/tree/dev) with an union-based plugin.
zMultilogue is a plugin that implements Multi-NPC dialog system for Gothic 1 and Gothic 2 NotR. Its working principle is based on the solution from [AFSP Trialogue package](https://github.com/Bad-Scientists/AF-Script-Packet/blob/main/Standalone-Packages/G12-Trialogue/trialogue.d). The main project goal is to replace Trialog packages based on [Ikarus](../../scripts/extenders/ikarus/index.md) and [LeGo](../../scripts/extenders/lego/index.md) with an union-based plugin.


!!! Info
Expand Down
7 changes: 5 additions & 2 deletions docs/zengin/union/sdk/externals.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@
# Externals
---
title: Externals
---
# Custom externals
Externals are functions defined by the Gothic engine that can be called from scripts. Union SDK provides symbols for pointers to global `zCParser` instances that we can use to interact with the parser and to define a custom external function.

```cpp
Expand All @@ -11,7 +14,7 @@ extern zCParser*& parserMenu;
extern zCParser*& parserMusic;
```

## Creating custom external
## Creating external
To create an external we need to define a function handler and register it in the parser. Before we start, it's good to write down a Daedalus function signature so we can see the return and argument types that will be important later.
```dae
func string AddNumbers(var int FirstArgument, var int SecondArgument, var string ThirdArgument) {}
Expand Down