fennec-org/fennec
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

- Update TOC in README.md

Browse Source
This commit is contained in:
Medusa Slockbower
2025-08-17 10:03:43 -04:00
parent 73041e994d
commit 5252ba84c9
1 changed files with 79 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

146
README.md
View File

@@ -10,15 +10,20 @@
## Table of Contents ## Table of Contents
1. [Introduction](#introduction) <!-- TOC -->
1. [Coding Standards](#coding-standards) * [Table of Contents](#table-of-contents)
2. [Building from Source](#building-from-source) * [Introduction](#introduction)
1. [Building from Terminal](#building-from-terminal) * [Coding Standards](#coding-standards)
2. [Building on Windows](#building-on-windows) * [Building from Source](#building-from-source)
3. [Running the Test Suite](#running-the-test-suite) * [Building from Terminal](#building-from-terminal)
4. [Usage](#usage) * [Debian](#debian)
5. [Contribution](#contribution) * [Building on Windows](#building-on-windows)
6. [Documentation](./documentation.html) * [Running the Test Suite](#running-the-test-suite)
* [Usage](#usage)
* [Licensing](#licensing)
* [Contribution](#contribution)
<!-- TOC -->
<br> <br>
<br> <br>
@@ -27,8 +32,8 @@
<a id="introduction"></a> <a id="introduction"></a>
## Introduction ## Introduction
&ensp; fennec is designed to be a general purpose, educational game engine. fennec &ensp; fennec is designed to be a general purpose, educational game engine. fennec
may be used through the provided editor application, or as a standalone library to may be used through the provided editor application, or as a standalone library to
link against your application. link against your application.
@@ -38,7 +43,7 @@ link against your application.
<a id="coding-standards"></a> <a id="coding-standards"></a>
### Coding Standards ### Coding Standards
Interfacing with the API in C++ follows the [GNU Coding Standards](https://www.gnu.org/prep/standards/html_node/index.html). Interfacing with the API in C++ follows the [GNU Coding Standards](https://www.gnu.org/prep/standards/html_node/index.html).
Some main areas where the engine strays from the GNU standard includes the following: Some main areas where the engine strays from the GNU standard includes the following:
* [Section 4.7, Standards for Graphical Interfaces](https://www.gnu.org/prep/standards/html_node/Graphical-Interfaces.html). * [Section 4.7, Standards for Graphical Interfaces](https://www.gnu.org/prep/standards/html_node/Graphical-Interfaces.html).
@@ -46,23 +51,23 @@ Some main areas where the engine strays from the GNU standard includes the follo
- [Section 6.1, GNU Manuals](https://www.gnu.org/prep/standards/html_node/GNU-Manuals.html) - [Section 6.1, GNU Manuals](https://www.gnu.org/prep/standards/html_node/GNU-Manuals.html)
fennec does not use Texinfo and instead uses Doxygen. Otherwise, it follows the other standards of this section. fennec does not use Texinfo and instead uses Doxygen. Otherwise, it follows the other standards of this section.
* [Section 7, The Release Process](https://www.gnu.org/prep/standards/html_node/Managing-Releases.html) * [Section 7, The Release Process](https://www.gnu.org/prep/standards/html_node/Managing-Releases.html)
fennec follows most of the conventions in this section, however the build system used is CMake and not fennec follows most of the conventions in this section, however the build system used is CMake and not
Makefile. CMake, although overwhelming at first, is much more friendly to those who are learning build systems for the first time. Makefile. CMake, although overwhelming at first, is much more friendly to those who are learning build systems for the first time.
<br> <br>
fennec Standards: fennec Standards:
* As per the GNU standard, macros should be `SCREAMING_SNAKE_CASE`. Additionally, Macros should be preceded by * As per the GNU standard, macros should be `SCREAMING_SNAKE_CASE`. Additionally, Macros should be preceded by
`<APP_NAME>_`. Macros that wrap C-Style functions may use normal `snake_case`. `<APP_NAME>_`. Macros that wrap C-Style functions may use normal `snake_case`.
- Header Guards should be implemented using `#ifndef`, `#define`, and `#endif` for portability. - Header Guards should be implemented using `#ifndef`, `#define`, and `#endif` for portability.
The naming convention for Header Guards is as follows: `<APP_NAME>_<DIRECTORY_PATH>_<FILE_NAME>_H`. The naming convention for Header Guards is as follows: `<APP_NAME>_<DIRECTORY_PATH>_<FILE_NAME>_H`.
I.E. the engine file `fennec/lang/utility.h` has the Header Guard `FENNEC_LANG_UTILITY_H`. I.E. the engine file `fennec/lang/utility.h` has the Header Guard `FENNEC_LANG_UTILITY_H`.
* Helper Functions, in the case of classes, should be private. * Helper Functions, in the case of classes, should be private.
In the case of global functions, helpers should be placed in a similarly named file in a subdirectory and namespace In the case of global functions, helpers should be placed in a similarly named file in a subdirectory and namespace
called `detail`. Helper functions should be documented with C-Style comments, however it is not necessary to provide called `detail`. Helper functions should be documented with C-Style comments, however it is not necessary to provide
Doxygen documentation. Doxygen documentation.
- **DO NOT USE C++ EXCEPTIONS** they will not be supported because they are shit.<sup>[[1]](#f1)</sup> - **DO NOT USE C++ EXCEPTIONS** they will not be supported because they are shit.<sup>[[1]](#f1)</sup>
@@ -72,19 +77,19 @@ fennec Standards:
<br><br> <br><br>
<a id="f1"></a> <a id="f1"></a>
<sup>[1]</sup> If we were to use the exception paradigm for all erroneous behaviour, we couldn't guarantee <sup>[1]</sup> If we were to use the exception paradigm for all erroneous behaviour, we couldn't guarantee
that the state will not be corrupted when an exception is thrown. The behaviour afterward is undefined that the state will not be corrupted when an exception is thrown. The behaviour afterward is undefined
because of this, and we also don't really know when, how, or where that exception will be handled. because of this, and we also don't really know when, how, or where that exception will be handled.
The assertion paradigm is better at handling this because you are defining erroneous behaviour in the The assertion paradigm is better at handling this because you are defining erroneous behaviour in the
code and how it is handled. In a debug build we can immediately halt the program, we don't care about code and how it is handled. In a debug build we can immediately halt the program, we don't care about
the state afterward, only beforehand. Now for a release build, this is first and foremost a game engine, the state afterward, only beforehand. Now for a release build, this is first and foremost a game engine,
so we want to crash as gracefully as possible, prevent data loss, and get some debug information for it. so we want to crash as gracefully as possible, prevent data loss, and get some debug information for it.
fennec defines its own `assert` macro to be used, defining a hook in the private version of the fennec defines its own `assert` macro to be used, defining a hook in the private version of the
function. This hook is used to clean up any state information within the engine and may be used to send function. This hook is used to clean up any state information within the engine and may be used to send
immediate events to listeners so that outside functionality may decide how to handle the impending crash. immediate events to listeners so that outside functionality may decide how to handle the impending crash.
In Debug Mode there is nothing that can be done to stop the crash, as soon as the branch finishes, In Debug Mode there is nothing that can be done to stop the crash, as soon as the branch finishes,
`abort()` will be called. `abort()` will be called.
<br> <br>
@@ -104,11 +109,11 @@ There are a few reasons for this:
<a id="building-from-source"></a> <a id="building-from-source"></a>
## Building from Source ## Building from Source
&ensp; fennec uses the CMake build manager. The CMake build script provides several &ensp; fennec uses the CMake build manager. The CMake build script provides several
targets for building parts of the engine. targets for building parts of the engine.
&ensp; Using an IDE will streamline the build process for you and add additional configuration &ensp; Using an IDE will streamline the build process for you and add additional configuration
options. Eclipse, Visual Studio, and CLion provide built-in support for CMake. VSCode options. Eclipse, Visual Studio, and CLion provide built-in support for CMake. VSCode
is also a viable IDE but involves some extra setup. is also a viable IDE but involves some extra setup.
| Target | Description | | Target | Description |
@@ -139,27 +144,34 @@ is also a viable IDE but involves some extra setup.
`build.sh` provides profiles for building the main engine. Run `./build.sh --help` `build.sh` provides profiles for building the main engine. Run `./build.sh --help`
for more info. for more info.
&ensp; By default, the CMake generator used is Ninja, which requires Ninja to be installed. You can modify the &ensp; By default, the CMake generator used is Ninja, which requires Ninja to be installed. You can modify the
build scripts to use another build manager, see the [CMake documentation for available generators](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html). build scripts to use another build manager, see the [CMake documentation for available generators](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html).
&ensp; I will at no point provide official cross-compilation toolchains for fennec. However, I will provide tools for
using specific toolchains for specific platforms that necessitate this. The primary examples would be Android and iOS.
If you wish to build for Windows *and* Linux, your options are WSL or Dual Boot. I recommend Dual Boot over WSL.
#### Debian
On Debian-based distributions, you can install dependencies using the following command: On Debian-based distributions, you can install dependencies using the following command:
```shell ```shell
sudo apt install build-essential cmake ninja-build libglew-dev valgrind sudo apt install build-essential cmake ninja-build libglew-dev valgrind
git submodule update --init --recursive git submodule update --init --recursive
``` ```
for Doxygen run:
&ensp; I will at no point provide official cross-compilation toolchains for fennec. However, I will provide tools for ```shell
using specific toolchains for specific platforms that necessitate this. The primary examples would be Android and iOS. sudo apt install doxygen graphviz
If you wish to build for Windows *and* Linux, your options are WSL or Dual Boot. I recommend Dual Boot over WSL. ```
<br> <br>
<a id="building-on-windows"></a> <a id="building-on-windows"></a>
### Building on Windows ### Building on Windows
&ensp; The bash script can be run natively on Windows when WSL is enabled. You do not need to run the &ensp; The bash script can be run natively on Windows when WSL is enabled. You do not need to run the
script in WSL, simply use the "bash" command in Command Prompt or PowerShell. The script will require script in WSL, simply use the "bash" command in Command Prompt or PowerShell. The script will require
the build [dependencies](#dependencies) installed and configured to be available on the `PATH` environment variable. the build [dependencies](#dependencies) installed and configured to be available on the `PATH` environment variable.
Fore more details, [see this blog post](https://blogs.windows.com/windows-insider/2016/04/06/announcing-windows-10-insider-preview-build-14316/) for Windows Build 14316. Fore more details, [see this blog post](https://blogs.windows.com/windows-insider/2016/04/06/announcing-windows-10-insider-preview-build-14316/) for Windows Build 14316.
@@ -185,8 +197,8 @@ The value of `<profile>` may be one of the following:
<br> <br>
&ensp; If you would like to use Visual Studio without CMake, you can use the build script to generate &ensp; If you would like to use Visual Studio without CMake, you can use the build script to generate
a Visual Studio project for the source. For a list of available Visual Studio generators, [see this section](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html) a Visual Studio project for the source. For a list of available Visual Studio generators, [see this section](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html)
of the CMake docs. Running the following command will generate the Visual Studio project. of the CMake docs. Running the following command will generate the Visual Studio project.
```commandline ```commandline
@@ -201,9 +213,9 @@ cmake -G "Visual Studio 17 2022" -A x64
`test.sh` provides profiles for building the test suite and executes them. `test.sh` provides profiles for building the test suite and executes them.
&ensp; By default, the program runs in debug mode and the first failed test will throw an assertion. &ensp; By default, the program runs in debug mode and the first failed test will throw an assertion.
Any tests that involve running as an application will spawn a subprocess with a window, and give Any tests that involve running as an application will spawn a subprocess with a window, and give
a short description of the behaviour in the terminal. It will then have you confirm whether the a short description of the behaviour in the terminal. It will then have you confirm whether the
information displayed is correct. information displayed is correct.
<br> <br>
@@ -215,31 +227,31 @@ information displayed is correct.
### Licensing ### Licensing
The following content of this section is not legal advice, nor is it legally binding, and nor does it change the terms The following content of this section is not legal advice, nor is it legally binding, and nor does it change the terms
of the license. Please seek legal council if you have any concerns. of the license. Please seek legal council if you have any concerns.
&ensp; fennec is licensed under GPLv3. The primary reason for the choice of license is to dissuade corporations from modifying &ensp; fennec is licensed under GPLv3. The primary reason for the choice of license is to dissuade corporations from modifying
fennec and using it in a commercial manner. This of course does not bar them from using fennec commercially, however fennec and using it in a commercial manner. This of course does not bar them from using fennec commercially, however
it will prevent them from being able to make the derivative work proprietary. You are free to use and redistribute it will prevent them from being able to make the derivative work proprietary. You are free to use and redistribute
fennec however you wish according to the terms of the license, which does not bar you from commercializing software fennec however you wish according to the terms of the license, which does not bar you from commercializing software
based on fennec. based on fennec.
&ensp; If you wish to protect your game files, assets and generated content do not constitute a covered work and may be &ensp; If you wish to protect your game files, assets and generated content do not constitute a covered work and may be
copyrighted under a non-compliant license. Think of it in terms of using Blender to create a mesh for a game, then copyrighted under a non-compliant license. Think of it in terms of using Blender to create a mesh for a game, then
licensing that mesh under another license. licensing that mesh under another license.
Any code that is linked against fennec or uses any part is by definition a covered work must be licensed under GPLv3. Any code that is linked against fennec or uses any part is by definition a covered work must be licensed under GPLv3.
&ensp; Later down the line, I plan on implementing scripts in a manner that allows the script itself to remain proprietary. &ensp; Later down the line, I plan on implementing scripts in a manner that allows the script itself to remain proprietary.
The scripts will likely be trans-compiled to another language before being compiled to binary, but this is only an The scripts will likely be trans-compiled to another language before being compiled to binary, but this is only an
intermediate step and will be erased when no longer needed. intermediate step and will be erased when no longer needed.
&ensp; As long as you use the official editor, it will properly include licenses in project content when provided a license &ensp; As long as you use the official editor, it will properly include licenses in project content when provided a license
and the name of the license holder. Archive packs will include the license holders non-GPLv3 license in them and any and the name of the license holder. Archive packs will include the license holders non-GPLv3 license in them and any
linked code will be covered by GPLv3 under the name of the license holder. Be aware that the parts of your project linked code will be covered by GPLv3 under the name of the license holder. Be aware that the parts of your project
licensed under GPLv3 must be available upon request. licensed under GPLv3 must be available upon request.
&ensp; A release project will consist of an executable, a shared library for your code, an archive pak, and streamable assets. &ensp; A release project will consist of an executable, a shared library for your code, an archive pak, and streamable assets.
The executable and shared library are under the GPLv3 license, while the archive pak and streamable assets are under your license. The executable and shared library are under the GPLv3 license, while the archive pak and streamable assets are under your license.
It is to my discretion whether I enforce the terms of the license on a party. It is to my discretion whether I enforce the terms of the license on a party.
@@ -255,7 +267,7 @@ The following practices are more likely to get my attention and enforcement:
- Subscription-Based Sales Model - Subscription-Based Sales Model
- NFTs or Nonfungible Tokens - NFTs or Nonfungible Tokens
I encourage those who wish to commercialize derivative works crowdfund rather than use a sales model. I also ask I encourage those who wish to commercialize derivative works crowdfund rather than use a sales model. I also ask
that you kindly support me as a developer, I will set up a Buy Me a Coffee link at some point. that you kindly support me as a developer, I will set up a Buy Me a Coffee link at some point.
GPLv3 is bound by fair use; here is the clause, 17 U.S. Code § 107: GPLv3 is bound by fair use; here is the clause, 17 U.S. Code § 107:
@@ -279,23 +291,23 @@ The fact that a work is unpublished shall not itself bar a finding of fair use i
consideration of all the above factors. consideration of all the above factors.
``` ```
If you have any questions or concerns, please seek legal council. If you believe someone else has violated the terms If you have any questions or concerns, please seek legal council. If you believe someone else has violated the terms
of this license, please contact me at [mslockbo@gmail.com](mailto:mslockbo@gmail.com). of this license, please contact me at [mslockbo@gmail.com](mailto:mslockbo@gmail.com).
I am aware of Universities with Game Development programs such as DigiPen Institute of Technology and Full-Sail I am aware of Universities with Game Development programs such as DigiPen Institute of Technology and Full-Sail
University which license student work to protect them and the faculty. University which license student work to protect them and the faculty.
Champlain College does not license student projects and constitutes fair use. Champlain College does not license student projects and constitutes fair use.
I have not worked with Full-Sail University before, so I am not familiar with any of their staff members, and I will I have not worked with Full-Sail University before, so I am not familiar with any of their staff members, and I will
require legal council to consult with them which may dissuade permission to use my engine. require legal council to consult with them which may dissuade permission to use my engine.
I hold a Bachelor's Degree in Computer Science and Real-Time Interactive Simulation from DigiPen Institute of Technology, I hold a Bachelor's Degree in Computer Science and Real-Time Interactive Simulation from DigiPen Institute of Technology,
so I am familiar with their copyright policy. Ask your professor about usage of my engine, and they or someone with so I am familiar with their copyright policy. Ask your professor about usage of my engine, and they or someone with
appropriate standing will reach out to me. Eventually, with interest, I may reach out on my own terms to negotiate usage appropriate standing will reach out to me. Eventually, with interest, I may reach out on my own terms to negotiate usage
of fennec for educative purposes at DigiPen while retaining their license on student work. of fennec for educative purposes at DigiPen while retaining their license on student work.
If your University is not listed here, reach out to your professor for permission. Ask them to reach out to me, I am If your University is not listed here, reach out to your professor for permission. Ask them to reach out to me, I am
willing to work with educational institutes to protect both fennec and student work in accordance to university policy. willing to work with educational institutes to protect both fennec and student work in accordance to university policy.
<br> <br>