From 370c72acdb43ddb79583c232af9f91155425fc8d Mon Sep 17 00:00:00 2001
From: Loek Le Blansch <loek@pipeframe.xyz>
Date: Sat, 26 Oct 2024 15:58:11 +0200
Subject: WIP save manager design

---
 design.tex | 45 +++++++++++++++++++++++++++++++++------------
 1 file changed, 33 insertions(+), 12 deletions(-)

(limited to 'design.tex')

diff --git a/design.tex b/design.tex
index 08ea7cc..a3da41c 100644
--- a/design.tex
+++ b/design.tex
@@ -24,15 +24,15 @@ workflows.
 
 \section{Overview}
 
-\subsection{Core}
-
-\subsection{Patterns}
+% TODO: high-level design introduction
+% - which parts of the design are prerequisites (and therefore not designed by us)
+% - why are all parts in the following section arranged in the way they are
 
 \section{Design}
 
-\subsection{Rendering}
+% \subsection{Rendering}
 
-\subsection{Physics}
+% \subsection{Physics}
 
 \subsection{Scripting}
 
@@ -91,10 +91,11 @@ follows:\noparbreak
 contains the following classes:\noparbreak
 \begin{description}
 	\item[Script] This is the script \emph{interface}, and is used by the game
-		programmer to create derived script classes. All methods in this class are
-		declared virtual and have an empty implementation.
+		programmer to create derived script classes. All virtual methods in this class
+		have an empty implementation by default, and are optionally implemented by the
+		game programmer.
 
-		This class' methods are protected by default, and a friend relation to
+		This class' virtual methods are protected by default, and a friend relation to
 		\codeinline{ScriptSystem} is used to ensure only \codeinline{ScriptSystem} is
 		able to call these methods.
 
@@ -103,6 +104,10 @@ contains the following classes:\noparbreak
 		function returns a reference to the \codeinline{BehaviorScript} instance it was
 		called on so it can be chained after the call to
 		\codeinline{GameObject::add_component}.
+
+		\codeinline{Script} also has a reference to its parent
+		\codeinline{BehaviorScript} instance so components can easily be retrieved using
+		the component manager.
 	\item[BehaviorScript]
 		This is the script \emph{component}, and is given as the template parameter to
 		\codeinline{GameObject::add_component}.
@@ -184,13 +189,29 @@ contains the following classes:
 	\label{fig:class-audio-facade}
 \end{figure}
 
-\subsection{Input}
+\subsection{Save manager}
+
+The save manager \gls{api} is designed to give the game programmer an easy to use
+interface for retrieving and storing game-specific data (\cref{req:savemgr}).
+
+Because the engine validation app only stores statistics and highscores, the save
+manager is not required to support loading different save files
+(\cref{req:savemgr:multi-file}), nor storing complicated data types
+(\cref{req:savemgr:types-custom}). The save manager only supports storing simple
+types (\cref{req:savemgr:types-scalar,req:savemgr:types-string}).
 
-\subsection{Physics}
+In order to reduce complexity for the game programmer further, the following
+requirements were also set:\noparbreak
+
+\begin{itemize}
+	\item Prevent data loss in the case of crashes (\cref{req:savemgr:journalling})
+	\item Handle opening/closing/flushing of the underlying file automatically
+		% (\cref{req:savemgr:???})
+\end{itemize}
 
-\section{Tools}
+% \subsection{Input}
 
-\section{Conclusion}
+% \subsection{Physics}
 
 \end{document}
 
-- 
cgit v1.2.3


From 07a919befbdff9d7da8db95a890c2f647396cd23 Mon Sep 17 00:00:00 2001
From: Loek Le Blansch <loek@pipeframe.xyz>
Date: Sun, 27 Oct 2024 19:34:23 +0100
Subject: more WIP design

---
 design.tex             | 16 +++++++++++++++-
 img/class-savemgr.puml | 13 +++++++++++++
 reqs.toml              | 20 ++++++++++++++++++++
 3 files changed, 48 insertions(+), 1 deletion(-)
 create mode 100644 img/class-savemgr.puml

(limited to 'design.tex')

diff --git a/design.tex b/design.tex
index a3da41c..761658c 100644
--- a/design.tex
+++ b/design.tex
@@ -206,9 +206,23 @@ requirements were also set:\noparbreak
 \begin{itemize}
 	\item Prevent data loss in the case of crashes (\cref{req:savemgr:journalling})
 	\item Handle opening/closing/flushing of the underlying file automatically
-		% (\cref{req:savemgr:???})
+		(\cref{req:savemgr:file-manage})
+	\item Save file variables are uniquely identified (\cref{req:savemgr:var-key})
 \end{itemize}
 
+% \subsubsection{Architecture}
+% \label{sec:savemgr:architecture}
+% 
+% \begin{figure}
+% 	\centering
+% 	\includepumldiag{img/class-savemgr.puml}
+% 	\caption{Save manager class diagram}
+% 	\label{fig:class-savemgr}
+% \end{figure}
+% 
+% In order to realize \cref{req:savemgr:journalling,req:savemgr:var-key}, a third-party
+% key-value database library is used.
+
 % \subsection{Input}
 
 % \subsection{Physics}
diff --git a/img/class-savemgr.puml b/img/class-savemgr.puml
new file mode 100644
index 0000000..30bcd08
--- /dev/null
+++ b/img/class-savemgr.puml
@@ -0,0 +1,13 @@
+@startuml
+!include theme.ipuml
+skinparam Linetype ortho
+
+class SaveManager {
+
+}
+
+class ValueBroker {
+
+}
+
+@enduml
diff --git a/reqs.toml b/reqs.toml
index 8cf9bca..9ad0a86 100644
--- a/reqs.toml
+++ b/reqs.toml
@@ -162,3 +162,23 @@ description = '''
 The save manager can load multiple different save files.
 '''
 
+[savemgr:file-manage]
+type = 'system'
+priority = 'must'
+description = '''
+The save manager manages opening/closing the underlying file, and flushing
+in-memory data to the file.
+'''
+done = '''
+The game programmer is able to use the save manager without explicit
+(de)initialization.
+'''
+
+[savemgr:var-key]
+type = 'system'
+priority = 'must'
+description = '''
+The save manager provides access to variables uniquely identified by a key
+string.
+'''
+
-- 
cgit v1.2.3


From 8ea0137aeeb5cc32c0456a7e2b7c4cbd8b73f010 Mon Sep 17 00:00:00 2001
From: max-001 <maxsmits21@kpnmail.nl>
Date: Thu, 31 Oct 2024 16:40:59 +0100
Subject: Made chapter two of the design

---
 design.tex             |  86 +++++++++++++++++++++++++++++++++++++++++++++++--
 img/JetpackJoyride.jpg | Bin 0 -> 295103 bytes
 sources.bib            |  12 +++++++
 3 files changed, 96 insertions(+), 2 deletions(-)
 create mode 100644 img/JetpackJoyride.jpg

(limited to 'design.tex')

diff --git a/design.tex b/design.tex
index 08ea7cc..94ff3a7 100644
--- a/design.tex
+++ b/design.tex
@@ -23,10 +23,92 @@ Unity and are looking for a flexible, cost-effective solution with familiar
 workflows.
 
 \section{Overview}
+As described above, the cr\^epe game engine's goal is to offer a Unity-like experience
+tailored for developing 2D games similar to Jetpack Joyride. That is why Jetpack
+Joyride and Unity provided the main inputs for this game engine design. Firstly, a
+quick overview will be given of the Unity game engine, in particular the \gls{ecs}.
+Secondly, this Overview will quickly talk you through some of the most important
+parts of the game engine, and why these parts are needed to create the Jetpack
+Joyride game.
+
+\subsection{ECS}
+The Unity game engine is structured using 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 also called a GameObject in Unity and it is made out of one (or
+more) components. Components are the classes that hold the data. The components
+determine what kind of entity it is (e.g. an enemy, 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).
 
-\subsection{Core}
+\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} will also be used at the cr\^epe game engine. Everything (from the
+protagonist and bullets to the walls and enemies) in the cr\^epe game engine will
+be a GameObject (a.k.a. entity). The game programmer must program his game by
+creating all kind of GameObjects and placing them in one (or multiple) scenes, just
+like Unity.
+
+\subsection{Jetpack Joyride}
+Firstly, some background information about Jetpack Joyride. Jetpack Joyride is a
+side-scrolling endless runner action video game created by Halfbrick Studios. The
+protagonist is called Barry Steakfries, who the player controls as he steals a
+bullet-powered jet pack from a top-secret laboratory \autocite{wiki:JetpackJoyride}.
+A screenshot from the game can be seen in \cref{fig:JetpackJoyride} (pleae be
+aware that the goal of this project is not to create an exact replica of Jetpack
+Joyride, it is only used as a source of inspiration).
+
+\begin{figure}
+	\centering
+	\includegraphics[width=0.5\textwidth]{img/JetpackJoyride.jpg}
+	\caption{Jetpack Joyride}
+	Source: \autocite{img:JetpackJoyride}
+	\label{fig:JetpackJoyride}
+\end{figure}
 
-\subsection{Patterns}
+The protagonist wears a jetpack with which he can float in the air. The player must
+avoide obstacles (such as lasers, missiles and zappers) by floating at the right
+height. The player can control the protagonist's jetpack, thereby also controlling
+the protagonist's height. The protagonist experiences gravity and other forces (like
+the force from his jetpack pushing him upwards). These forces should be easily
+programmable by the game programmer. That is why a physics system is needed in the
+cr\^epe game engine. Only very limited/easy physics are needed for Jetpack Joyride,
+that is why this is only supported by the cr\^epe game engine.
+
+The protagonist must avoid obstacles. That is why the cr\^epe game engine should
+also support a collision system. Again, only very limited/easy collision is needed
+for Jetpack Joyride, that is why only very limited/easy collision is supported
+by the cr\^epe game engine.
+
+The game must, of course, also be visible to and playable by the user. A rendering
+system will take care of rendering (displaying) the game and its GameObjects. An
+input system will take care of all the inputs (mouse and keyboard).
+
+Jetpack Joyride also offers audio. A system will take care of the audio in the cr\^epe
+game engine.
+
+Particles are very common in Jetpack Joyride, e.g. underneath the jetpack and behind
+the rockets. Particles will be supported by the particle system.
+
+The start of a scene is described in a scene. However, the game programmer might also
+want to write game logic code which is running during the game (e.g. to switch to a
+new scene or to perform a custom action at a collision). For these purposes, Unity
+uses scripts. These scripts will also be supported by the cr\^epe game engine.
+
+Finally, as an extra, replay functionality will be supported by the cr\^epe game
+engine. A dedicated replay system will be used to support replay.
+
+It turns out that a physics, collision, rendering, input, audio, particle, script,
+and replay system are needed to create the Jetpack Joyride game. These systems form
+the main part of the \gls{ecs}. The design of these eight systems in combination with
+\gls{ecs}, will be briefly discussed in the next parts of this design document.
 
 \section{Design}
 
diff --git a/img/JetpackJoyride.jpg b/img/JetpackJoyride.jpg
new file mode 100644
index 0000000..d1c0e9e
Binary files /dev/null and b/img/JetpackJoyride.jpg differ
diff --git a/sources.bib b/sources.bib
index 7d7b6f7..dc05a95 100644
--- a/sources.bib
+++ b/sources.bib
@@ -194,3 +194,15 @@
   date = {2024}
 }
 
+@online{wiki:JetpackJoyride,
+	title = {Jetpack Joyride wikipedia},
+	url = {https://en.wikipedia.org/wiki/Jetpack_Joyride},
+	urldate = {2024-10-22},
+}
+
+@misc{img:JetpackJoyride,
+	title = {Jetpack Joyride},
+	author = {Halbrick},
+	url = {https://www.halfbrick.com/games/jetpack-joyride-2},
+	date = {2024}
+}
-- 
cgit v1.2.3


From 36f25d64abc37f6fa0fbd1c10f11dfe3ac10b5ea Mon Sep 17 00:00:00 2001
From: Loek Le Blansch <loek@pipeframe.xyz>
Date: Thu, 31 Oct 2024 17:01:46 +0100
Subject: WIP more design

---
 design.tex                | 41 ++++++++++++++++++++++++++++++++++++++++-
 img/activity-scripts.puml | 21 +++++++++++++++++++++
 img/theme.ipuml           | 14 ++++----------
 3 files changed, 65 insertions(+), 11 deletions(-)
 create mode 100644 img/activity-scripts.puml

(limited to 'design.tex')

diff --git a/design.tex b/design.tex
index 761658c..340a662 100644
--- a/design.tex
+++ b/design.tex
@@ -69,6 +69,7 @@ architecture:\noparbreak
 \end{itemize}
 
 \subsubsection{Architecture}
+\label{sec:scripts:architecture}
 
 The restrictions detailed at the start of this section are mitigated as
 follows:\noparbreak
@@ -115,7 +116,8 @@ contains the following classes:\noparbreak
 		This class also uses a friend relation to \codeinline{ScriptSystem} to restrict
 		access to its private reference member \codeinline{script}.
 	\item[ScriptSystem] This is the system class that runs the methods implemented in
-		the derivative instances of \codeinline{Script}.
+		the derivative instances of \codeinline{Script}. Described further in
+		\cref{sec:scripts:sytem}.
 \end{description}
 
 \begin{figure}
@@ -125,6 +127,32 @@ contains the following classes:\noparbreak
 	\label{fig:class-scripts}
 \end{figure}
 
+\subsubsection{System}
+\label{sec:scripts:sytem}
+
+Because most of the complexity in the scripting interface comes from the containers
+described in \cref{sec:scripts:architecture}, the script system class itself is
+relatively simple. The script system provides a method
+\codeinline{ScriptSystem::update} that calls all active script's update functions.
+
+Because of the limitation that types cannot be passed as parameters in C++, the
+user-defined script class (derived from \codeinline{Script}) can not directly be
+instantiated when adding the component to the component manager. To work around this
+limitation, the method \codeinline{BehaviorScript::set_script} was created. This
+results in the possibility that an instance of \codeinline{BehaviorScript} does not
+reference an instance of \codeinline{Script}. In addition to the non-active script
+components, the script system skips over these `invalid' instances. This is
+illustrated in \cref{fig:activity-scripts}.
+
+\begin{figure}
+	\centering
+	\includepumldiag{img/activity-scripts.puml}
+	\caption{Script system update method}
+	\label{fig:activity-scripts}
+\end{figure}
+
+A \gls{poc} for the script system
+
 \subsection{Audio}
 
 Since writing a custom real-time audio mixing engine is outside the scope of this
@@ -227,5 +255,16 @@ requirements were also set:\noparbreak
 
 % \subsection{Physics}
 
+\appendix
+
+\section{\Glsfmtlongpl{poc}}
+
+\subsection{Script system}
+\label{poc:scripts}
+
+\subsection{Global configuration interface}
+
+\subsection{Logging utilities}
+
 \end{document}
 
diff --git a/img/activity-scripts.puml b/img/activity-scripts.puml
new file mode 100644
index 0000000..b833bdf
--- /dev/null
+++ b/img/activity-scripts.puml
@@ -0,0 +1,21 @@
+@startuml
+!include theme.ipuml
+
+start
+
+label continue
+:Get list of ""BehaviorScript"" components from ""ComponentManager"";
+
+while (for each ""BehaviorScript"" in list)
+	if (""BehaviorScript"" is active) then (yes)
+		if (""BehaviorScript"" has an instance of ""Script"") then (yes)
+			:Call update function of ""BehaviorScript""'s ""Script"" instance;
+		else (no)
+		endif
+	else (no)
+	endif
+endwhile
+
+stop
+
+@enduml
diff --git a/img/theme.ipuml b/img/theme.ipuml
index 81391e2..c44db05 100644
--- a/img/theme.ipuml
+++ b/img/theme.ipuml
@@ -1,18 +1,10 @@
 ' vim:ft=plantuml
-
-<style>
-root {
-	BackgroundColor white
-	FontColor black
-	LineThickness 1
-	Margin 0
-}
-</style>
-
+!theme plain
 skinparam ClassAttributeIconSize 0
 skinparam ClassFontStyle bold
 skinparam DefaultFontName Inter
 skinparam DefaultFontSize 10
+skinparam DefaultMonospacedFontName "JetBrains Mono"
 skinparam MaxMessageSize 200
 skinparam Nodesep 25
 ' skinparam Padding 0
@@ -20,6 +12,8 @@ skinparam Ranksep 50
 skinparam RoundCorner 0
 skinparam PackageStyle rectangle
 skinparam PackageFontStyle italic
+skinparam ActivityStartColor black
+skinparam ActivityEndColor black
 
 hide class circle
 
-- 
cgit v1.2.3


From bc4353cba5323a1e60c41e357838edc0be67958b Mon Sep 17 00:00:00 2001
From: Loek Le Blansch <loek@pipeframe.xyz>
Date: Thu, 31 Oct 2024 17:15:49 +0100
Subject: fix code style

---
 design.tex  | 73 ++++++++++++++++++++++++++++++++-----------------------------
 sources.bib | 16 +++++++++-----
 2 files changed, 48 insertions(+), 41 deletions(-)

(limited to 'design.tex')

diff --git a/design.tex b/design.tex
index 94ff3a7..88d7cc8 100644
--- a/design.tex
+++ b/design.tex
@@ -23,58 +23,61 @@ Unity and are looking for a flexible, cost-effective solution with familiar
 workflows.
 
 \section{Overview}
-As described above, the cr\^epe game engine's goal is to offer a Unity-like experience
-tailored for developing 2D games similar to Jetpack Joyride. That is why Jetpack
-Joyride and Unity provided the main inputs for this game engine design. Firstly, a
-quick overview will be given of the Unity game engine, in particular the \gls{ecs}.
-Secondly, this Overview will quickly talk you through some of the most important
-parts of the game engine, and why these parts are needed to create the Jetpack
-Joyride game.
+
+As described above, the cr\^epe game engine's goal is to offer a Unity-like
+experience tailored for developing 2D games similar to Jetpack Joyride. That is why
+Jetpack Joyride and Unity provided the main inputs for this game engine design.
+Firstly, a quick overview will be given of the Unity game engine, in particular the
+\gls{ecs}. Secondly, this Overview will quickly talk you through some of the most
+important parts of the game engine, and why these parts are needed to create the
+Jetpack Joyride game.
 
 \subsection{ECS}
-The Unity game engine is structured using 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 also called a GameObject in Unity and it is made out of one (or
-more) components. Components are the classes that hold the data. The components
-determine what kind of entity it is (e.g. an enemy, 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).
+
+The Unity game engine is structured using 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 also called a GameObject in Unity and it is made out of one (or more) components.
+Components are the classes that hold the data. The components determine what kind of
+entity it is (e.g. an enemy, 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).
 
 \begin{figure}
 	\centering
 	\includegraphics[width=0.5\textwidth]{img/ECSBlockDiagram.png}
 	\caption{ECS design pattern}
-	Source: \autocite{img:ECSBlockDiagram}
-	\label{fig:ECS Block Diagram}
+	Source: \autocite{img:ecs-block-diag}
+	\label{fig:ecs-block-diagram}
 \end{figure}
 
 The \gls{ecs} will also be used at the cr\^epe game engine. Everything (from the
-protagonist and bullets to the walls and enemies) in the cr\^epe game engine will
-be a GameObject (a.k.a. entity). The game programmer must program his game by
-creating all kind of GameObjects and placing them in one (or multiple) scenes, just
-like Unity.
+protagonist and bullets to the walls and enemies) in the cr\^epe game engine will be
+a GameObject (i.e.~entity). The game programmer must program his game by creating all
+kind of GameObjects and placing them in one (or multiple) scenes, just like Unity.
 
 \subsection{Jetpack Joyride}
+
 Firstly, some background information about Jetpack Joyride. Jetpack Joyride is a
 side-scrolling endless runner action video game created by Halfbrick Studios. The
 protagonist is called Barry Steakfries, who the player controls as he steals a
-bullet-powered jet pack from a top-secret laboratory \autocite{wiki:JetpackJoyride}.
-A screenshot from the game can be seen in \cref{fig:JetpackJoyride} (pleae be
-aware that the goal of this project is not to create an exact replica of Jetpack
-Joyride, it is only used as a source of inspiration).
+bullet-powered jet pack from a top-secret laboratory
+\autocite{wikipedia:jetpack-joyride}. A screenshot from the game can be seen in
+\cref{fig:jetpack-joyride} (pleae be aware that the goal of this project is not to
+create an exact replica of Jetpack Joyride, it is only used as a source of
+inspiration).
 
 \begin{figure}
 	\centering
 	\includegraphics[width=0.5\textwidth]{img/JetpackJoyride.jpg}
 	\caption{Jetpack Joyride}
-	Source: \autocite{img:JetpackJoyride}
-	\label{fig:JetpackJoyride}
+	Source: \autocite{img:jetpack-joyride}
+	\label{fig:jetpack-joyride}
 \end{figure}
 
 The protagonist wears a jetpack with which he can float in the air. The player must
-avoide obstacles (such as lasers, missiles and zappers) by floating at the right
+avoid obstacles (such as lasers, missiles and zappers) by floating at the right
 height. The player can control the protagonist's jetpack, thereby also controlling
 the protagonist's height. The protagonist experiences gravity and other forces (like
 the force from his jetpack pushing him upwards). These forces should be easily
@@ -82,17 +85,17 @@ programmable by the game programmer. That is why a physics system is needed in t
 cr\^epe game engine. Only very limited/easy physics are needed for Jetpack Joyride,
 that is why this is only supported by the cr\^epe game engine.
 
-The protagonist must avoid obstacles. That is why the cr\^epe game engine should
-also support a collision system. Again, only very limited/easy collision is needed
-for Jetpack Joyride, that is why only very limited/easy collision is supported
-by the cr\^epe game engine.
+The protagonist must avoid obstacles. That is why the cr\^epe game engine should also
+support a collision system. Again, only very limited/easy collision is needed for
+Jetpack Joyride, that is why only very limited/easy collision is supported by the
+cr\^epe game engine.
 
 The game must, of course, also be visible to and playable by the user. A rendering
 system will take care of rendering (displaying) the game and its GameObjects. An
 input system will take care of all the inputs (mouse and keyboard).
 
-Jetpack Joyride also offers audio. A system will take care of the audio in the cr\^epe
-game engine.
+Jetpack Joyride also offers audio. A system will take care of the audio in the
+cr\^epe game engine.
 
 Particles are very common in Jetpack Joyride, e.g. underneath the jetpack and behind
 the rockets. Particles will be supported by the particle system.
diff --git a/sources.bib b/sources.bib
index dc05a95..0ff00a1 100644
--- a/sources.bib
+++ b/sources.bib
@@ -164,7 +164,7 @@
 	date = {2016}
 }
 
-@misc{img:ECSBlockDiagram,
+@misc{img:ecs-block-diag,
 	title = {ECS Diagram},
 	author = {{Unity}},
 	url = {https://docs.unity3d.com/Packages/com.unity.entities@0.1/manual/images/ECSBlockDiagram.png},
@@ -194,15 +194,19 @@
   date = {2024}
 }
 
-@online{wiki:JetpackJoyride,
-	title = {Jetpack Joyride wikipedia},
-	url = {https://en.wikipedia.org/wiki/Jetpack_Joyride},
+@online{wikipedia:jetpack-joyride,
+	author = {{Wikipedia contributors}},
+	title = {Jetpack Joyride --- {Wikipedia}{,} The Free Encyclopedia},
+	year = {2024},
+	url = {https://en.wikipedia.org/w/index.php?title=Jetpack_Joyride&oldid=1252734266},
 	urldate = {2024-10-22},
 }
 
-@misc{img:JetpackJoyride,
+@misc{img:jetpack-joyride,
 	title = {Jetpack Joyride},
 	author = {Halbrick},
 	url = {https://www.halfbrick.com/games/jetpack-joyride-2},
-	date = {2024}
+	date = {2024},
+	urldate = {2024-10-22},
 }
+
-- 
cgit v1.2.3


From cf6c883c5b09d2cd2d3f7a117b5ce2b31c92a00f Mon Sep 17 00:00:00 2001
From: Loek Le Blansch <loek@pipeframe.xyz>
Date: Thu, 31 Oct 2024 19:00:06 +0100
Subject: more POC showcase

---
 design.tex                 |  64 +++++++++++++++++++++++++++++++++++++--------
 img/poc-output-scripts.png | Bin 0 -> 31761 bytes
 2 files changed, 53 insertions(+), 11 deletions(-)
 create mode 100644 img/poc-output-scripts.png

(limited to 'design.tex')

diff --git a/design.tex b/design.tex
index 340a662..9088528 100644
--- a/design.tex
+++ b/design.tex
@@ -151,7 +151,7 @@ illustrated in \cref{fig:activity-scripts}.
 	\label{fig:activity-scripts}
 \end{figure}
 
-A \gls{poc} for the script system
+A \gls{poc} for the script system is showcased in \cref{poc:scripts}.
 
 \subsection{Audio}
 
@@ -168,15 +168,7 @@ searching for libraries (search terms: `dynamic/adaptive audio', `real-time audi
 `audio library', `game audio engine'), several libraries were found. These libraries
 were checked against the audio engine requirements \autocite{crepe:requirements} and
 then tested by writing the same benchmark-style \gls{poc} using the remaining
-qualifying libraries:\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}
+qualifying libraries. These \glspl{poc} are detailed in \cref{poc:audio}.
 
 Of these libraries the following were determined to be unsuitable for use in this
 project:\noparbreak
@@ -217,6 +209,8 @@ contains the following classes:
 	\label{fig:class-audio-facade}
 \end{figure}
 
+A \gls{poc} for the final Audio fa\c{c}ade is also showcased in \cref{poc:audio}.
+
 \subsection{Save manager}
 
 The save manager \gls{api} is designed to give the game programmer an easy to use
@@ -251,6 +245,8 @@ requirements were also set:\noparbreak
 % In order to realize \cref{req:savemgr:journalling,req:savemgr:var-key}, a third-party
 % key-value database library is used.
 
+\subsection{Global configuration interface}
+
 % \subsection{Input}
 
 % \subsection{Physics}
@@ -259,12 +255,58 @@ requirements were also set:\noparbreak
 
 \section{\Glsfmtlongpl{poc}}
 
+The full (documented) source code of these \glspl{poc} is available on GitHub
+\autocite{crepe:code-repo}.
+
 \subsection{Script system}
 \label{poc:scripts}
 
-\subsection{Global configuration interface}
+The script system \gls{poc} \autocite[script example]{crepe:code-repo} consists of
+the following:\noparbreak
+\begin{itemize}
+	\item A user-defined class (\codeinline{MyScript}) derived from
+		\codeinline{Script}, which only implements the \codeinline{update()} function.
+	\item A main function that---
+		\begin{itemize}
+			\item Creates a game object with \codeinline{Transform} and
+				\codeinline{BehaviorScript} components.
+			\item A call to \codeinline{ScriptSystem::update}, which results in
+				\codeinline{MyScript::update} being called.
+		\end{itemize}
+\end{itemize}
+
+Running the \gls{poc} results in the output shown in \cref{fig:poc-output-scripts},
+demonstrating that the system works as intended.
+
+\begin{figure}
+	\centering
+	\fitimg{\includegraphics{img/poc-output-scripts.png}}
+	\caption{Script system \glsfmtshort{poc} output}
+	\label{fig:poc-output-scripts}
+\end{figure}
 
 \subsection{Logging utilities}
+\label{poc:log}
+
+\subsection{Audio}
+\label{poc:audio}
+
+A test that consists of the following steps was written for each audio library
+mentioned in \cref{sec:audio:libs}:\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}
+
+The repository \autocite{crepe:code-repo} contains two finished \glspl{poc} under the
+\codeinline{mwe/audio/} subdirectory for miniaudio and SoLoud. The SoLoud \gls{poc}
+was later converted to a full audio fa\c{c}ade, which is currently part of the
+cr\^epe engine. The \gls{poc} using the audio fa\c{c}ade is available from the same
+repository, under the \codeinline{src/example/audio_internal.cpp} file.
 
 \end{document}
 
diff --git a/img/poc-output-scripts.png b/img/poc-output-scripts.png
new file mode 100644
index 0000000..068f345
Binary files /dev/null and b/img/poc-output-scripts.png differ
-- 
cgit v1.2.3


From 24611c757318be124c01a6c335d116e7d1529554 Mon Sep 17 00:00:00 2001
From: Loek Le Blansch <loek@pipeframe.xyz>
Date: Fri, 1 Nov 2024 15:09:03 +0100
Subject: add design for global configuration manager + appendix log poc

---
 design.tex            |  58 ++++++++++++++++++++++++++++++++++++++++++--------
 glossary.bib          |   4 ++++
 img/class-config.puml |  14 ++++++++++++
 img/poc-log.png       | Bin 0 -> 12526 bytes
 4 files changed, 67 insertions(+), 9 deletions(-)
 create mode 100644 img/class-config.puml
 create mode 100644 img/poc-log.png

(limited to 'design.tex')

diff --git a/design.tex b/design.tex
index 9088528..75e9ec6 100644
--- a/design.tex
+++ b/design.tex
@@ -151,13 +151,13 @@ illustrated in \cref{fig:activity-scripts}.
 	\label{fig:activity-scripts}
 \end{figure}
 
-A \gls{poc} for the script system is showcased in \cref{poc:scripts}.
+A \gls{poc} for the script system is shown in \cref{poc:scripts}.
 
 \subsection{Audio}
 
 Since writing a custom real-time audio mixing engine is outside the scope of this
 project\mref and C++ does not provide a built-in cross-platform audio \gls{api}, the
-audio system inside the cr\^epe engine is implemented as a fa\c{c}ade around an
+audio system inside the cr\^epe engine is implemented as a \gls{facade} around an
 existing audio library.
 
 \subsubsection{Libraries}
@@ -184,12 +184,12 @@ project:\noparbreak
 
 The only library that remained after these tests is SoLoud \autocite{lib:soloud}. It
 is Zlib/LibPng licensed and provides a high-level object-oriented C++ \gls{api}.
-\Cref{sec:audio:architecture} describes the fa\c{c}ade written for this library.
+\Cref{sec:audio:architecture} describes the \gls{facade} written for this library.
 
 \subsubsection{Architecture}
 \label{sec:audio:architecture}
 
-\Cref{fig:class-audio-facade} shows a class diagram of the audio fa\c{c}ade. It
+\Cref{fig:class-audio-facade} shows a class diagram of the audio \gls{facade}. It
 contains the following classes:
 \begin{description}
 	\item[SoundContext] This is a wrapper around the \codeinline{SoLoud::soloud}
@@ -205,11 +205,11 @@ contains the following classes:
 \begin{figure}
 	\centering
 	\includepumldiag{img/facade-audio.puml}
-	\caption{Audio fa\c{c}ade class diagram}
+	\caption{Audio \glsfmtshort{facade} class diagram}
 	\label{fig:class-audio-facade}
 \end{figure}
 
-A \gls{poc} for the final Audio fa\c{c}ade is also showcased in \cref{poc:audio}.
+A \gls{poc} for the final Audio \gls{facade} is also showcased in \cref{poc:audio}.
 
 \subsection{Save manager}
 
@@ -247,6 +247,26 @@ requirements were also set:\noparbreak
 
 \subsection{Global configuration interface}
 
+Because the game programmer only has access to interfaces within the public \gls{api}
+namespace (\codeinline{crepe::api}), they would not be able to configure aspects of
+engine-internal components. To work around this access restriction, a global
+interface was made that stores arbitrary data, which can be accessed both internally
+and via the public \gls{api}.
+
+\subsubsection{Architecture}
+\label{sec:config:architecture}
+
+The global configuration interface consists of a single singleton class that can be
+accessed globally (see \cref{fig:class-config}). This class holds several anonymous
+structs, which are used to organize options per system or engine component.
+
+\begin{figure}
+	\centering
+	\includepumldiag{img/class-config.puml}
+	\caption{Global configuration interface class diagram}
+	\label{fig:class-config}
+\end{figure}
+
 % \subsection{Input}
 
 % \subsection{Physics}
@@ -280,7 +300,7 @@ demonstrating that the system works as intended.
 
 \begin{figure}
 	\centering
-	\fitimg{\includegraphics{img/poc-output-scripts.png}}
+	\fitimg{\includegraphics[scale=0.7]{img/poc-output-scripts.png}}
 	\caption{Script system \glsfmtshort{poc} output}
 	\label{fig:poc-output-scripts}
 \end{figure}
@@ -288,6 +308,26 @@ demonstrating that the system works as intended.
 \subsection{Logging utilities}
 \label{poc:log}
 
+A small \gls{poc} was written to test the engine's logging functions \autocite[log
+example]{crepe:code-repo}. The following calls are used in this example:
+
+\begin{blockcode}
+dbg_trace();                                 // the dbg_* macros automatically show
+dbg_logf("test printf parameters: %d", 3);   // where the message is coming from
+logf(LogLevel::INFO,    "info message");
+logf(LogLevel::WARNING, "warning");
+logf(LogLevel::ERROR,   "error");
+\end{blockcode}
+
+The output of this test is shown in \cref{fig:poc-log}.
+
+\begin{figure}
+	\centering
+	\includegraphics[scale=0.7]{img/poc-log.png}
+	\caption{Logging function outputs}
+	\label{fig:poc-log}
+\end{figure}
+
 \subsection{Audio}
 \label{poc:audio}
 
@@ -304,8 +344,8 @@ mentioned in \cref{sec:audio:libs}:\noparbreak
 
 The repository \autocite{crepe:code-repo} contains two finished \glspl{poc} under the
 \codeinline{mwe/audio/} subdirectory for miniaudio and SoLoud. The SoLoud \gls{poc}
-was later converted to a full audio fa\c{c}ade, which is currently part of the
-cr\^epe engine. The \gls{poc} using the audio fa\c{c}ade is available from the same
+was later converted to a full audio \gls{facade}, which is currently part of the
+cr\^epe engine. The \gls{poc} using the audio \gls{facade} is available from the same
 repository, under the \codeinline{src/example/audio_internal.cpp} file.
 
 \end{document}
diff --git a/glossary.bib b/glossary.bib
index fda634f..0842ff8 100644
--- a/glossary.bib
+++ b/glossary.bib
@@ -51,4 +51,8 @@
 	long = {proof-of-concept},
 }
 
+@entry{facade,
+	name = {fa\c{c}ade},
+	description = {Design pattern used to provide an abstraction from other software},
+}
 
diff --git a/img/class-config.puml b/img/class-config.puml
new file mode 100644
index 0000000..72e5e6c
--- /dev/null
+++ b/img/class-config.puml
@@ -0,0 +1,14 @@
+@startuml
+!include theme.ipuml
+
+class Config <<singleton>> {
+	- Config()
+	+ ~Config()
+	--
+	+ get_instance() : Config & <<static>>
+	--
+	+ log : struct ...
+	...
+}
+
+@enduml
diff --git a/img/poc-log.png b/img/poc-log.png
new file mode 100644
index 0000000..12e2c61
Binary files /dev/null and b/img/poc-log.png differ
-- 
cgit v1.2.3


From f316e5582c40cbfe18567c7fd34cbb1bfff3ddbb Mon Sep 17 00:00:00 2001
From: Loek Le Blansch <loek@pipeframe.xyz>
Date: Fri, 1 Nov 2024 15:42:06 +0100
Subject: comment out WIP design

---
 design.tex | 42 +++++++++++++++++++++---------------------
 1 file changed, 21 insertions(+), 21 deletions(-)

(limited to 'design.tex')

diff --git a/design.tex b/design.tex
index 4a8208d..4c4794d 100644
--- a/design.tex
+++ b/design.tex
@@ -296,27 +296,27 @@ contains the following classes:
 
 A \gls{poc} for the final Audio \gls{facade} is also showcased in \cref{poc:audio}.
 
-\subsection{Save manager}
-
-The save manager \gls{api} is designed to give the game programmer an easy to use
-interface for retrieving and storing game-specific data (\cref{req:savemgr}).
-
-Because the engine validation app only stores statistics and highscores, the save
-manager is not required to support loading different save files
-(\cref{req:savemgr:multi-file}), nor storing complicated data types
-(\cref{req:savemgr:types-custom}). The save manager only supports storing simple
-types (\cref{req:savemgr:types-scalar,req:savemgr:types-string}).
-
-In order to reduce complexity for the game programmer further, the following
-requirements were also set:\noparbreak
-
-\begin{itemize}
-	\item Prevent data loss in the case of crashes (\cref{req:savemgr:journalling})
-	\item Handle opening/closing/flushing of the underlying file automatically
-		(\cref{req:savemgr:file-manage})
-	\item Save file variables are uniquely identified (\cref{req:savemgr:var-key})
-\end{itemize}
-
+% \subsection{Save manager}
+% 
+% The save manager \gls{api} is designed to give the game programmer an easy to use
+% interface for retrieving and storing game-specific data (\cref{req:savemgr}).
+% 
+% Because the engine validation app only stores statistics and highscores, the save
+% manager is not required to support loading different save files
+% (\cref{req:savemgr:multi-file}), nor storing complicated data types
+% (\cref{req:savemgr:types-custom}). The save manager only supports storing simple
+% types (\cref{req:savemgr:types-scalar,req:savemgr:types-string}).
+% 
+% In order to reduce complexity for the game programmer further, the following
+% requirements were also set:\noparbreak
+% 
+% \begin{itemize}
+% 	\item Prevent data loss in the case of crashes (\cref{req:savemgr:journalling})
+% 	\item Handle opening/closing/flushing of the underlying file automatically
+% 		(\cref{req:savemgr:file-manage})
+% 	\item Save file variables are uniquely identified (\cref{req:savemgr:var-key})
+% \end{itemize}
+% 
 % \subsubsection{Architecture}
 % \label{sec:savemgr:architecture}
 % 
-- 
cgit v1.2.3