\documentclass{projdoc}
\input{meta.tex}

\title{Research document}

\begin{document}
\tablestables
\newpage

\section{Introduction}

\section{Game engine}

\subsection{Introduction}

To build a game engine, it must first be understood how it operates. The
functionalities it requires and how these functionalities work together must be
determined. In this section, the general functioning of a game engine and the
different parts required are described.

\subsection{Findings}

A game engine is not the game itself but a platform with which games are built. It
should provide the functionalities with which the game is constructed. The purpose of
a game engine is not to create data out of nothing. Instead, data is read, and the
correlating features and effects are generated. However, the engine is also used to
create these files, referred to as ``assets.'' The game engine must be able to accept
a certain format of these assets---whether levels, sprites, or textures---and convert
them into usable data.

\subsubsection{Layers}

A game engine is composed of multiple layers, each with its own functions. These
layers are divided into the following categories:\noparbreak
\begin{description}
	\item[Resource manager] Responsible for what happens when the engine is launched,
		including loading data formats.
	\item[Application] Manages the run loop, time, code execution, and events
		(e.g.~input events).
	\item[Window/\glspl{hid}] Handles input and events.
	\item[Renderer] Responsible for drawing the necessary objects on the screen,
		usually once per frame.
	\item[Debugging support] Provides testing for the engine, such as logging or
		performance profiling.
	\item[Scripting layer] Runs scripts, such as Lua or Python.
	\item[Memory systems] Handles and monitors memory usage.
	\item[Physics] Adds specific physics to objects.
	\item[Audio] Processes audio.
	\item[AI] Provides artificial inteligent behavior.
\end{description}

\subsubsection{Structures}

The above mentioned layers should be structured, somehow. One of the requirements is
that the game engine's API uses a so-called gameObject (with one or more
component(s)). The gameObject is described in more detail at
\cref{sec:Gameobjects/components}.

There are multiple structures that could be used to structure a game engine. It's of
course possible to use inheritance. A major disadvantages of inheritance is that it's
not flexible. However, the provided class diagram of the game engine's API already
specifies that composition should be used (in stead of inheritance). So, let's take a
look at structures that use composition.

The Decorator design pattern (as shown in \cref{fig:decorator}) could be used to
structure the game engine. A gameObject's propperties/behavior is determined by one
(or more) components. The Decorator design pattern allows to modify an object's
propperties/behavior by adding one (or more) Decorators. The object that is modified,
could be the gameObject and the components could be the Decorators. This is not
exactly the same as the required API, but it's very close. A major disadvantage of
such Decorator design pattern, is that the interface of all components should be the
same (they should share the same methods), because the client (which is the scene in
our case) can only call/reach the components through the interface. This would
require very general methods (at the interface), which might make the programming
harder \autocite{man:DecoratorDesignPattern,man:Decorator}.

\begin{figure}
	\centering
	\includepumldiag{img/decorator-design-pattern.puml}
	\caption{Decorator design pattern}
	Source: \autocite{img:Decorator}
	\label{fig:decorator}
\end{figure}

TODO: Add Extension Objects design pattern (if this is applicable)!

Another (very popular) design pattern to structure the game engine, is the Entity
Component System (\gls{ecs}). The \gls{ecs} is made out of three main subsystems,
namely entities, components and systems. Entities are just IDs. An entity is made out
of a gameObject and one (or more) components. Components are the classes that hold
the data. The components determine what kind of entity it is (e.g. a sprite, audio,
and so on). Systems take care of the behavior of the entities. Systems mainly read
and write the enity's components data. The \gls{ecs} clearly distinguishes the data
(components) from the functionality (systems).

% TODO: Continue this explanation (also add some diagrams to make the ECS more clear)!

There are many C/C++ libraries available, completely dedicated to \gls{ecs}. The most
popular libraries are shown in \cref{tab:popularECSLibraries}. The popularity is
based on the amount of stars on GitHub.

\begin{table}
	\centering
	\begin{tabular}{ll@{\qquad}lr}
		\toprule
		\textbf{Name} & \textbf{Short Description} & \textbf{Stars} & \textbf{License}\\
		\midrule
		EnTT & Fast and reliable entity-component system & 10k & MIT\\
		Flecs & A Multithreaded Entity Component System & 6.3k & MIT\\
		EntityX & Fast, type-safe C++ entity component system & 2.2k & MIT\\
		\bottomrule
	\end{tabular}
	\caption{Popular \gls{ecs} libraries}
	Source: \autocite{github:awesome-ecs}
	\label{tab:popularECSLibraries}
\end{table}

It is, of course, not necessary to use a library to implement an \gls{ecs}
architecture. However, it seems very hard to achieve the same performance as a
library \autocite{github:ecsfaq}.

\subsection{Conclusion}

\section{Third-party Tools}

\subsection{Introduction}

Developing a game engine from scratch requires a significant amount of time, as many
different features are necessary. Fortunately, some of these features have already
been developed and can be reused in the form of frameworks and third-party
tools/libraries. The decision to use third-party libraries, and the selection of
which ones to use, directly influences the development process of the game engine. In
this section, several third-party frameworks and tools available for use are
described.

\subsection{Findings}

\subsubsection{Media Frameworks}

A game engine must have the ability to handle user input, render graphics, and
process audio. Several large frameworks are available that provide these features and
are already widely used by other game engines. The two most popular and
best-supported options are \gls{sdl2} and \gls{sfml}.

\paragraph{SDL2}

% TODO: ref?sdl2
According to its official website, \gls{sdl2} is \emph{``a cross-platform development
library designed to provide low-level access to audio, keyboard, mouse, joystick, and
graphics hardware via \gls{opengl} and \gls{d3d}. It is used by video playback
software, emulators, and popular games, including Valve's award-winning catalog and
many Humble Bundle games.''} \gls{sdl2} is written in the C programming language, and
therefore, structs and functions are used instead of objects and methods.

\begin{comparison}
	\pro{Controller support is provided.}
	\pro{2D and 3D rendering are supported.}
	\pro{Broad multiplatform support is offered, including older consoles such as the
	Wii.}
	\pro{Low-level control is available.}
	\pro{A large community ensures wide usage.}
	\pro{Extended libraries can be used to add functionalities, such as SDL\_Mixer for
	sound.}
	\con{A limited built-in 2D renderer is provided.}
	\con{Extended libraries require setup.}
\end{comparison}

\paragraph{SFML}

\gls{sfml} is a simple framework consisting of five modules: audio, graphics,
network, system, and window. This framework, written in C++, was designed to simplify
game development.

\begin{comparison}
	\pro{Object-oriented design is provided since it is written in C++.}
	\pro{A built-in 2D renderer is available for ease of use.}
	\pro{A built-in audio system is included.}
	\pro{Cross-platform support is available for Linux, Windows, and macOS.}
	\pro{Networking capabilities are provided for multiplayer or networked
	applications.}
	\con{The 2D rendering engine may experience performance issues in large-scale
	games.}
	\con{The community is smaller compared to \gls{sdl2}.}
	\con{No native 3D support is provided.}
	\con{Not all image formats are supported.}
\end{comparison}

\subsubsection{Audio}

for audio some options could be: FMOD, Wwise, or iirKlang

\subsection{Conclusion}

\section{Resource manager}

\subsection{Introduction}

\subsection{Findings}

\subsection{Conclusion}

\section{Rendering}

\subsection{Introduction}

\subsection{Findings}

\subsection{Conclusion}

\section{Event manager/game loop}

\subsection{Introduction}

\subsection{Findings}

\subsection{Conclusion}

% TODO: this entire section
\section{Profiling and debugging}

% Which profiling and debugging features are wanted?
% How to provide those profiling and debugging features?
% Can most of the profiling/debugging be handled by external tools?

% Ideas:
% - flame graph
% - watchtable (combine w/ fps/speed control overlay?)
% - debug printing utility functions

\subsection{Introduction}

\subsection{Findings}

\subsubsection{Callgrind}

\begin{comparison}
	\pro{Source code does not need to be modified for profiling}
	\con{Execution speed is severely impacted}
\end{comparison}

\subsection{Conclusion}

\section{Audio}

The game engine is required to have an audio system
\autocite[\ref{req:audio}]{crepe:requirements}. Since writing a custom real-time
audio mixing engine is outside the scope of this project\mref, this section compares
various standalone audio libraries for suitability in the engine.

\Cref{sec:audio:libs} details which libraries were considered,
\cref{sec:audio:benchmark} compares their performance, and
\cref{sec:audio:conclusion} concludes with a recommendation for most performant audio
library.

\subsection{Libraries}
\label{sec:audio:libs}

\Cref{tab:audio:libs} lists the standalone audio engine libraries that fit
\cref{req:audio,req:lib:license}.

\begin{table}
	\centering
	\begin{tabular}{llc}
		\toprule
		\textbf{Library} & \textbf{License} & \textbf{API}\\
		\midrule
		miniaudio \autocite{lib:miniaudio} & MIT-0 & C\\
		YSE \autocite{lib:yse} & EPL & C++\\
		SoLoud \autocite{lib:soloud} & Zlip/LibPng & C++\\
		\bottomrule
	\end{tabular}
	\caption{Audio engine library comparison}
	\label{tab:audio:libs}
\end{table}

Other popular libraries that were researched but are unsuitable for this project
include:\noparbreak
\begin{description}
	\item[FMOD \autocite{lib:fmod}] Is proprietary (violates \cref{req:lib:license})
	\item[PortAudio \autocite{lib:portaudio}] Does not handle mixing
\end{description}

\subsection{Benchmarks}
\label{sec:audio:benchmark}

The same benchmark application was written for each of the libraries listed in
\cref{tab:audio:libs}. The application does the following:\noparbreak
\begin{enumerate}
	\item Load a background track (Ogg Vorbis)
	\item Load three short samples (WAV)
	\item Start the background track
	\item Play each sample sequentially while pausing and resuming the background track
	\item Play all samples simultaniously
	\item Stop all audio and exit
\end{enumerate}

Each benchmark was profiled using \emph{perf} \autocite{tool:perf} and compared based
on total CPU and memory utilization. The results of these benchmarks are listed in
\cref{tab:audio:benchmark}.

\begin{table}
	\centering
	\begin{tabular}{lr}
		\toprule
		\textbf{Library} & \textbf{???}\\
		\midrule
		miniaudio &\\
		YSE &\\
		SoLoud &\\
		\bottomrule
	\end{tabular}
	\caption{Audio engine library benchmark results}
	\label{tab:audio:benchmark}
\end{table}

\subsection{Conclusion}
\label{sec:audio:conclusion}


\section{Physics}

\subsection{Introduction}

\subsection{Findings}

\subsection{Conclusion}

\section{Scripting}

\subsection{Introduction}

\subsection{Findings}

\subsection{Conclusion}

\section{Audio}

\subsection{Introduction}

\subsection{Findings}

\subsection{Conclusion}

\section{Gameobjects/components}
\label{sec:Gameobjects/components}

\subsection{Introduction}

One of the requirements of our customer, is that the game engine's structure is
similar to Unity. The customer has created a class diagram of the game engine's API,
which is (of course) very similar to Unity. One of the most important parts of the
class diagram is a so-called gameObject (with several components). It's needed to
understand the exact meaning/function of these gameObjects, that's why this research
question arose.

\subsection{Findings}

A gameObject is the most important concept in Unity. Every object in a game is a
GameObject, from characters and collectible items to the lights, cameras and special
effects. However, a gameObject itself can't do anything on its own. A gameObject
needs to be given properties before it can become a character, an envirnment, or a
special effect. \autocite{man:unityGameobjects}

A gameObject can be seen as a container for components. Components are the properties
of the gameObject. A few examples of components are sprites, animators, audioSources,
and so on. Multiple (different) components can be assigned to a single gameObject
(e.g.~a sprite and an audioSource).

Since we now know that a gameObject needs components to do something, it's obvious
that there should be a way to add components to a gameObject. Some components
(e.g.~the behaviorScript component) should also be able to reference to its
gameObject.

Each gameObject always has one transform class. The transform class describes the
position, rotation, and scale within the scene. Some component use this information
to e.g. scale a sprite. Other components eddit this information to e.g.~model
gravity. \autocite{man:unityTransformClass}

A gameObject can have one (or multiple) children gameObject(s). All children
gameObjects, of course, also have one transform class. However, the position,
rotation, and scale of this class, is always the same as the child's parent. A child
can not have more than one parent. \autocite{man:unityTransformClass}

\subsection{Conclusion}

\section{AI}

\subsection{Introduction}

\subsection{Findings}

\subsection{Conclusion}

\end{document}