From 7f1ba9e90ddcdbcd3b6ab11c5796ef8043f71cc1 Mon Sep 17 00:00:00 2001 From: max-001 Date: Fri, 22 Nov 2024 09:39:23 +0100 Subject: Updated documentation --- src/doc/feature/scene.dox | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'src/doc') diff --git a/src/doc/feature/scene.dox b/src/doc/feature/scene.dox index 5f34446..5d765f9 100644 --- a/src/doc/feature/scene.dox +++ b/src/doc/feature/scene.dox @@ -42,10 +42,8 @@ using namespace crepe; class MyScene : public Scene { public: - using Scene::Scene; - void load_scene() { - auto & mgr = this->component_manager; + ComponentManager & mgr = this->component_manager; GameObject object1 = mgr.new_object("object1", "tag_my_scene", Vector2{0, 0}, 0, 1); GameObject object2 = mgr.new_object("object2", "tag_my_scene", Vector2{1, 0}, 0, 1); } -- cgit v1.2.3 From 610461763977597c5df213d272a514730dd2364e Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Fri, 22 Nov 2024 16:33:08 +0100 Subject: add custom tabs to doxygen --- src/doc/layout.xml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'src/doc') diff --git a/src/doc/layout.xml b/src/doc/layout.xml index 7f514d4..6bde443 100644 --- a/src/doc/layout.xml +++ b/src/doc/layout.xml @@ -2,8 +2,11 @@ + + + - + -- 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 'src/doc') 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 be5ccbe24086d5d4fb407f268c649dcbc36eda6b Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sun, 24 Nov 2024 19:03:06 +0100 Subject: nitpick #50 --- src/crepe/api/Scene.h | 3 ++- src/doc/feature/scene.dox | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) (limited to 'src/doc') diff --git a/src/crepe/api/Scene.h b/src/crepe/api/Scene.h index 22aadab..f6fdb2a 100644 --- a/src/crepe/api/Scene.h +++ b/src/crepe/api/Scene.h @@ -1,8 +1,9 @@ #pragma once -#include "util/OptionalRef.h" #include +#include "../util/OptionalRef.h" + namespace crepe { class SceneManager; diff --git a/src/doc/feature/scene.dox b/src/doc/feature/scene.dox index bac1c87..d81df4c 100644 --- a/src/doc/feature/scene.dox +++ b/src/doc/feature/scene.dox @@ -36,7 +36,7 @@ concrete scene to be added. #include #include #include -#include +#include using namespace crepe; -- cgit v1.2.3