diff options
| -rw-r--r-- | .vscode/settings.json | 4 | ||||
| -rw-r--r-- | contributing.md | 55 | ||||
| -rw-r--r-- | glossary.bib | 30 | ||||
| -rw-r--r-- | latexmkrc | 45 | ||||
| -rw-r--r-- | projdoc.cls | 42 | ||||
| -rw-r--r-- | readme.md | 15 | ||||
| -rw-r--r-- | research.tex | 207 | ||||
| -rw-r--r-- | style.md | 25 | ||||
| -rw-r--r-- | time.txt | 17 | ||||
| -rwxr-xr-x | time2tex.py | 2 |
10 files changed, 414 insertions, 28 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/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/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..503f049 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,13 @@ \RequirePackage{cleveref} \RequirePackage{adjustbox} \RequirePackage{xparse} +\RequirePackage{biblatex} +\RequirePackage{glossaries} +\RequirePackage{glossaries-extra} \RequirePackage{ifdraft} \RequirePackage{enumitem} \RequirePackage{subcaption} +\RequirePackage{multicol} % font style \setmainfont{TeX Gyre Schola} @@ -171,18 +187,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 +208,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. + @@ -1,4 +1,5 @@ -# <who>: <when> <how long> <what> +loek: 2024-09-02 1h project meeting :: project kickoff +loek: 2024-09-02 45m project meeting loek: 2024-09-02 1h4m repository scaffolding loek: 2024-09-03 25m repository scaffolding loek: 2024-09-03 1h30m repository scaffolding :: engine repository, unit testing @@ -10,12 +11,22 @@ 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 +max: 2024-09-02 1h project meeting :: project kickoff +max: 2024-09-02 45m project meeting max: 2024-09-04 1h30m installing and configuring latex max: 2024-09-04 2h reading project info max: 2024-09-05 20m discussing GitHub with Jaro max: 2024-09-05 1h30m first group meeting +wouter: 2024-09-02 1h project meeting :: project kickoff +wouter: 2024-09-02 45m project meeting wouter: 2024-09-03 1h reading project info wouter: 2024-09-04 1h setting up working environment wouter: 2024-09-04 1h30m researching 3rd party tools @@ -23,6 +34,8 @@ wouter: 2024-09-05 1h30m first group meeting wouter: 2024-09-05 20m setting up research document wouter: 2024-09-05 1h researching game enigne +niels: 2024-09-02 1h project meeting :: project kickoff +niels: 2024-09-02 45m project meeting niels: 2024-09-03 1h reading project info niels: 2024-09-04 30m validation app ideas niels: 2024-09-04 2h setting up vimtex on neovim @@ -30,7 +43,7 @@ niels: 2024-09-04 1h researching different code styles and c++ guidelines niels: 2024-09-05 1h30m first group meeting niels: 2024-09-06 2h added c++ guidelines in the contributing.md -jaro: 2024-09-02 1h project kickoff +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 diff --git a/time2tex.py b/time2tex.py index 1d0cd90..fe3091f 100755 --- a/time2tex.py +++ b/time2tex.py @@ -87,7 +87,7 @@ def fmt_weekly_overview(times): # begin table out += r"\begin{table}\centering" out += f"\\begin{{tabular}}{{l{'r@{~}l' * len(members)}@{{\\qquad}}r}}\\toprule" - out += r"\textbf{Week\#}" + out += r"\textbf{\#}" for member in members: out += f"&\\textbf{{{member}}}&" out += r"&\textbf{Subtotal}\\\midrule{}" |