\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}.

\begin{figure}
	\centering
	\includegraphics[width=0.5\textwidth]{img/DecoratorDesignPattern.png}
	\caption{Decorator design pattern}
	Source: \autocite{img:Decorator}
	\label{fig:decorator}
\end{figure}

The Extension Objects design pattern (as shown in \cref{fig:extension objects}) could
also be used to structure the game engine. The Extension Objects design pattern allows
to modify an object's propperties/behavior by adding one (or more) Extensions. The
object that is modified, could be the gameObject and the components could be the
Extensions. This is quite the same as the required API. An advantage is, that the client
(which is the scene in our case) can call all kind of different Extension's methods
(depending on the kind of Externsion, e.g. the method render() for the sprite Extension
and the method update() for the script Extension). In other words, the interfaces of the
different Extensions should not be the same. This is way more flexible than the Decorator
design pattern. A disadvantage is that the data and functionality are in the same class
(namely inside the Extion's methods), so it's not sepperated. Another disadvantage is
that the Extension Objects design pattern can be quite slow, because objects are scattered
in memory (and it is very hard to quickly get their memory address)
\autocite{man:ExtensionObjectDesignPattern, man:extionsionObjectsStackOverflow}.

\begin{figure}
	\centering
	\includegraphics[width=0.5\textwidth]{img/ExtensionObjects.jpg}
	\caption{Extension Objects design pattern}
	Source: \autocite{img:extionsionObjects}
	\label{fig:extension objects}
\end{figure}

Another (very popular) design pattern to structure the game engine, is the Entity
Component System (\gls{ecs}) (as shown in \cref{fig:ECS Block Diagram}). 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), which is an advantage.

\begin{figure}
	\centering
	\includegraphics[width=0.5\textwidth]{img/ECSBlockDiagram.png}
	\caption{ECS design pattern}
	Source: \autocite{img:ECSBlockDiagram}
	\label{fig:ECS Block Diagram}
\end{figure}

The \gls{ecs} is normally equipped with a component manager (as shown in
\cref{fig:ECS Component manager}). The component manager keeps track of the entities
(Alien, Player, Target, etc in \cref{fig:ECS Component manager}) and the connected
components (Position, Movement, Render, etc in \cref{fig:ECS Component manager}).
The component manager stores two lists (key value pairs). The key of the first list
is the ID of an entity, and the value of this list are the connected components. The key
of the second list is the component, and the value of this list are the entities that
have this component. These two lists make it possible to very quickly gather components
or entities. This makes the \gls{ecs} very fast, which is of course an advantage.

\begin{figure}
	\centering
	\includegraphics[width=0.5\textwidth]{img/ECSComponentManager.png}
	\caption{ECS Component manager}
	Source: \autocite{img:ECSComponentSystem}
	\label{fig:ECS Component manager}
\end{figure}

Another aspect that makes the \gls{ecs} very fast, is that a system can handle all
components (of the same type) together at once. This is possible because all entities
are independent of each other.

There are many ways of implementing the systems. Some say that each component type has
their own system. This interpretation of the systems does not take the interplay of
different component types, into account. A less restrictive approach is to let different
systems deal with all components they should be concerned with. For instance a Physics
Systems should be aware of Collision Components and Rigidbody Components, as both
probably contain necessary information regarding physics simulation. It's best to see
systems as “closed environments”. That is, they do not take ownership of entities nor
components. They do access them through independent manager objects, which in turn will
take care of the entities and components life-cycle.

Sometimes systems, entities and even components need to cummincate with each other. This
might be very hard because systems, entities and components are more or less independent.
One option is to use an event systems. A system, entity and component can raise an event
and other systems, entities and components can react to that event. This is what makes the
\gls{ecs} a complicated system (disadvantage).

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}

% TODO: this entire section
\section{Audio}

% should audio research be scoped down to SDL2 (if that's what we're going with) or
% standalone libraries only (for modularity?).

The game engine is required to have an audio system with support for playing multiple
audio streams (i.e.~tracks or samples) simultaniously. Since writing a custom live
audio mixing engine is outside the scope of this project, this section compares
various standalone audio engines that could be used in the engine.

% TODO: requirements first!

% REQ ~ is cross-platform
% REQ ~ supports multiple audio formats (TODO: which)
% REQ ~ supports simultanious playback / mixing
% REQ ~ has an open-source license
\begin{table}
	\centering
	\begin{tabular}{llc}
		\toprule
		\textbf{Library} & \textbf{License} & \textbf{API}\\
		\midrule
		miniaudio & MIT-0 & C\\
		YSE & EPL & C++\\
		SoLoud & Zlip/LibPng & C++\\
		\bottomrule
	\end{tabular}
	\caption{Audio engine library comparison}
	\label{tab:audio-engines}
\end{table}
% TODO: ref https://miniaud.io/
% TODO: ref https://www.attr-x.net/yse/

Not considered further:
\begin{description}
	\item[FMOD] is proprietary
	\item[PortAudio] requires manual mixing
\end{description}

\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}