szapp / ninja

Extension framework for the video game series Gothic to allow true modular modifications

This repository contains the source code of the Ninja extension for the Gothic game series.

If you are interested in developing patches with Ninja, please follow the instructions in the relevant chapters of the documentation and get started with the official patch template.

About

Ninja is supported by the games Gothic (1.08k_mod), Gothic Sequel (1.12f), Gothic 2 (1.30 fix report version), and Gothic 2 NotR (2.6 fix report version).

For information on Ninja, please visit the documentation.

Usage

To use Ninja, download and install the latest release. If you run into issues or need further instructions, please consult the documentation.

---

Building from Source

There is absolutely no need to assemble Ninja yourself as the latest build is always available for download.

Nevertheless, if you wish to do so anyway, not all resources necessary for building are supplied in this repository and you'll not be able to successfully build it. The purpose of this repository is merely to provide insight into the source code. The additional resources may be provided upon request.

Requirements

Because of linking a Windows DLL, assembling this project is no longer possible under *nix but is exclusive to Windows. (All *nix shell scripts have been stripped from this project, but may still be found in the git history.) For linking the final DLL the following libraries are required on your system.

• User32.dll
• Kernel32.dll
• NtDll.dll

For assembling and building, the following software is required.

• NASM (The Netwide Assembler) (2.16.03)
• GoLink (Go Tools for Windows) (1.0.4.5)
• GoRC (Go Tools for Windows) (1.0.3.0)
• NSIS (Nullsoft Scriptable Install System) (3.10)

Additionally, you'll need the following binaries:

• GNU Make (3.81)
• Git for Windows (2.45.1) for various included GNU Win32 tools
• BinUtils (2.28) for objdump
• ducible (1.2.2)

The binaries of the listed software must be added to your PATH environment variable or placed in the root directory.

Some binaries are attempted to be automatically detected at build time and added to the PATH for the duration of building. These include nasm, makensis, grep, date, dd, touch, xxd.

Assembling

Building Ninja consists of a cascade of assembling the core and assembling the DLL wrapper.
First, the core is assembled into binary files. These are then included when assembling the wrapper which is then finally linked into a DLL.

The reason for this compartmentalization is to separate core and wrapper and to avoid slow absolute (eax) jumps within the executed code by injecting it into the executable at fixed addresses to make use of relative jumps to addresses known at time of assembling.

All the steps above are performed simply with

make

Legal

Ninja is free software and released under the MIT License (MIT).

ninja's Issues

Create log file

Since error dialogs seem not to show for everyone (depending on their settings presumably), Ninja should ideally log its actions to a file. Beyond a mere error message, this log file could also provide direct insight into patch incompatibilities.

PermMem handle integration

So far, handles of patch specific objects are not written to disk. In order to allow more versatile patches, PermMem handles of patches should be stored separately for each patch. This requires a lot of work and testing.

3 engines detected this file

virustotal.com
Regarding v2.3+
What's up with that file?

Remove version information from menu

Modifying the version info in the main menu should be removed to not interfere with other patching systems.

Patch specific subdirectories

The instructions on how to design a patch suggest all file names to contain the patch name. The reason for this is to prevent patches from mutually overriding files with same path in the virtual file system.

While being very inconvenient and producing long, inflexible file names, it is also easy to forget and thereby cause hard to spot compatibility issues. Instead suggest patch-specific subdirectories. They will result in unique file paths, but allow for arbitrary file names.

Allow modifications to ignore specific patches

It should be fairly easy to read another INI entry from the mod-file (e.g. GothicGame.ini) containing space separated names of patches to ignore (due to incompatibility).

Unified Ninja for G1 and G2

The sought file paths can be extended by "_G1" and "_G2" postfixes to allow unified patches for both G1 and G2. This would remove the need for separate patches, simplify maintaining them and actually encourage and make easier to create patches for both.

Exchange wrapper

The current DLL is not linked directly by the executable.

Automate build

Automate the building of machine code from assembly, e.g. by using NASM or github/asmjit/asmtk.

Supply mod name to Daedalus

Without the need for Ikarus, the mod name should be provided to the Daedalus scripts in form of a Daedalus string constant, much like the other Ninja helper symbols.

Incorporate OU

The only thing missing from the range of Ninja's possibilities is the ability to inject output units. Although the motivation would be questionable, it might be worth looking at. At the very least for completion.

Add Buff_FadeOut to preserved symbols

LeGo introduces the user constant Buff_FadeOut with version 2.6.0. This symbol should not be overwritten by a patch and should be added to the preserved symbol list.

Apply patches in order of their timestamps

So far, individual patches were found by matching a file name pattern. Matched files, i.e. found patches, were then applied in the "arbitrary" order they were provided in by the findnext loop. To allow patches to build on or patch each other they should be applied in a second loop after they were ordered by their timestamps.

Add infos to the info manager on loading

Infos (oCInfo) are unarchived from the gamesave. Thus any script injections are ignored when loading. (New game not affected.)

The last step to fully allowing new output units is to hook the end of the oCInfoManager unarchiver and add the respective infos to the sorted list. A local prototype to this solution already works.

Technically this is necessary for

• oCInfoManager
• oCMission deprecated
• oCLogManager not necessary

Fallback to SRC files without postfix

Recent changes require a "_G1" or "_G2" postfix to all SRC and animation files to indicate their affiliation. This is useful for creating unified patches. However, for larger projects this results in a lot of duplicate/identical files, if the SRC/animation files do not differ between both games.

An improvement would be to fallback to SRC and animation files without neither postfix that are parsed only if no matching postfixed file is found previously. An exception should be the content ninja to ensure compatibility at all times.

Infer working directory

Depending on the loader, the working directory might differ resulting in error when not finding relative paths.

Text currently printed with PrintS_Ext sometimes is stuck on reloading the game

Hi, thanks for your work and recent updates!

I recently noticed that in my whacky plugin, if I reload the game shortly after I printed a text notification to the screen using PrintS_Ext, the message gets permanently stuck on the screen until I restart the game. I've managed to reproduce this in both Gothic 1 and Gothic 2 NotR, both with Ninja and the latest Union installed (via Steam workshop).

I tried downgrading to Ninja 2.7.12 - couldn't reproduce the issue then.
Did another test, snatched the original Lego's PrintS_Ext implementation into my project, on each call saved a raw pointer to zCTextView object saved in gCPrintS::tv_Text. Then, on the next init run after reloading, I manually called zCTextView_Delete with each saved ptr (which should have been done as part of _PM_Reset() cleanup as far as I understood Lego source code). I couldn't reproduce the issue then neither so seems like something may be off with PermMem handles cleanup?

I made a minimum repro-plugin here https://github.com/Avenire/ninjapermmemhandleleak
Steps to reproduce is just smash V button 15+ times & quickly reload the game while text is still on the screen.
Also, recorded my reproduction attempts, looks like the bug was introduced with 2.8.13:
Ninja 2.7.12 - no bug: https://youtu.be/bOEN2DFBoh4
Ninja 2.8.13 - bugged: https://youtu.be/tOt4FWtrw_M
Ninja 2.9.14 - bugged: https://youtu.be/a3gmqPQSrec

Version check for LeGo

While Ninja is completely independent from LeGo and the use thereof, it is a common source for incompatibility with both mods and other patches. Ninja could check for the symbol LeGo_Version and if it exists make sure it is of a predefined, Ninja-specific version.

Safety check on loaded scripts

To prevent an incomprehensible error message, there should be a safety check on whether the script data (VDF) was in fact loaded.

Rename _while and _repeat

Rename the symbols _while and _repeat to while and repeat, respectively, if they exist.

if symbol_exists("_while") and !symbol_exists("while")
    sym = get_symbol("_while")
    sym.name = "while"
if symbol_exists("_repeat") and !symbol_exists("repeat")
    sym = get_symbol("_repeat")
    sym.name = "repeat"

Add more divider symbols to symbol tables

To differentiate Deadalus symbols not only between mod and patches, it would be nice to pinpoint which patch specifically a symbol belongs to.

This could be achieved by adding a divider symbol (much like NINJA_SYMBOLS_START) for each patch.

An open question is how to name these divider symbols; either with patch name or patch index. Patch name has the obvious advantage to be constructed easily for a patch in question, but the disadvantage that the range to the next or previous divider symbol has to be constructed by complex string retrieval from the NINJA_PATCHES array. This step would be necessary anyway if using patch indices directly for naming the divider symbols.

Investigate access violation on unarchiving (Gothic 1)

Look into removeInvalidNpcs in Gothic 1 in conjunction with oCMobFire objects.

Do not archive transient NPC in spawn queue

The spawn manager ignores the do-not-archive vob-flag of NPC on archiving. Its archive routine needs to be adjusted accordingly to prevent crashes on removing patches that introduce new NPC.

Change divider symbol into instance

To reduce the address space, the divider symbol could be changed to an instance. Setting its content to its symbol index will become superfluous.