Gothic Mod Build Tool

A simple tool designed to help in testing and building Gothic and Gothic 2 Night of the Raven mods.

Latest GitHub release License Status Uptime Downloads of Github Releases Join the Discord chat Join the Gitter chat

This project was developed primarily for the purpose of assisting the SoulFire team with the development of The Chronicles of Myrtana.

Tool available in English , Polish and Slovak .

Table of Contents

How does it work?

Idea

Let’s start with some background: the Gothic Mod Build Tool is kind of a breakthrough in Gothic modding, because it is one of the few successful attempts to create a build system which fully automates the process that was previously done manually, every modder had to manually compile assets like textures, meshes and animations and send them to their co-modders. Now, working with version control systems is possible, because each modder has the same version of assets at the same time and at any time can launch the game without need to build a .mod and not run into errors or discrepancies due to a lack of or mismatching assets.

This tool serves two very important purposes, to merge and to compile everything. It uses external tool for updating dialogs subtitles but also launches the Gothic game executable and compiles assets like 3D models and animations ingame with appropriate game settings.

Modes

There are 4 modes of use:

Speed

On a mid-range PC with an HDD, a no sounds build of a huge addon The Chronicles of Myrtana with around 300 MB of worlds, 800 MB of textures, 150 MB of animations and 3D models, takes about 9 - 10 minutes. Similar time with a full test (subtract about a half minute of packing the .mod).

Status

The most important features of the tool are finalized. Currently around 30 modders in SoulFire team are using this tool everyday and various problems are being reported and fixed on ongoing basis.

Milestone for 1.0 version is set to January 1, 2020.

Download

Latest stable release Latest unstable release Unstable development (dev branch)
GitHub release GitHub (pre-)release Build status (dev)

Installation & Requirements

After installation, you can run the Gothic copy ONLY via GMBT. Of course, you can use eg. Spacer, but you have to complete a full test before (the scripts have to be compiled because Spacer needs eg. GOTHIC.DAT and CAMERA.DAT).

Next you have to do configuration and run the tool with the command you want (usage guide).

Configuration

You have to configure a YAML config:

Example

Below is an example files structure and configuration used in The Chronicles of Myrtana project. Also, the same structure you can see in the example project.

Our developers have to clone modification repository to _Work directory, so their local repository is located in _Work/TheChroniclesOfMyrtana. We have a complex structure for our files. There are four directories:

We have got this config in root of the local repository (_Work/TheChroniclesOfMyrtana/.gmbt.yml).

projectName: The Chronicles of Myrtana

gothicRoot: ..\..

modFiles:
  assets:
    - mdk
    - mdk-overrides
    - thirdparty
    - mod

  defaultWorld: KM_WORLD.ZEN

modVdf:
  output:  ..\..\Data\ModVDF\KM.mod
  comment: Gothic 2 - The Chronicles of Myrtana (%%D)%%N(C) 2018 SoulFire

  exclude:
    - _work\Data\Worlds\KM_SUBZENS\*

gothicIniOverrides:
  - 'GAME.playLogoVideos' : '0'
  - 'SKY_OUTDOOR.zSkyDome' : '1'

As you can see, there are only relative paths because this file is in our remote Git repository and every collaborator does not have to configure everything by themselves. And this is the main idea of this tool, to enable easy collaboration in version control systems and large teams.

Usage

At this moment the only way to use the tool is command line interface. GUI application is planned, but below you can find simple examples of Windows Batch files.

Common parameters

Parameter Description Default value
-L <en|pl|sk>, --lang=<en|pl|sk> Set language of console output. Available: English (en), Polish (pl) and Slovak (sk). Control Panel -> Regional Settings
--help Print short descriptions of parameters. N/A
-V <level>, --verbosity=<level> Set verbosity level of console output. Levels: quiet|minimal|normal|detailed|diagnostic. normal

Common parameters (test & spacer & build & compile & pack)

Parameter Description Default value
-C <path>, --config=<path> Path of a config file. </br> Guide how to configure this file is here. .gmbt.yml in working directory

Common parameters (test & spacer & build & compile)

Parameter Description Default value
--zspy=<none|low|medium|high> Level of zSpy logging. none
--zspy-filter=<all|fatal|fault|warning|information> Filter level of zSpy messages all

Common parameters (test & build)

Parameter Description Default value
--noupdatesubtitles Do not update (convert to OU.csl) of dialogues subtitles. N/A
--show-duplicated-subtitles Print duplicated subtitles. N/A
--additional-gothic-parameters Additional Gothic parameters, eg. --additional-gothic-parameters=-nomenu -zwindow N/A

Common parameters (test & spacer)

Parameter Description Default value
--noaudio Run game/Spacer without any audio. N/A

Common parameters (test & compile)

Parameter Description Default value
-F, --full Full test/compilation mode. Information about modes is here. N/A
--merge=<none|all|scripts|worlds|sounds> Merge option.
Enter eg. scripts if you just want to debug scripts and do not want to copy all assets every time. Also, nice option to use is scripts,worlds if you want to debug some changes only related to scripts and worlds.
all
-R, --reinstall Reinstall before start. N/A

Common parameters (build & pack)

Parameter Description Default value
-O <file>, --output=<file> Path of VDF volume (.mod) output. Set in config file
--nopacksounds Do not to pack sounds (WAVs) to mod package. N/A
--comment Set or override comment of VDF. Set in config file

Verb commands

test

Starts test.

Parameter Description Default value
-W <zen>, --world=<zen> Run game in a specific world. Set in config file
--windowed Run game in window. N/A
--ingametime=<hh:mm> Ingame time.
Syntax: hour:minute, eg. 15:59.
N/A
--nodx11 If D3D11-Renderer for Gothic is installed, this command allows you to temporarily disable this wrapper. N/A
--nomenu Run game without menu showing (starts a new game immediately). N/A
-D, --devmode Dev mode of game (marvin mode). N/A

build

Starts a .mod build.

compile

Starts compilation.

pack

Packs a .mod volume.

spacer

Starts Spacer.

Parameter Description Default value
--maxfps Maximum framerate. N/A

update

Updates the tool.

Parameter Description
-F, --force Download and update even if it is up to date.
--no-confirm Do not ask for download.

Examples

Example Batch scripts are also in example project.

Below are some examples used developing The Chronicles of Myrtana project:

Example project

There is an example project which uses this tool. There are some assets from World of Gothic DE Modderdatenbank — just for the test. That repository is very nice sandbox which allows you to get acquainted with the tool. The repository has the same structure of files as in example configuration.

Advanced usage

Hooks

Hooks are actions that can be set in config file to trigger actions at certain points in the tool execution.

Modes

Types

Events

Hooks have to be set in config file. Example:

hooks: 
    common: 
        post:
            assetsMerge: 
                - "tools/script.bat"
                - "tools/script1.bat"
    test: 
        post:
            subtitlesUpdate: 
                - "tools/script2.bat"
    quickTest: 
        pre:
            assetsMerge: 
                - "tools/script3.bat"

To better understand the entire process of tool execution, you should look at the diagram:

Predefined options

Predefined options is something like templates for command line parameters.

You can set predefined options sets in config file:

predefined:
  - "world": "--world=WORLD.ZEN"
  - "anotherworld": "--world=WORLD2.ZEN"

and then, instead of calling gmbt test --world=WORLD2.ZEN, you can type gmbt test anotherworld.

License

MIT License

Copyright (c) 2019 Szymon 'Szmyk' Zak <szymonszmykzak@gmail.com> and contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Built with

Licenses and disclaimers are in the ThirdPartyNotices.md file.

Used software

Licenses and disclaimers are in the tools directory.

Acknowledgments

Big thanks to:

Contributing / issues / contact