diff options
| -rw-r--r-- | .vscode/settings.json | 4 | ||||
| -rw-r--r-- | comparison.sty | 80 | ||||
| -rw-r--r-- | contributing.md | 55 | ||||
| -rw-r--r-- | example.tex | 27 | ||||
| -rw-r--r-- | glossary.bib | 30 | ||||
| -rw-r--r-- | latexmkrc | 45 | ||||
| -rw-r--r-- | projdoc.cls | 43 | ||||
| -rw-r--r-- | readme.md | 15 | ||||
| -rw-r--r-- | research.tex | 207 | ||||
| -rw-r--r-- | style.md | 25 | ||||
| -rw-r--r-- | time.txt | 14 |
11 files changed, 519 insertions, 26 deletions
diff --git a/.vscode/settings.json b/.vscode/settings.json index 72f0e6b..25effcc 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,4 +1,8 @@ { + "editor.wordWrap": "wordWrapColumn", + "editor.wrappingIndent": "same", + "editor.wordWrapColumn": 85, + "files.trimTrailingWhitespace": true, "latex-workshop.latex.recipe.default": "latexmk", "latex-workshop.latex.tools": [ { diff --git a/comparison.sty b/comparison.sty new file mode 100644 index 0000000..d10f95f --- /dev/null +++ b/comparison.sty @@ -0,0 +1,80 @@ +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{comparison}[2024-01-19 package comparison] + +\RequirePackage{booktabs} +\RequirePackage{etoolbox} +\RequirePackage{tabularx} +\RequirePackage{environ} +\RequirePackage{enumitem} + +% comparison environment, usage: +% +% \begin{comparison} +% \pro{reason why thing is good} +% \pro{...} +% \con{reason why thing is bad} +% \con{...} +% \end{comparison} +% +% output: +% +% Pros (2) Cons (2) +% ---------------------------------------------------------- +% - reason why thing is good - reason why thing is bad +% - ... - ... +% + +\newcounter{pro-count} +\newcounter{pro-index} +\newcounter{con-count} +\newcounter{con-index} +\newcounter{cmp-count} +\newcounter{cmp-index} +\NewEnviron{comparison}{% + \par% + \setcounter{pro-count}{0}% + \newcommand{\pro}[1]{% + \stepcounter{pro-count}% + \csdef{pro-\the\value{pro-count}}{##1}% + }% + \setcounter{con-count}{0}% + \newcommand{\con}[1]{% + \stepcounter{con-count}% + \csdef{con-\the\value{con-count}}{##1}% + }% + \BODY% + \def\spacing{3mm}% + \newcommand{\halfbox}[1]{% + \begin{minipage}[t]{\dimexpr(\linewidth - \spacing) / 2\relax}% + ##1% + \end{minipage}% + }% + \begin{minipage}{\linewidth}% + \halfbox{\strut\centering\textsc{Benefits}~(\the\value{pro-count})\strut}% + \hfill% + \halfbox{\strut\centering\textsc{Drawbacks}~(\the\value{con-count})\strut}% + \par% + \vspace*{\dimexpr-\parskip-0.5\baselineskip\relax}% + \noindent\rule{\linewidth}{0.66pt}\par% + \vspace*{\dimexpr-\parskip\relax}% + \halfbox{% + \begin{itemize}[leftmargin=5mm]% + \setcounter{pro-index}{0}% + \whileboolexpr{test{\ifnumcomp{\value{pro-index}}{<}{\value{pro-count}}}}{% + \stepcounter{pro-index}% + \item \csuse{pro-\the\value{pro-index}}% + }% + \end{itemize}% + }\hfill\halfbox{% + \begin{itemize}[leftmargin=5mm]% + \setcounter{con-index}{0}% + \whileboolexpr{test{\ifnumcomp{\value{con-index}}{<}{\value{con-count}}}}{% + \stepcounter{con-index}% + \item \csuse{con-\the\value{con-index}}% + }% + \end{itemize}% + }% + \end{minipage}% + \par% +} + diff --git a/contributing.md b/contributing.md index 770d02e..c11c834 100644 --- a/contributing.md +++ b/contributing.md @@ -10,12 +10,17 @@ other document. - Indent using tabs - Wrap long lines at column 80 -- Diacritical marks should be represented in ASCII using LaTeX syntax instead - of using UTF-8 (i.e. `fa\c{c}ade` instead of `façade`) +- ASCII only (LaTeX syntax should be used instead of UTF-8, i.e. `fa\c{c}ade` + instead of `façade`, `---` instead of `—`) - Images should be placed in the img/ folder - Labels and bibliography keys should only consist of characters from the following set: `[a-z0-9:-]` (lower-case, numbers, colon, dash). -- Quotes are opened with the tilde (<code>`</code>) +- Both single and double quotes are opened using backtick(s) + (<code>`</code>) and closed using single quote(s) (`'`), i.e. + <code>``like this''</code> or <code>`this'</code> +- Only environments indent the LaTeX source code +- Insert a non-breaking space (`~`) after (Latin) abbreviations such as "i.e." + or "e.g.". Never place a comma after either of these. # Banned practices @@ -27,7 +32,7 @@ other document. command should be used instead. - **Using `\href`** - Add the source in sources.bib and cite this source instead. + Add the source in [sources.bib](#sources) and cite this source instead. - **Using `\textbf` or `\textit` to emphasize** Use `\emph`, single quotes or an em dash (`---`) instead. @@ -51,21 +56,47 @@ Please use prefixes to 'namespace' `\label`s: |Sections|`sec:`| |List items (i.e. `enumerate`/`itemize`)|`item:`| +These items can be referenced using the `\cref` command. + ## Sources Bibliography entries work with a similar label system (usually called *keys*). Since these exist in a registry separate from `\label` entries, these do not -need to be prefixed. +need to be prefixed. All sources are stored in [sources.bib](./sources.bib). +There is a very helpful [cheat sheet][biblatex-cheat-sheet] online that +showcases different entry types and their fields. -For consistency, the following format is preferred: `authority:topic`. The -`authority` part refers to a company, website or author, and `topic` refers to -a title, chip model number, etc. depending on the type of document being +For consistency, the following format for keys is preferred: `authority:topic`. +The `authority` part refers to a company, website or author, and `topic` refers +to a title, chip model number, etc. depending on the type of document being referenced. -<!-- -TODO -- Cross-references and citations should be handled using cleveref ---> +## Glossary + +Glossary entries are stored in [glossary.bib](./glossary.bib). This file has +the same structure as the bibliography, but with different key types: + +|type|usage| +|-|-| +|`@abbreviation`|Abbreviations (long version inserted on first occurrence)| +|`@acronym`|Acronyms (long version only in glossary)| +|`@entry`|Generic entries / words| + +The keys in the glossary do not have to be prefixed, and should be short as +they should be inserted frequently. Glossary entries can be used with the +following commands: + +|command|usage| +|-|-| +|`\gls{<key>}`|regular| +|`\glspl{<key>}`|plural| +|`\Gls{<key>}`|capitalized (at start of sentence)| +|`\Glspl{<key>}`|capitalized plural| + +> [!NOTE] +> Glossary entries should not be inserted in figure captions or section +> headings! [crepe-engine-contrib]: https://github.com/lonkaars/crepe/blob/master/contributing.md +[biblatex-cheat-sheet]: https://tug.ctan.org/info/biblatex-cheatsheet/biblatex-cheatsheet.pdf diff --git a/example.tex b/example.tex index 8525973..ce45f6f 100644 --- a/example.tex +++ b/example.tex @@ -108,7 +108,7 @@ The \codeinline{blockcode} environment can be used to insert a code block: This is all included verbatim: \verb|asdf| \ $%!(*@#&)$ \end{blockcode} -\subsection{Lists} +\subsection{Information dumps} Unordered (bullet) list: @@ -136,9 +136,34 @@ Numbered list: (See \cref{item:enum-nest-ref}) +Description: + +\begin{description} + \item[Item one] description of item one + \item[Item two] description of item two + \item[Item three] ... +\end{description} + +\subsection{Comparisons} + +\begin{comparison} + \pro{Good thing} + \con{Bad thing} + \pro{Good thing 2} + \con{Bad thing 2} +\end{comparison} + \subsection{Citations} Citations are inserted using the \codeinline{\autocite} command \autocite{rfc:3339}. +The bibliography is automatically printed after \codeinline{\end{document}}. + +\subsection{Glossary} + +Glossary entries can be inserted using the \codeinline{\gls} commands. Example: +``\Gls{sdl2} handles \glspl{hid} as well!''. In following occurrences of acronyms, +only their short form is printed: `\gls{sdl2}' and `\gls{hid}'. All of these link to +the glossary that is automatically printed after \codeinline{\end{document}}. \end{document} diff --git a/glossary.bib b/glossary.bib new file mode 100644 index 0000000..4d02e4a --- /dev/null +++ b/glossary.bib @@ -0,0 +1,30 @@ +@abbreviation{ecs, + short = {ECS}, + long = {Entity-Component System}, +} + +@abbreviation{hid, + short = {HID}, + long = {Human Interface Device}, +} + +@abbreviation{sdl2, + short = {SDL2}, + long = {Simple DirectMedia Layer}, +} + +@abbreviation{sfml, + short = {SFML}, + long = {Simple and Fast Multimedia Library}, +} + +@entry{opengl, + name = {OpenGL}, + description = {Open-source graphics library}, +} + +@entry{d3d, + name = {Direct3D}, + description = {Graphics library developed by \hbox{Microsoft}}, +} + @@ -2,3 +2,48 @@ $pdflatex = "xelatex %O %S"; $pdf_mode = 1; $dvi_mode = 0; $postscript_mode = 0; + +# https://tex.stackexchange.com/questions/400325/latexmkrc-for-bib2gls +add_cus_dep('glo', 'gls', 0, 'run_makeglossaries'); +add_cus_dep('acn', 'acr', 0, 'run_makeglossaries'); +add_cus_dep('aux', 'glstex', 0, 'run_bib2gls'); + +sub run_makeglossaries { + if ( $silent ) { + system "makeglossaries -q '$_[0]'"; + } else { + system "makeglossaries '$_[0]'"; + }; +} + +sub run_bib2gls { + if ( $silent ) { + my $ret = system "bib2gls --silent --group '$_[0]'"; + } else { + my $ret = system "bib2gls --group '$_[0]'"; + }; + my ($base, $path) = fileparse( $_[0] ); + if ($path && -e "$base.glstex") { + rename "$base.glstex", "$path$base.glstex"; + } + # Analyze log file. + local *LOG; + $LOG = "$_[0].glg"; + if (!$ret && -e $LOG) { + open LOG, "<$LOG"; + while (<LOG>) { + if (/^Reading (.*\.bib)\s$/) { + rdb_ensure_file( $rule, $1 ); + } + } + close LOG; + } + return $ret; +} + +push @file_not_found, '^Package .* No file `([^\\\']*)\\\''; +push @generated_exts, 'glo', 'gls', 'glg'; +push @generated_exts, 'acn', 'acr', 'alg'; +$clean_ext .= ' %R.ist %R.xdy'; +$clean_ext .= ' bbl run.xml'; + diff --git a/projdoc.cls b/projdoc.cls index c6abaca..388f901 100644 --- a/projdoc.cls +++ b/projdoc.cls @@ -14,6 +14,18 @@ \PassOptionsToPackage{nosort}{cleveref} \PassOptionsToPackage{nameinlink}{cleveref} \PassOptionsToPackage{obeyspaces}{url} +\PassOptionsToPackage{toc=false}{glossaries} +\PassOptionsToPackage{record}{glossaries-extra} +\PassOptionsToPackage{ + backend=biber, + bibencoding=utf8, + style=iso-numeric, + % Technically, Avans University of Applied Sciences requires that we always use APA + % style references, but this often results in ugly citations when working with + % technical or online resources. At the end of the day, the bibliography is there + % to prove we didn't plagiarize or make shit up, so ISO 690 is *probably* fine. + autocite=plain, +}{biblatex} % frequently used packages \RequirePackage{geometry} @@ -38,9 +50,14 @@ \RequirePackage{cleveref} \RequirePackage{adjustbox} \RequirePackage{xparse} +\RequirePackage{biblatex} +\RequirePackage{glossaries} +\RequirePackage{glossaries-extra} \RequirePackage{ifdraft} \RequirePackage{enumitem} \RequirePackage{subcaption} +\RequirePackage{multicol} +\RequirePackage{comparison} % ./comparison.sty % font style \setmainfont{TeX Gyre Schola} @@ -171,18 +188,14 @@ \makeatother % bibliography -\usepackage[ - backend=biber, - bibencoding=utf8, - style=iso-numeric, - % Technically, Avans University of Applied Sciences requires that we always use APA - % style references, but this often results in ugly citations when working with - % technical or online resources. At the end of the day, the bibliography is there - % to prove we didn't plagiarize or make shit up, so ISO 690 is *probably* fine. - autocite=plain, -]{biblatex} \addbibresource{sources.bib} +% glossary +\GlsXtrLoadResources[ + src={./glossary.bib}, + selection={recorded and deps and see}, +] + % default document header/trailer \makeatletter \def\projdoc@header{ @@ -196,8 +209,16 @@ \newbool{projdoc@cited} \apptocmd{\abx@aux@cite}{\global\booltrue{projdoc@cited}}{}{} \def\projdoc@trailer{ - % end with bibliography (if citations used) + % bibliography (if citations used) \ifbool{projdoc@cited}{\printbibliography}{}% + % glossary + \ifcsundef{printunsrtglossary}{}{% + \section*{Glossary}% + \begin{multicols}{2}% + \renewcommand{\glossarysection}[2][]{}% + \printunsrtglossary% + \end{multicols}% + }% } \AtBeginDocument{\projdoc@header} \AtEndDocument{\projdoc@trailer} @@ -10,9 +10,22 @@ Please see [style.md](./style.md) for writing style and - A `latexmkrc` file is provided for copmilation with `latexmk`. The documents should also compile under [Visual Studio Code][vscode] using the [LaTeX Workshop extension][latexworkshop], as well as [VimTeX][vimtex]. +- A [makefile](./makefile) is used to compile other files (e.g. plantuml + diagrams, [time report](#time-report)) - These documents use fonts loaded using `fontspec`, please see [style.md](./style.md) for download links. -- A `makefile` is provided for compiling other files (e.g. plantuml diagrams) + +## Time report + +The time report document includes generated LaTeX code which can be compiled +from [time.txt](./time.txt) using [time2tex.py](./time2tex.py). The +[makefile](./makefile) includes a rule that does this, so `make timerep.pdf` +should be used to compile this document specifically. + +## Requirements + +TODO: how to store + cross-reference requirements w/o extra latex compilation +runs [vscode]: https://code.visualstudio.com [latexworkshop]: https://marketplace.visualstudio.com/items?itemName=James-Yu.latex-workshop diff --git a/research.tex b/research.tex new file mode 100644 index 0000000..ca2afed --- /dev/null +++ b/research.tex @@ -0,0 +1,207 @@ +\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[\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{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. Entt is +an example of an \gls{ecs}. +% TODO: ref?entt + +\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. + +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} + +\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. + +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} + +\subsubsection{Audio} + +for audio some options could be: FMOD, Wwise, or iirKlang + +\subsection{Conclusion} + +\section{Gameloop/resource manager} + +\subsection{Introduction} + +\subsection{Findings} + +\subsection{Conclusion} + +\section{Rendering} + +\subsection{Introduction} + +\subsection{Findings} + +\subsection{Conclusion} + +\section{Event manager} + +\subsection{Introduction} + +\subsection{Findings} + +\subsection{Conclusion} + +\section{Memory/debugging} + +\subsection{Introduction} + +\subsection{Findings} + +\subsection{Conclusion} + +\section{Physics/scripting} + +\subsection{Introduction} + +\subsection{Findings} + +\subsection{Conclusion} + +\section{Conclusion} + +\section{Gameobjects/components} + +\subsection{Introduction} + +\subsection{Findings} + +\subsection{Conclusion} + +\section{Conclusion} + +\end{document} @@ -1,3 +1,9 @@ +This document contains requirements for all project documentation. Specific +LaTeX commands and LaTeX source style requirements are detailed in +[contributing.md](./contributing.md), and [example.tex](./example.tex) contains +a number of frequently used snippets that may be used as a cheat-sheet style +reference. + # Fonts The documents use the following fonts. All of these are free and open source, @@ -23,7 +29,9 @@ workshop and VimTeX. # Spelling -All documentation is written in U.S. English +- All documentation is written in U.S. English +- Section headers are in sentence case (i.e. only the first word and proper + nouns are capitalized) # Grammar @@ -51,3 +59,18 @@ converted to PDF (e.g. using `svg2pdf` on linux). Raster images should only be used when the source is already in a raster format (e.g. for photos) or when otherwise impractical. +# References + +- When a library or piece of software is introduced in a document, reference + the project homepage using the bibliography. +- Direct quotations or paraphased text must be cited. +- Acronyms, abbreviations and jargon reference the glossary. +- All figures and tables must be referenced in the body text. Don't write + paragraphs that 'lead up' to figures, as this forces LaTeX to not break the + page between the paragraph and figure. + +# Document structure + +- Use `\section`, `\subsection`, `\subsubsection` and `\paragraph` to insert + headings. + @@ -11,6 +11,14 @@ loek: 2024-09-05 15m repository scaffolding :: additional latex contributing gui loek: 2024-09-05 1h40m project meeting loek: 2024-09-05 1h24m time report script loek: 2024-09-06 55m time report script +loek: 2024-09-09 30m feedback :: niels code style guide +loek: 2024-09-09 45m review :: wouter research PR#5 +loek: 2024-09-09 25m documentation style guide +loek: 2024-09-10 1h55m project meeting +loek: 2024-09-10 25m briefing :: watch bob videos +loek: 2024-09-10 5m docs :: update readme +loek: 2024-09-10 12m docs :: add comparison package and more example latex code +loek: 2024-09-10 30m project meeting max: 2024-09-02 1h project kickoff max: 2024-09-02 45m first project meeting @@ -47,9 +55,15 @@ niels: 2024-09-06 2h added c++ guidelines in the contributing.md jaro: 2024-09-02 1h project meeting :: project kickoff jaro: 2024-09-02 45m project meeting jaro: 2024-09-02 1h45m scrumboard(miro), installing dependencies +jaro: 2024-09-03 1h project lesson jaro: 2024-09-04 4h15m latex environment, code environment and project plan jaro: 2024-09-05 2h preparing meeting, project plan, discussing github with max jaro: 2024-09-05 1h30m project meeting jaro: 2024-09-05 1h documentatie review and improving environment +jaro: 2024-09-06 30m weekly update +jaro: 2024-09-09 1h project plan +jaro: 2024-09-10 1h preparing meeting and project plan +jaro: 2024-09-10 1h30m project meeting +jaro: 2024-09-10 1h project disussing research # vim:ft=cfg |