From f923835a5e82d727dc27d61ef9ef9d731580b0c9 Mon Sep 17 00:00:00 2001 From: Max-001 <80035972+Max-001@users.noreply.github.com> Date: Mon, 16 Sep 2024 16:53:41 +0200 Subject: Added popular ECS --- research.tex | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/research.tex b/research.tex index ad33d10..3e2e103 100644 --- a/research.tex +++ b/research.tex @@ -66,10 +66,30 @@ must be stored efficiently, and entities must be provided with the required beha such as audio, position, or physics. To create diverse entities with specific functions: A scene can contain many different kinds of entities, each with different properties and functions. But no matter how different each entity is, it remains an -entity. To assign properties and functions to entities, components are used. Entt is -an example of an \gls{ecs}. +entity. To assign properties and functions to entities, components are used. % TODO: ref?entt +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} + \begin{tabularx}{\linewidth}{lXr} + \toprule + \textbf{Name} & \textbf{Short Description} & \textbf{GitHub Stars} \\ + \midrule + EnTT & Fast and reliable entity-component system & 10k \\ + Flecs & A Multithreaded Entity Component System written for C89 and C99 & 6.3k \\ + EntityX & Fast, type-safe C++ entity component system & 2.2k \\ + \bottomrule + \end{tabularx} + \caption{Popular \gls{ecs} libraries} + \label{tab:popularECSLibraries} +\end{table} +https://github.com/abeimler/ecs_benchmark + +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. https://github.com/SanderMertens/ecs-faq?tab=readme-ov-file#should-i-write-my-own-ecs + \subsection{Conclusion} \section{Third-party Tools} -- cgit v1.2.3 From f89ee3feb7e514ec7fbb469a16d34569a57bd0dc Mon Sep 17 00:00:00 2001 From: Max-001 <80035972+Max-001@users.noreply.github.com> Date: Wed, 18 Sep 2024 15:03:23 +0200 Subject: Added sources to text --- research.tex | 28 ++++++++++++++-------------- sources.bib | 12 ++++++++++++ 2 files changed, 26 insertions(+), 14 deletions(-) diff --git a/research.tex b/research.tex index 3e2e103..d453df5 100644 --- a/research.tex +++ b/research.tex @@ -72,23 +72,23 @@ entity. To assign properties and functions to entities, components are used. 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} - \begin{tabularx}{\linewidth}{lXr} - \toprule - \textbf{Name} & \textbf{Short Description} & \textbf{GitHub Stars} \\ - \midrule - EnTT & Fast and reliable entity-component system & 10k \\ - Flecs & A Multithreaded Entity Component System written for C89 and C99 & 6.3k \\ - EntityX & Fast, type-safe C++ entity component system & 2.2k \\ - \bottomrule - \end{tabularx} - \caption{Popular \gls{ecs} libraries} - \label{tab:popularECSLibraries} +\begin{table}[ht] + \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 \autocite{github:001}} + \label{tab:popularECSLibraries} \end{table} -https://github.com/abeimler/ecs_benchmark 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. https://github.com/SanderMertens/ecs-faq?tab=readme-ov-file#should-i-write-my-own-ecs +However, it seems very hard to achieve the same performance as a library. \autocite{github:002} \subsection{Conclusion} diff --git a/sources.bib b/sources.bib index 50f5ead..9b08c96 100644 --- a/sources.bib +++ b/sources.bib @@ -47,4 +47,16 @@ date = {2024-09-10}, } +@misc{github:001, + author = {Sangjun Lee}, + title = {Awesome Entity Component System}, + url = {https://github.com/jslee02/awesome-entity-component-system?tab=readme-ov-file}, + date = {2023} +} +@misc{github:002, + author = {Sander Mertens}, + title = {ECS FAQ}, + url = {https://github.com/SanderMertens/ecs-faq?tab=readme-ov-file#should-i-write-my-own-ecs}, + date = {2023} +} -- cgit v1.2.3 From 105cab5fc6f88f7e71e71910c5f598d39fba3262 Mon Sep 17 00:00:00 2001 From: Max-001 <80035972+Max-001@users.noreply.github.com> Date: Wed, 18 Sep 2024 16:25:37 +0200 Subject: Rectified gameObject/components section, added references to gameObject/components section and created new subsubsection for the game engine's structure --- research.tex | 34 ++++++++++++++++++---------------- sources.bib | 16 ++++++++++++++++ 2 files changed, 34 insertions(+), 16 deletions(-) diff --git a/research.tex b/research.tex index d453df5..f62f736 100644 --- a/research.tex +++ b/research.tex @@ -44,13 +44,17 @@ layers are divided into the following categories:\noparbreak performance profiling. \item[Scripting layer] Runs scripts, such as Lua or Python. \item[Memory systems] Handles and monitors memory usage. - \item[\gls{ecs}] Provides a modular way to create game objects, add physics, and - define how the engine interacts with objects. \item[Physics] Adds specific physics to objects. \item[Audio] Processes audio. \item[AI] Provides artificial inteligent behavior. \end{description} +\subsubsection{Structure} + +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}. ... + \subsubsection{ECS} A game engine must have the ability to keep track and update several game objects. To @@ -286,6 +290,7 @@ Not considered further: \subsection{Conclusion} \section{Gameobjects/components} +\label{sec:Gameobjects/components} \subsection{Introduction} @@ -302,16 +307,7 @@ 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. -% TODO: cite https://docs.unity3d.com/Manual/GameObjects.html - -\subsection{Conclusion} - -\section{AI} - -\subsection{Introduction} - -\subsection{Findings} +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, @@ -326,14 +322,20 @@ 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. -% TODO: cite https://docs.unity3d.com/Manual/class-Transform.html +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. -% TODO: cite https://docs.unity3d.com/Manual/class-Transform.html +can not have more than one parent. \autocite{man:unityTransformClass} + +\subsection{Conclusion} + +\section{AI} + +\subsection{Introduction} + +\subsection{Findings} \subsection{Conclusion} diff --git a/sources.bib b/sources.bib index 9b08c96..d6b960b 100644 --- a/sources.bib +++ b/sources.bib @@ -60,3 +60,19 @@ url = {https://github.com/SanderMertens/ecs-faq?tab=readme-ov-file#should-i-write-my-own-ecs}, date = {2023} } + +@manual{man:unityGameobjects, + title = {GameObject}, + author = {Unity Technologies}, + organization = {Unity}, + url = {https://docs.unity3d.com/Manual/GameObjects.html}, + date = {2024} +} + +@manual{man:unityTransformClass, + title = {Transform Class}, + author = {Unity Technologies}, + organization = {Unity}, + url = {https://docs.unity3d.com/Manual/class-Transform.html}, + date = {2024} +} -- cgit v1.2.3 From d8d57711c340ae58bf14946372fdffd9642532b5 Mon Sep 17 00:00:00 2001 From: Max-001 <80035972+Max-001@users.noreply.github.com> Date: Wed, 18 Sep 2024 17:51:58 +0200 Subject: Described possible game engine structures --- img/DecoratorDesignPattern.png | Bin 0 -> 13528 bytes research.tex | 30 +++++++++++++++++++++++++++--- sources.bib | 23 +++++++++++++++++++++++ 3 files changed, 50 insertions(+), 3 deletions(-) create mode 100644 img/DecoratorDesignPattern.png diff --git a/img/DecoratorDesignPattern.png b/img/DecoratorDesignPattern.png new file mode 100644 index 0000000..8830a3d Binary files /dev/null and b/img/DecoratorDesignPattern.png differ diff --git a/research.tex b/research.tex index f62f736..052a5b2 100644 --- a/research.tex +++ b/research.tex @@ -53,9 +53,34 @@ layers are divided into the following categories:\noparbreak 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}. ... +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} \autocite{man:Decorator} +\begin{figure}[H] + \centering + \includegraphics[width=0.5\textwidth]{img/DecoratorDesignPattern.png} + \caption{Decorator design pattern \autocite{img:Decorator}} + \label{fig:decorator} +\end{figure} + +Another very popular design pattern, is the Entity Component System (\gls{ecs}). ... -\subsubsection{ECS} +\paragraph{ECS} A game engine must have the ability to keep track and update several game objects. To do this most game engines employ an \gls{ecs} model which uses modulair components to @@ -71,7 +96,6 @@ such as audio, position, or physics. To create diverse entities with specific functions: A scene can contain many different kinds of entities, each with different properties and functions. But no matter how different each entity is, it remains an entity. To assign properties and functions to entities, components are used. -% TODO: ref?entt 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 diff --git a/sources.bib b/sources.bib index d6b960b..e754959 100644 --- a/sources.bib +++ b/sources.bib @@ -76,3 +76,26 @@ url = {https://docs.unity3d.com/Manual/class-Transform.html}, date = {2024} } + +@misc{img:Decorator, + title = {Decorator Pattern Structure Diagram}, + author = {Refactoring Guru}, + url = {https://refactoring.guru/images/patterns/diagrams/decorator/structure.png}, + date = {2024} +} + +@manual{man:DecoratorDesignPattern, + title = {Extension Object Design Pattern}, + author = {James Fawcett}, + organization = {Syracuse University}, + url = {https://ecs.syr.edu/faculty/fawcett/handouts/CSE776/PatternPDFs/ExtensionObject.pdf}, + date = {2024} +} + +@manual{man:Decorator, + title = {Decorator Design Pattern}, + author = {Refactoring Guru}, + organization = {Refactoring Guru}, + url = {https://refactoring.guru/design-patterns/decorator}, + date = {2024} +} -- cgit v1.2.3 From c69c8815df1c0e1e6ef155a9cfc4747132e0e1c6 Mon Sep 17 00:00:00 2001 From: Max-001 <80035972+Max-001@users.noreply.github.com> Date: Wed, 18 Sep 2024 18:11:19 +0200 Subject: Made a begin for the ECS --- research.tex | 30 +++++++++++------------------- 1 file changed, 11 insertions(+), 19 deletions(-) diff --git a/research.tex b/research.tex index 052a5b2..1ca5a2e 100644 --- a/research.tex +++ b/research.tex @@ -49,7 +49,7 @@ layers are divided into the following categories:\noparbreak \item[AI] Provides artificial inteligent behavior. \end{description} -\subsubsection{Structure} +\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)). @@ -78,24 +78,16 @@ programming harder. \autocite{man:DecoratorDesignPattern} \autocite{man:Decorato \label{fig:decorator} \end{figure} -Another very popular design pattern, is the Entity Component System (\gls{ecs}). ... - -\paragraph{ECS} - -A game engine must have the ability to keep track and update several game objects. To -do this most game engines employ an \gls{ecs} model which uses modulair components to -give entities properties and features. The need for an entity component system arises -because multiple game objects are required to create a scene in a game. These game -objects exist within the scene and perform actions, such as a UI display for a score. -This game object does not need to be rendered; it could be a script running in the -background. It could also be a player sprite that is controlled. These entities need -to be aware of other entities, for example, during collisions. For this to function, -a scene is required to host all game objects. Within this scene, the game objects -must be stored efficiently, and entities must be provided with the required behavior, -such as audio, position, or physics. To create diverse entities with specific -functions: A scene can contain many different kinds of entities, each with different -properties and functions. But no matter how different each entity is, it remains an -entity. To assign properties and functions to entities, components are used. +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 -- cgit v1.2.3 From 7dc00a616e186bb8b02902e06b7cb38164acbbbd Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Wed, 18 Sep 2024 20:51:55 +0200 Subject: merge #15 --- img/decorator-design-pattern.puml | 62 +++++++++++++++++++++++++ img/theme.ipuml | 9 +++- research.tex | 93 ++++++++++++++++++++----------------- sources.bib | 97 ++++++++++++++++++++------------------- 4 files changed, 169 insertions(+), 92 deletions(-) create mode 100644 img/decorator-design-pattern.puml diff --git a/img/decorator-design-pattern.puml b/img/decorator-design-pattern.puml new file mode 100644 index 0000000..2bc406b --- /dev/null +++ b/img/decorator-design-pattern.puml @@ -0,0 +1,62 @@ +@startuml +!include theme.ipuml +skinparam style strictuml +skinparam Linetype ortho + +class Client +class Component <> { + + execute() + -- +} +class ConcComponent as "Concrete\nComponent" { + ... + -- + + execute() +} +class BaseDecorator as "Base Decorator" { + - wrappee: Component + + BaseDecorator(c: Component) + + execute() +} +class ConcDecorator as "Concrete\nDecorators" { + ... + -- + + execute() + + extra() +} + +hide Client members +hide circle + +Client --> Component +Component <|.. ConcComponent +Component <|.. BaseDecorator +Component <--o BaseDecorator +BaseDecorator <|-- ConcDecorator + +ConcComponent -right[hidden] BaseDecorator + +note right of Client + a = new ConcComponent() + b = new ConcDecorator1(a) + c = new ConcDecorator1(b) + c.execute() + // Decorator -> Decorator -> Component +end note + +note right of BaseDecorator::BaseDecorator + wrappee = c +end note + +note right of BaseDecorator::execute + wrappee.execute() +end note + +note right of ConcDecorator::execute + super::execute() + extra() +end note + +@enduml + +" referenced from diff --git a/img/theme.ipuml b/img/theme.ipuml index 88d183a..4e3613e 100644 --- a/img/theme.ipuml +++ b/img/theme.ipuml @@ -1,5 +1,10 @@ !theme plain -skinparam DefaultFontSize 14 +skinparam ClassAttributeIconSize 0 +skinparam ClassFontStyle bold skinparam DefaultFontName Inter +skinparam DefaultFontSize 14 +skinparam MaxMessageSize 200 +skinparam Nodesep 25 +skinparam Padding 2 +skinparam Ranksep 50 skinparam RoundCorner 0 -skinparam maxMessageSize 200 diff --git a/research.tex b/research.tex index 1ca5a2e..e07a428 100644 --- a/research.tex +++ b/research.tex @@ -52,8 +52,9 @@ layers are divided into the following categories:\noparbreak \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}. +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 @@ -61,54 +62,62 @@ not flexible. However, the provided class diagram of the game engine's API alrea 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} \autocite{man:Decorator} -\begin{figure}[H] - \centering - \includegraphics[width=0.5\textwidth]{img/DecoratorDesignPattern.png} - \caption{Decorator design pattern \autocite{img:Decorator}} - \label{fig:decorator} +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)! +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}[ht] - \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 \autocite{github:001}} - \label{tab:popularECSLibraries} +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:002} +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} diff --git a/sources.bib b/sources.bib index e754959..bf04165 100644 --- a/sources.bib +++ b/sources.bib @@ -13,89 +13,90 @@ } @misc{miro:scrum-board, - author = {Loek Le Blansch and Wouter Boerenkamps and Jaro Rutjes and Max Smits and Niels Stunnebrink}, - title = {Scrum Board on Miro}, - url = {https://miro.com/app/board/uXjVKjtdM64=/?share_link_id=303851465474}, - date = {2024-09-10}, + author = {Loek Le Blansch and Wouter Boerenkamps and Jaro Rutjes and Max Smits and Niels Stunnebrink}, + title = {Scrum Board on Miro}, + url = {https://miro.com/app/board/uXjVKjtdM64=/?share_link_id=303851465474}, + date = {2024-09-10}, } @misc{crepe:code-repo, - author = {Loek Le Blansch and Wouter Boerenkamps and Jaro Rutjes and Max Smits and Niels Stunnebrink}, - title = {Crepe Code Repository}, - url = {https://github.com/lonkaars/crepe}, - date = {2024-09-10}, + author = {Loek Le Blansch and Wouter Boerenkamps and Jaro Rutjes and Max Smits and Niels Stunnebrink}, + title = {Crepe Code Repository}, + url = {https://github.com/lonkaars/crepe}, + date = {2024-09-10}, } @misc{crepe:docs-repo, - author = {Loek Le Blansch and Wouter Boerenkamps and Jaro Rutjes and Max Smits and Niels Stunnebrink}, - title = {Crepe Documentation Repository}, - url = {https://github.com/lonkaars}, - date = {2024-09-10}, + author = {Loek Le Blansch and Wouter Boerenkamps and Jaro Rutjes and Max Smits and Niels Stunnebrink}, + title = {Crepe Documentation Repository}, + url = {https://github.com/lonkaars}, + date = {2024-09-10}, } @misc{crepe:docs-standard, - author = {Loek Le Blansch and Wouter Boerenkamps and Jaro Rutjes and Max Smits and Niels Stunnebrink}, - title = {Crepe Documentation Standard}, - url = {https://github.com/lonkaars/crepe-docs/blob/master/contributing.md}, - date = {2024-09-10}, + author = {Loek Le Blansch and Wouter Boerenkamps and Jaro Rutjes and Max Smits and Niels Stunnebrink}, + title = {Crepe Documentation Standard}, + url = {https://github.com/lonkaars/crepe-docs/blob/master/contributing.md}, + date = {2024-09-10}, } @misc{crepe:code-standard, - author = {Loek Le Blansch and Wouter Boerenkamps and Jaro Rutjes and Max Smits and Niels Stunnebrink}, - title = {Crepe Code Standard}, - url = {https://github.com/lonkaars/crepe/blob/master/contributing.md}, - date = {2024-09-10}, + author = {Loek Le Blansch and Wouter Boerenkamps and Jaro Rutjes and Max Smits and Niels Stunnebrink}, + title = {Crepe Code Standard}, + url = {https://github.com/lonkaars/crepe/blob/master/contributing.md}, + date = {2024-09-10}, } -@misc{github:001, - author = {Sangjun Lee}, - title = {Awesome Entity Component System}, - url = {https://github.com/jslee02/awesome-entity-component-system?tab=readme-ov-file}, +@misc{github:awesome-ecs, + author = {Sangjun Lee}, + title = {Awesome Entity Component System}, + url = {https://github.com/jslee02/awesome-entity-component-system?tab=readme-ov-file}, date = {2023} } -@misc{github:002, - author = {Sander Mertens}, - title = {ECS FAQ}, - url = {https://github.com/SanderMertens/ecs-faq?tab=readme-ov-file#should-i-write-my-own-ecs}, +@misc{github:ecsfaq, + author = {Sander Mertens}, + title = {ECS FAQ}, + url = {https://github.com/SanderMertens/ecs-faq?tab=readme-ov-file#should-i-write-my-own-ecs}, date = {2023} } @manual{man:unityGameobjects, title = {GameObject}, author = {Unity Technologies}, - organization = {Unity}, - url = {https://docs.unity3d.com/Manual/GameObjects.html}, + organization = {Unity}, + url = {https://docs.unity3d.com/Manual/GameObjects.html}, date = {2024} } @manual{man:unityTransformClass, - title = {Transform Class}, - author = {Unity Technologies}, - organization = {Unity}, - url = {https://docs.unity3d.com/Manual/class-Transform.html}, - date = {2024} + title = {Transform Class}, + author = {Unity Technologies}, + organization = {Unity}, + url = {https://docs.unity3d.com/Manual/class-Transform.html}, + date = {2024} } @misc{img:Decorator, - title = {Decorator Pattern Structure Diagram}, - author = {Refactoring Guru}, - url = {https://refactoring.guru/images/patterns/diagrams/decorator/structure.png}, - date = {2024} + title = {Decorator Pattern Structure Diagram}, + author = {Refactoring Guru}, + url = {https://refactoring.guru/images/patterns/diagrams/decorator/structure.png}, + date = {2024} } @manual{man:DecoratorDesignPattern, - title = {Extension Object Design Pattern}, - author = {James Fawcett}, - organization = {Syracuse University}, - url = {https://ecs.syr.edu/faculty/fawcett/handouts/CSE776/PatternPDFs/ExtensionObject.pdf}, - date = {2024} + title = {Extension Object Design Pattern}, + author = {James Fawcett}, + organization = {Syracuse University}, + url = {https://ecs.syr.edu/faculty/fawcett/handouts/CSE776/PatternPDFs/ExtensionObject.pdf}, + date = {2024} } @manual{man:Decorator, - title = {Decorator Design Pattern}, - author = {Refactoring Guru}, + title = {Decorator Design Pattern}, + author = {Refactoring Guru}, organization = {Refactoring Guru}, - url = {https://refactoring.guru/design-patterns/decorator}, - date = {2024} + url = {https://refactoring.guru/design-patterns/decorator}, + date = {2024} } + -- cgit v1.2.3 From 14788335ba110076e8beb72a0330712d238cf12a Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Wed, 18 Sep 2024 20:54:41 +0200 Subject: refactor pro/cons in research --- research.tex | 60 +++++++++++++++++++++++++----------------------------------- 1 file changed, 25 insertions(+), 35 deletions(-) diff --git a/research.tex b/research.tex index e07a428..5340bf5 100644 --- a/research.tex +++ b/research.tex @@ -152,23 +152,18 @@ software, emulators, and popular games, including Valve's award-winning catalog 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. -The advantages of \gls{sdl2} are:\noparbreak -\begin{itemize} - \item Controller support is provided. - \item 2D and 3D rendering are supported. - \item Broad multiplatform support is offered, including older consoles such as the - Wii. - \item Low-level control is available. - \item A large community ensures wide usage. - \item Extended libraries can be used to add functionalities, such as SDL\_Mixer for - sound. -\end{itemize} - -The disadvantages of \gls{sdl2} are:\noparbreak -\begin{itemize} - \item A limited built-in 2D renderer is provided. - \item Extended libraries require setup. -\end{itemize} +\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} @@ -176,24 +171,19 @@ The disadvantages of \gls{sdl2} are:\noparbreak network, system, and window. This framework, written in C++, was designed to simplify game development. -The advantages of \gls{sfml} are: -\begin{itemize} - \item Object-oriented design is provided since it is written in C++. - \item A built-in 2D renderer is available for ease of use. - \item A built-in audio system is included. - \item Cross-platform support is available for Linux, Windows, and macOS. - \item Networking capabilities are provided for multiplayer or networked - applications. -\end{itemize} - -The disadvantages of \gls{sfml} are: -\begin{itemize} - \item The 2D rendering engine may experience performance issues in large-scale - games. - \item The community is smaller compared to \gls{sdl2}. - \item No native 3D support is provided. - \item Not all image formats are supported. -\end{itemize} +\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} -- cgit v1.2.3 From 5d13bc5999c4abc51b9bcccf4b8b2cbd44a0193c Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Wed, 18 Sep 2024 20:55:13 +0200 Subject: update time.txt --- time.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/time.txt b/time.txt index 9e012de..509ed5b 100644 --- a/time.txt +++ b/time.txt @@ -33,6 +33,7 @@ loek: 2024-09-17 55m bugs :: cross-platform latexmk filespec loek: 2024-09-17 2h25m docs :: requirements loek: 2024-09-18 2h20m docs :: requirements loek: 2024-09-18 1h50m research :: audio +loek: 2024-09-18 1h05m integration :: PR merge max: 2024-09-02 1h project kickoff max: 2024-09-02 45m first project meeting -- cgit v1.2.3 From f63057474a461fe814458c66515e281700f296df Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Thu, 19 Sep 2024 09:52:35 +0200 Subject: fix requirement ordering in reqs2tex --- reqs.toml | 27 +++++++++------------- scripts/reqs2tex.py | 65 ++++++++++++++++++++++++++++------------------------- 2 files changed, 45 insertions(+), 47 deletions(-) diff --git a/reqs.toml b/reqs.toml index 6645ea4..35c7a96 100644 --- a/reqs.toml +++ b/reqs.toml @@ -1,15 +1,10 @@ # This is a TOML file containing all project requirements. The reqs2tex script # can be used to generate the files necessary to compile requirements.tex and # cross-reference the requirements from other documents. -# -# Note that TOML has a hash table structure, so keys used for defining -# requirement properties cannot be used for requirement IDs. The properties are: -# label, type, id, index, deleted, done, description, priority # This is the requirement cross-reference ID. Requirements can be -# (cross-)referenced from LaTeX by prefixing this ID with `req:` and -# substituting dots for colons (i.e. this requirement is referenced as -# \cref{req:audio:async-api}). +# (cross-)referenced from LaTeX by prefixing this ID with `req:` (i.e. this +# requirement is referenced as \cref{req:audio}). [audio] # Requirement type ('system' | 'user') type = 'user' @@ -25,10 +20,10 @@ background music, while simultaniously playing sound effects. # is a list of strings, each item is treated as the ID of another requirement, # and the references are checked before LaTeX runs. done = [ - 'audio.async-api', - 'audio.handle', - 'audio.stream-mix', - 'audio.volume', + 'audio:async-api', + 'audio:handle', + 'audio:stream-mix', + 'audio:volume', ] #done = 'When I feel like it' # Requirements that are no longer applicable should set `deleted` to `true`. @@ -36,7 +31,7 @@ done = [ # different document revisions. #deleted = true -[audio.async-api] +[audio:async-api] type = 'system' priority = 'must' description = ''' @@ -44,7 +39,7 @@ The public audio \gls{api} supports starting audio samples asynchronously (i.e.~fire and forget). ''' -[audio.handle] +[audio:handle] type = 'system' priority = 'must' description = ''' @@ -52,14 +47,14 @@ The public audio \gls{api} allows the game programmer to control (i.e.~play, pause, resume and stop) audio samples after they are created/initialized. ''' -[audio.stream-mix] +[audio:stream-mix] type = 'system' priority = 'must' description = ''' The audio system supports playing multiple audio streams simultaniously. ''' -[audio.volume] +[audio:volume] type = 'system' priority = 'must' description = ''' @@ -67,7 +62,7 @@ The public audio \gls{api} allows the game programmer to control the volume of audio samples. ''' -[aux.license] +[aux:license] type = 'system' priority = 'must' description = ''' diff --git a/scripts/reqs2tex.py b/scripts/reqs2tex.py index e5f063d..1863b0d 100755 --- a/scripts/reqs2tex.py +++ b/scripts/reqs2tex.py @@ -1,9 +1,9 @@ #!/bin/python3 -import sys, tomllib, tex +import sys, tomllib, tex, re from enum import StrEnum def label2ref(*labels): - return ",".join(["req:" + label.replace('.', ':') for label in labels]) + return ",".join(["req:" + label for label in labels]) class KEY(StrEnum): LABEL = 'label' @@ -25,27 +25,6 @@ class REQ_PRIORITY(StrEnum): COULD = 'could' WONT = 'will not' -def flatten(data): - out = [] - for key, value in data.items(): - # this item is a requirement - if key == KEY.DESCRIPTION: - out.append(data) - - # skip over reserved keys - if key in KEY: continue - - # recursively flatten other requirements - items = flatten(value) - # and prefix them with the current key - for item in items: - if KEY.LABEL in item: - item[KEY.LABEL] = f"{key}.{item[KEY.LABEL]}" - else: - item[KEY.LABEL] = f"{key}" - out += items - return out - id_counter = 0 def make_id(item): global id_counter @@ -79,8 +58,7 @@ def sanitize(item, ids): die("definition of done includes unknown requirement(s)") item[KEY.DONE] = tex.cmd('Cref', label2ref(*item[KEY.DONE])) -def convert(data): - reqs = flatten(data) +def convert(reqs): all_ids = [item[KEY.LABEL] for item in reqs] index = 0 for item in reqs: @@ -94,6 +72,9 @@ def convert(data): # skip deleted requirements (but process for make_id) reqs = [item for item in reqs if item[KEY.DELETED] == False] + # sort by label + reqs = sorted(reqs, key=lambda req: req[KEY.LABEL]) + return reqs def fmt_aux(data): @@ -145,20 +126,42 @@ def fmt_tex(data): ) return out +def tomlload(content): + # replace requirement labels with temp value + label_map = dict() + label_idx = 0 + lines = content.split("\n") + for index, line in enumerate(lines): + match = re.search(r"^\s*\[(.+)\]", line) + if match is None: continue + lines[index] = f"[{label_idx}]" + label_map[str(label_idx)] = match.group(1) + label_idx += 1 + content = "\n".join(lines) + + # load TOML and replace temporary labels with real labels + data_dict = tomllib.loads(content) + data_list = [] + for key, value in data_dict.items(): + value[KEY.LABEL] = label_map[key] + data_list.append(value) + + return data_list + def main(input_file): - data = {} - with open(input_file, "rb") as file: - data = tomllib.load(file) + data = [] + with open(input_file, "r") as file: + data = tomlload(file.read()) - requirements = convert(data) + items = convert(data) output_aux = input_file.removesuffix(".toml") + ".aux" with open(output_aux, "w+") as file: - file.write(fmt_aux(requirements)) + file.write(fmt_aux(items)) output_tex = input_file.removesuffix(".toml") + ".tex" with open(output_tex, "w+") as file: - file.write(fmt_tex(requirements)) + file.write(fmt_tex(items)) if __name__ == "__main__": if len(sys.argv) != 2: -- cgit v1.2.3 From 43597e2e405276868aac640175e50931513a1ae0 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Thu, 19 Sep 2024 09:53:21 +0200 Subject: update time.txt --- time.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/time.txt b/time.txt index 509ed5b..afbfa38 100644 --- a/time.txt +++ b/time.txt @@ -34,6 +34,7 @@ loek: 2024-09-17 2h25m docs :: requirements loek: 2024-09-18 2h20m docs :: requirements loek: 2024-09-18 1h50m research :: audio loek: 2024-09-18 1h05m integration :: PR merge +loek: 2024-09-19 30m docs :: requirements max: 2024-09-02 1h project kickoff max: 2024-09-02 45m first project meeting -- cgit v1.2.3 From e99bf20eff8eb26a5b6f5ec31b7ba1dfc6480931 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Thu, 19 Sep 2024 12:20:58 +0200 Subject: update time.txt --- time.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/time.txt b/time.txt index afbfa38..1566870 100644 --- a/time.txt +++ b/time.txt @@ -35,6 +35,7 @@ loek: 2024-09-18 2h20m docs :: requirements loek: 2024-09-18 1h50m research :: audio loek: 2024-09-18 1h05m integration :: PR merge loek: 2024-09-19 30m docs :: requirements +loek: 2024-09-19 15m project meeting max: 2024-09-02 1h project kickoff max: 2024-09-02 45m first project meeting -- cgit v1.2.3 From 6655651c11bafde04122a451f35ed4bb9ed1808f Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Thu, 19 Sep 2024 14:51:47 +0200 Subject: update time.txt --- time.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/time.txt b/time.txt index 1566870..5f07bac 100644 --- a/time.txt +++ b/time.txt @@ -36,6 +36,8 @@ loek: 2024-09-18 1h50m research :: audio loek: 2024-09-18 1h05m integration :: PR merge loek: 2024-09-19 30m docs :: requirements loek: 2024-09-19 15m project meeting +loek: 2024-09-19 1h30m project meeting +loek: 2024-09-19 45m project meeting max: 2024-09-02 1h project kickoff max: 2024-09-02 45m first project meeting -- cgit v1.2.3 From b5ad864b5f020a73e4e0a068302cd22209f01fbb Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Thu, 19 Sep 2024 17:27:21 +0200 Subject: remove version from documents --- contributing.md | 4 ---- latexmkrc | 2 +- meta.tex | 1 - plan.tex | 8 -------- projdoc.cls | 11 ++++++++--- 5 files changed, 9 insertions(+), 17 deletions(-) diff --git a/contributing.md b/contributing.md index c11c834..db58388 100644 --- a/contributing.md +++ b/contributing.md @@ -2,10 +2,6 @@ This document is an extension of the [crêpe engine contribution guidelines][crepe-engine-contrib]. Rules in this document override those in the other document. -# Versioning - -- TODO: discuss w/ group - # Code style - Indent using tabs diff --git a/latexmkrc b/latexmkrc index 880f859..d2c3cdc 100644 --- a/latexmkrc +++ b/latexmkrc @@ -2,7 +2,7 @@ use File::Spec::Functions; -$pdflatex = "xelatex --interaction=nonstopmode %O %S"; +$pdflatex = "xelatex --interaction=nonstopmode --shell-escape %O %S"; $pdf_mode = 1; $dvi_mode = 0; $postscript_mode = 0; diff --git a/meta.tex b/meta.tex index cad4b81..db7c7b1 100644 --- a/meta.tex +++ b/meta.tex @@ -1,6 +1,5 @@ \organization{Avans University of Applied Sciences} \project{Project cr\^epe} -\version{0.0} \author{% Loek Le Blansch\and% Wouter Boerenkamps\and% diff --git a/plan.tex b/plan.tex index 076ce11..6ebd73a 100644 --- a/plan.tex +++ b/plan.tex @@ -1,15 +1,7 @@ \documentclass{projdoc} \input{meta.tex} -% @Jaro: Zie hieronder -% Version 0.0 seems not right -% I'm also missing a 'version table' -% Shall we use this version system?: -% Version numbers after the comma indicate an interim version and version numbers -% before the comma indicate versions ready for publication - \title{Project Plan} -\version{0.1} \begin{document} \tablestables diff --git a/projdoc.cls b/projdoc.cls index fe6317b..ee94835 100644 --- a/projdoc.cls +++ b/projdoc.cls @@ -164,8 +164,6 @@ \def\project#1{\def\@project{#1}} \let\@organization\relax \def\organization#1{\def\@organization{#1}} -\let\@version\relax -\def\version#1{\def\@version{#1}} \def\@maketitle{% \centering% \parskip=0pt% @@ -195,8 +193,15 @@ }% \vfill\flushright% \par{% - \par{\strut{}Version \@version\strut}% \par{\strut\@date\strut}% + \begingroup% + \endlinechar=\m@ne\everyeof{\noexpand}% + \edef\x{% + \endgroup% + \def\noexpand\commit{\@@input|"git rev-parse --short HEAD" }% + }% + \x% + \par{\strut\footnotesize({\ttfamily\commit})\strut}% }% \par\vspace*{2in}% } -- cgit v1.2.3 From 41ac21680ef13e2db543ff56728ecffe504d6850 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Thu, 19 Sep 2024 17:27:51 +0200 Subject: update time.txt --- time.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/time.txt b/time.txt index 5f07bac..165e927 100644 --- a/time.txt +++ b/time.txt @@ -38,6 +38,7 @@ loek: 2024-09-19 30m docs :: requirements loek: 2024-09-19 15m project meeting loek: 2024-09-19 1h30m project meeting loek: 2024-09-19 45m project meeting +loek: 2024-09-19 15m docs :: remove versioning max: 2024-09-02 1h project kickoff max: 2024-09-02 45m first project meeting -- cgit v1.2.3