SFTtech · TheJJ · Aug 22, 2020 · Sep 2, 2019 · Sep 4, 2019 · Sep 21, 2019
diff --git a/doc/build_instructions/arch_linux.md b/doc/build_instructions/arch_linux.md
@@ -4,7 +4,7 @@
 
 This command should provide required packages for Arch Linux installation:
 
-`sudo pacman -S --needed eigen python python-jinja python-pillow python-numpy python-pygments cython libepoxy libogg libpng ttf-dejavu freetype2 fontconfig harfbuzz cmake sdl2 sdl2_image opusfile opus python-pylint qt5-declarative qt5-quickcontrols`
+`sudo pacman -S --needed eigen python python-jinja python-pillow python-numpy python-pygments cython libepoxy libogg libpng ttf-dejavu freetype2 fontconfig harfbuzz cmake sdl2 sdl2_image opusfile opus python-pylint python-toml qt5-declarative qt5-quickcontrols`
 
 If you don't have a compiler installed, you can select between these commands to install it:
  - `sudo pacman -S --needed gcc`

diff --git a/doc/build_instructions/debian.md b/doc/build_instructions/debian.md
@@ -1,6 +1,6 @@
 # Prerequisite steps for Debian Sid users
 
  - `sudo apt-get update`
- - `sudo apt-get install cmake cython3 libeigen3-dev libepoxy-dev libfontconfig1-dev libfreetype6-dev libharfbuzz-dev libogg-dev libopus-dev libopusfile-dev libpng-dev libsdl2-dev libsdl2-image-dev python3-dev python3-jinja2 python3-numpy python3-pil python3-pip python3-pygments qml-module-qtquick-controls qtdeclarative5-dev`
+ - `sudo apt-get install cmake cython3 libeigen3-dev libepoxy-dev libfontconfig1-dev libfreetype6-dev libharfbuzz-dev libogg-dev libopus-dev libopusfile-dev libpng-dev libsdl2-dev libsdl2-image-dev python3-dev python3-jinja2 python3-numpy python3-pil python3-pip python3-pygments python3-toml qml-module-qtquick-controls qtdeclarative5-dev`
 
 You will also need [nyan](https://github.com/SFTtech/nyan/blob/master/doc/building.md) and its dependencies.
diff --git a/doc/build_instructions/fedora.md b/doc/build_instructions/fedora.md
@@ -2,6 +2,6 @@
 
 Run the following command:
 
-`sudo dnf install clang cmake eigen3-devel fontconfig-devel gcc-c harfbuzz-devel libepoxy-devel libogg-devel libopusenc-devel libpng-devel opusfile-devel python3-Cython python3-devel python3-jinja2 python3-numpy python3-pillow python3-pygments SDL2-devel SDL2_image-devel++ qt5-qtdeclarative-devel qt5-qtquickcontrols`
+`sudo dnf install clang cmake eigen3-devel fontconfig-devel gcc-c harfbuzz-devel libepoxy-devel libogg-devel libopusenc-devel libpng-devel opusfile-devel python3-Cython python3-devel python3-jinja2 python3-numpy python3-pillow python3-pygments python3-toml SDL2-devel SDL2_image-devel++ qt5-qtdeclarative-devel qt5-qtquickcontrols`
 
 You will also need [nyan](https://github.com/SFTtech/nyan/blob/master/doc/building.md) and its dependencies.
diff --git a/doc/build_instructions/freebsd.md b/doc/build_instructions/freebsd.md
@@ -2,7 +2,7 @@
 
 This command should provide required packages for FreeBSD installation:
 
-`sudo pkg install cmake cython eigen3 harfbuzz opus-tools opusfile png py-numpy py-pillow py-pygments pylint python qt5 sdl2 sdl2_image`
+`sudo pkg install cmake cython eigen3 harfbuzz opus-tools opusfile png py-numpy py-pillow py-pygments py-toml pylint python qt5 sdl2 sdl2_image`
 
 You will also need [nyan](https://github.com/SFTtech/nyan/blob/master/doc/building.md) and its dependencies.
 

diff --git a/doc/build_instructions/opensuse_13.2.md b/doc/build_instructions/opensuse_13.2.md
@@ -6,6 +6,6 @@ if all packages can be installed.
 
 - `zypper addrepo http://download.opensuse.org/repositories/devel:languages:python3/openSUSE_13.2/devel:languages:python3.repo`
 - `zypper refresh`
-- `zypper install --no-recommends cmake doxygen eigen3-devel fontconfig-devel gcc49-c graphviz++ harfbuzz-devel libSDL2-devel libSDL2_image-devel libepoxy-devel libfreetype6 libogg-devel libopus-devel libpng-devel libqt5-qtdeclarative-devel libqt5-qtquickcontrols opusfile-devel pkgconfig python3-Cython python3-Jinja2 python3-Pillow python3-Pygments python3-devel`
+- `zypper install --no-recommends cmake doxygen eigen3-devel fontconfig-devel gcc49-c graphviz++ harfbuzz-devel libSDL2-devel libSDL2_image-devel libepoxy-devel libfreetype6 libogg-devel libopus-devel libpng-devel libqt5-qtdeclarative-devel libqt5-qtquickcontrols opusfile-devel pkgconfig python3-Cython python3-Jinja2 python3-Pillow python3-Pygments python3-toml python3-devel`
 
 You will also need [nyan](https://github.com/SFTtech/nyan/blob/master/doc/building.md) and its dependencies.
diff --git a/doc/build_instructions/opensuse_tumbleweed.md b/doc/build_instructions/opensuse_tumbleweed.md
@@ -1,5 +1,5 @@
 # Prerequisite steps for openSUSE users (openSUSE Tumbleweed)
 
- - `zypper install --no-recommends cmake doxygen eigen3-devel fontconfig-devel gcc-c graphviz++ harfbuzz-devel libSDL2-devel libSDL2_image-devel libepoxy-devel libfreetype6 libogg-devel libopus-devel libpng-devel libqt5-qtdeclarative-devel libqt5-qtquickcontrols opusfile-devel pkgconfig python3-Cython python3-Jinja2 python3-Pillow python3-Pygments python3-devel`
+ - `zypper install --no-recommends cmake doxygen eigen3-devel fontconfig-devel gcc-c graphviz++ harfbuzz-devel libSDL2-devel libSDL2_image-devel libepoxy-devel libfreetype6 libogg-devel libopus-devel libpng-devel libqt5-qtdeclarative-devel libqt5-qtquickcontrols opusfile-devel pkgconfig python3-Cython python3-Jinja2 python3-Pillow python3-Pygments python3-toml python3-devel`
 
 You will also need [nyan](https://github.com/SFTtech/nyan/blob/master/doc/building.md) and its dependencies.
diff --git a/doc/build_instructions/os_x_10.14_mojave.md b/doc/build_instructions/os_x_10.14_mojave.md
@@ -12,7 +12,7 @@ brew install qt5
 brew install -cc=clang llvm@8
 export PATH="/usr/local/opt/llvm@8/bin:$PATH:/usr/local/lib:/usr/local/opt/llvm/bin"
 export PKG_CONFIG_PATH="$PKG_CONFIG_PATH:/usr/local/lib/pkgconfig:/usr/local/lib"
-pip3 install pygments cython numpy pillow pyreadline jinja2
+pip3 install pygments cython numpy pillow pyreadline toml jinja2
 ```
 
 You will also need [nyan](https://github.com/SFTtech/nyan/blob/master/doc/building.md) and its dependencies:

diff --git a/doc/build_instructions/ubuntu.md b/doc/build_instructions/ubuntu.md
@@ -1,6 +1,6 @@
 # Prerequisite steps for Ubuntu users (Ubuntu 18.04)
 
  - `sudo apt-get update`
- - `sudo apt-get install cmake cython3 libeigen3-dev libepoxy-dev libfontconfig1-dev libfreetype6-dev libharfbuzz-dev libogg-dev libopus-dev libopusfile-dev libpng-dev libsdl2-dev libsdl2-image-dev python3-dev python3-jinja2 python3-numpy python3-pil python3-pip python3-pygments qml-module-qtquick-controls qtdeclarative5-dev`
+ - `sudo apt-get install cmake cython3 libeigen3-dev libepoxy-dev libfontconfig1-dev libfreetype6-dev libharfbuzz-dev libogg-dev libopus-dev libopusfile-dev libpng-dev libsdl2-dev libsdl2-image-dev python3-dev python3-jinja2 python3-numpy python3-pil python3-pip python3-pygments python3-toml qml-module-qtquick-controls qtdeclarative5-dev`
 
 You will also need [nyan](https://github.com/SFTtech/nyan/blob/master/doc/building.md) and its dependencies.
diff --git a/doc/building.md b/doc/building.md
@@ -33,6 +33,7 @@ Dependency list:
     C     cmake >=3.16
       A   numpy
       A   python imaging library (PIL) -> pillow
+     RA   toml
     CR    opengl >=3.3
     CR    libepoxy
     CR    libpng

diff --git a/openage/convert/__init__.pxd → doc/code/converter/README.md b/openage/convert/__init__.pxd → doc/code/converter/README.md
diff --git a/doc/code/converter/architecture_overview.md b/doc/code/converter/architecture_overview.md
@@ -0,0 +1,59 @@
+# Converter Architecture Overview
+
+This document describes the code architecture of the openage converter module.
+
+## Design Principles
+
+Our converter uses hierarchical multi-layered object-oriented code principles similar to those found in
+[Domain-Driven Design](https://en.wikipedia.org/wiki/Domain-driven_design) and [WAM](http://wam-ansatz.de/).
+The main focus of using these principles was to provide **readability** and **maintainability** as well
+as enabling us to quickly integrate extensions that support other games and game versions than the original
+Age of Empires 2 release.
+
+A hierarchical structure is achieved by designing objects as part of one of the 5 domains described below.
+Every domain defines a category of complexity. The idea is that every object can only access functionality
+from domains with the same or lower complexity. For example, an object for data storage should not access
+the methods that drive the main conversion process. The resulting code will thus not evolve into a spaghetti
+mess.
+
+### Value Object
+
+Value objects are used to store primitive data or as definition of how to read primitive data from files.
+In the converter, the parsers utilize these objects to extract attributes from the original Genie Engine
+file formats. Extracted attributes are also saved as value objects.
+
+Value objects are treated as *immutable*. Operations on the objects's values will therefore always return
+a new object instance with the result and leave the original values as-is.
+
+### Entity Object
+
+Entity objects are used for structures that have a defined identity. An example for such a structure would
+be one `Unit` object from AoE2 or a `GameEntity` instance from the openage API. Entity objects are mutable
+and can have any number of attributes assigned to them. In the converter, they are used to model the
+more complex structures from Genie games such as units, civilizations and techs. The transition to the nyan
+API objects is also done utilizing etntity objects.
+
+### Service
+
+Services are interfaces for requesting or passing collections of entity objects and value objects from/to
+a processor or tool. It is also used to communicate with external interfaces such as included libraries
+or Python packages. A services main job is to translate the data it receives/forwards into a usable format.
+Examples for services are internal name lookup service for mapping unit IDs to nyan object names as well as
+the nyan file and graphics exporters.
+
+### Processor
+
+Processors operate on a given dataset consisting of multiple entity objects to produce a result. For the
+converter, the input dataset is the data read in from Genie file formats, while the result are modpacks
+for openage. Processors can be split into several subprocessor modules for which the same hierarchical
+structure applies. A subprocessor can never access functions from a parent processor, but use any other
+(sub-)processor or entity object/value object.
+
+openage conversion processor are not instanced and implement most of their functions with the `@staticmethod`
+decorator. The reason for this is to allow conversion processors for game expansions cross-reference
+processor functions of their base game and thus reduce code redundancy.
+
+### Tool
+
+Tools are used to encapsulate processor with a user interface (GUI, TUI or CLI), pass user input to processors
+and start the conversion process.