From 5f39dc386cce357a7c71a81c523a90496f7b1e67 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Mon, 18 Nov 2024 18:18:27 +0100 Subject: update contributing.md --- contributing.md | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'contributing.md') diff --git a/contributing.md b/contributing.md index 5b0c79d..e4f075f 100644 --- a/contributing.md +++ b/contributing.md @@ -15,7 +15,11 @@ that you can click on to open them. `name/feature` (i.e. `loek/dll-so-poc` or `jaro/class2`) - The master branch is considered stable, and should always contain a working/compiling version of the project +- Pull requests for new code include either automated tests for the new code or + an explanation as to why the code can not (reliably) be tested + # Code style @@ -790,6 +794,7 @@ that you can click on to open them. } ``` +- Do not implement new classes as singletons ## CMakeLists-specific -- cgit v1.2.3 From 26ddec125cd93e9613331872f8e22c79c6f3a720 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Wed, 20 Nov 2024 13:30:33 +0100 Subject: update contributing.md --- contributing.md | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) (limited to 'contributing.md') diff --git a/contributing.md b/contributing.md index 5b0c79d..9c95851 100644 --- a/contributing.md +++ b/contributing.md @@ -20,7 +20,7 @@ that you can click on to open them. # Code style - Formatting nitty-gritty is handled by clang-format/clang-tidy (run `make - format` in the root folder of this repository to format all sources files) + format` or `make lint`) -
ASCII only
GoodBad
@@ -798,6 +798,27 @@ that you can click on to open them. resolving merge conflicts when multiple sources were added by different people to the same CMakeLists.txt easier. +## GoogleTest-specific + +- Unit tests are not *required* to follow all code standards +-
+ Private/protected members may be accessed using preprocessor tricks + + + ```cpp + // include unrelated headers before + + #define private public + #define protected public + + // headers included after *will* be affected + ``` +
+- Each test source file defines tests within a single test suite (first + parameter of `TEST()` / `TEST_F()` macro) +- Test source files match their suite name (or test fixture name in the case of + tests that use a fixture) + # Structure - Files are placed in the appropriate directory: -- cgit v1.2.3 From 1499363d85abedbdb571e33801b821f4dfabc638 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Fri, 22 Nov 2024 17:28:28 +0100 Subject: more documentation --- contributing.md | 24 ++++++++++++++++++++++++ src/crepe/api/Script.h | 7 +++++-- src/doc/internal/component.dox | 41 +++++++++++++++++++++++++++++++++++++++++ src/doc/internal/resource.dox | 12 ++++++++++++ src/doc/internal/style.dox | 9 +++++++++ src/doc/internal/system.dox | 26 ++++++++++++++++++++++++++ src/doc/internals.dox | 10 ++++++++++ src/doc/layout.xml | 16 ++++++++-------- src/doc/style.css | 2 ++ 9 files changed, 137 insertions(+), 10 deletions(-) create mode 100644 src/doc/internal/component.dox create mode 100644 src/doc/internal/resource.dox create mode 100644 src/doc/internal/style.dox create mode 100644 src/doc/internal/system.dox create mode 100644 src/doc/internals.dox (limited to 'contributing.md') diff --git a/contributing.md b/contributing.md index 77a2908..0a90e86 100644 --- a/contributing.md +++ b/contributing.md @@ -17,6 +17,7 @@ that you can click on to open them. working/compiling version of the project - Pull requests for new code include either automated tests for the new code or an explanation as to why the code can not (reliably) be tested + @@ -495,6 +496,12 @@ that you can click on to open them.
-
Ensure const-correctness + + > [!IMPORTANT] + > C-style APIs that work on (possibly internal) references to structs can be + > called from const member functions in C++. If the compiler allows you to + > mark a function as `const` even though it has side effects, it should + > **not** be marked as `const`.
GoodBad
```cpp @@ -795,6 +802,23 @@ that you can click on to open them. ```
- Do not implement new classes as singletons +-
+ Retrieving the first or last indices for iterators with a known or expected + size should be done using .front() or .back() + instead of by index +
GoodBad
+ + ```cpp + vector foo = { 1, 2, 3 }; + int bar = foo.first(); + ``` + + + ```cpp + vector foo = { 1, 2, 3 }; + int bar = foo[0]; + ``` +
## CMakeLists-specific diff --git a/src/crepe/api/Script.h b/src/crepe/api/Script.h index f0b9c73..a0870cb 100644 --- a/src/crepe/api/Script.h +++ b/src/crepe/api/Script.h @@ -22,6 +22,10 @@ class ComponentManager; * \info Additional *events* (like Unity's OnDisable and OnEnable) should be implemented as * member or lambda methods in derivative user script classes and registered in \c init(). * + * \warning Concrete scripts are allowed do create a custom constructor, but the utility + * functions should not be called inside the constructor as they rely on late references that + * are only available after the constructor returns. + * * \see feature_script */ class Script { @@ -63,8 +67,7 @@ protected: * * \returns Reference to component * - * \throws std::runtime_error if this game object does not have a component matching type \c - * T + * \throws std::runtime_error if this game object does not have a component with type \c T */ template T & get_component() const; diff --git a/src/doc/internal/component.dox b/src/doc/internal/component.dox new file mode 100644 index 0000000..0dd4cb5 --- /dev/null +++ b/src/doc/internal/component.dox @@ -0,0 +1,41 @@ +// vim:ft=doxygen +namespace crepe { +/** + +\defgroup internal_component Components +\ingroup internal +\brief ECS Components + +Components are attached to GameObject instances and are composed by the game +programmer to create specific entities in the game world. While they are +implemented as C++ classes, components should be treated as C-style structs, +meaning all members are public and they do not contain functions. + +A basic component has the following structure: +```cpp +#include + +class MyComponent : public crepe::Component { +public: + // Add your custom component's ininitializer properties after the `id` + // parameter. The first parameter is controlled by GameObject::add_component, + // while all other parameters are forwarded using std::forward. + MyComponent(game_object_id_t id, ...); + + // Optionally define the `get_instances_max` method to limit the amount of + // instances of this component per GameObject. The default implementation for + // this function returns -1, which means the instance count does not have an + // upper limit: + virtual int get_instances_max() const { return -1; } + + // Properties + // ... +}; +``` + +Generally, components are "handled" by \ref internal_system "systems", which may +optionally change the components' state. Components' state may also be +controlled by the game programmer through \ref feature_script "scripts". + +*/ +} diff --git a/src/doc/internal/resource.dox b/src/doc/internal/resource.dox new file mode 100644 index 0000000..56f1de0 --- /dev/null +++ b/src/doc/internal/resource.dox @@ -0,0 +1,12 @@ +// vim:ft=doxygen +namespace crepe { +/** + +\defgroup internal_resource Resources +\ingroup internal +\brief Concrete resources + +\todo This section is incomplete + +*/ +} diff --git a/src/doc/internal/style.dox b/src/doc/internal/style.dox new file mode 100644 index 0000000..dad2df0 --- /dev/null +++ b/src/doc/internal/style.dox @@ -0,0 +1,9 @@ +// vim:ft=doxygen +/** + +\defgroup internal_style Code style +\ingroup internal +\brief Coding conventions +\include{doc} contributing.md + +*/ diff --git a/src/doc/internal/system.dox b/src/doc/internal/system.dox new file mode 100644 index 0000000..17a101e --- /dev/null +++ b/src/doc/internal/system.dox @@ -0,0 +1,26 @@ +// vim:ft=doxygen +namespace crepe { +/** + +\defgroup internal_system Systems +\ingroup internal +\brief ECS Systems + +\todo This section is incomplete + +A system is responsible for processing the data stored in \ref +internal_component "components". + +A basic system has the following structure: +```cpp +#include + +class MySystem : public System { +public: + using System::System; + void update() override; +}; +``` + +*/ +} diff --git a/src/doc/internals.dox b/src/doc/internals.dox new file mode 100644 index 0000000..2d2ca56 --- /dev/null +++ b/src/doc/internals.dox @@ -0,0 +1,10 @@ +// vim:ft=doxygen +/** + +\defgroup internal Internals +\brief Internal engine structure and other conventions + +\todo This page is incomplete +\todo Anything about Contexts? + +*/ diff --git a/src/doc/layout.xml b/src/doc/layout.xml index 6bde443..fb4cc0c 100644 --- a/src/doc/layout.xml +++ b/src/doc/layout.xml @@ -1,13 +1,13 @@ - + - + @@ -15,9 +15,9 @@ - + - + @@ -28,20 +28,20 @@ - + - + - + - + diff --git a/src/doc/style.css b/src/doc/style.css index 08bc9f5..daabd39 100644 --- a/src/doc/style.css +++ b/src/doc/style.css @@ -2,3 +2,5 @@ address { display: none; } + +h2.groupheader { margin-top: revert; } -- cgit v1.2.3 From 647eb8e318f1ed1e3ec18505ea4df57025e6ffd5 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Fri, 29 Nov 2024 20:40:05 +0100 Subject: update contributing.md --- contributing.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'contributing.md') diff --git a/contributing.md b/contributing.md index 0a90e86..b0f623b 100644 --- a/contributing.md +++ b/contributing.md @@ -17,6 +17,8 @@ that you can click on to open them. working/compiling version of the project - Pull requests for new code include either automated tests for the new code or an explanation as to why the code can not (reliably) be tested +- Non-bugfix pull requests must be approved by at least 2 reviewers before being + merged