diff options
| -rw-r--r-- | contributing.md | 24 | ||||
| -rw-r--r-- | src/crepe/api/Script.h | 7 | ||||
| -rw-r--r-- | src/doc/internal/component.dox | 41 | ||||
| -rw-r--r-- | src/doc/internal/resource.dox | 12 | ||||
| -rw-r--r-- | src/doc/internal/style.dox | 9 | ||||
| -rw-r--r-- | src/doc/internal/system.dox | 26 | ||||
| -rw-r--r-- | src/doc/internals.dox | 10 | ||||
| -rw-r--r-- | src/doc/layout.xml | 16 | ||||
| -rw-r--r-- | src/doc/style.css | 2 |
9 files changed, 137 insertions, 10 deletions
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 + <!-- - TODO: tagging / versions --> @@ -495,6 +496,12 @@ that you can click on to open them. </td></tr></table></details> - <details><summary> 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`. </summary><table><tr><th>Good</th><th>Bad</th></tr><tr><td> ```cpp @@ -795,6 +802,23 @@ that you can click on to open them. ``` </td></tr></table></details> - Do not implement new classes as singletons +- <details><summary> + Retrieving the first or last indices for iterators with a known or expected + size should be done using <code>.front()</code> or <code>.back()</code> + instead of by index + </summary><table><tr><th>Good</th><th>Bad</th></tr><tr><td> + + ```cpp + vector<int> foo = { 1, 2, 3 }; + int bar = foo.first(); + ``` + </td><td> + + ```cpp + vector<int> foo = { 1, 2, 3 }; + int bar = foo[0]; + ``` + </td></tr></table></details> ## 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 <typename T> 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 <crepe/Component.h> + +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 <crepe/system/System.h> + +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 @@ <?xml version="1.0" encoding="UTF-8"?> <doxygenlayout version="1.0"> <navindex> - <tab type="mainpage" visible="yes" title=""/> + <tab type="mainpage" visible="yes" title="Intro"/> <tab type="user" url="@ref install" title="Installation"/> <tab type="user" url="@ref feature" title="Features"/> <tab type="user" url="@ref internal" title="Internals"/> <tab type="pages" visible="no" title="" intro=""/> <tab type="topics" visible="no" title="" intro=""/> - <tab type="modules" visible="yes" title="" intro=""> + <tab type="modules" visible="no" title="" intro=""> <tab type="modulelist" visible="yes" title="" intro=""/> <tab type="modulemembers" visible="yes" title="" intro=""/> </tab> @@ -15,9 +15,9 @@ <tab type="namespacelist" visible="yes" title="" intro=""/> <tab type="namespacemembers" visible="yes" title="" intro=""/> </tab> - <tab type="concepts" visible="yes" title=""> + <tab type="concepts" visible="no" title=""> </tab> - <tab type="interfaces" visible="yes" title=""> + <tab type="interfaces" visible="no" title=""> <tab type="interfacelist" visible="yes" title="" intro=""/> <tab type="interfaceindex" visible="$ALPHABETICAL_INDEX" title=""/> <tab type="interfacehierarchy" visible="yes" title="" intro=""/> @@ -28,20 +28,20 @@ <tab type="hierarchy" visible="yes" title="" intro=""/> <tab type="classmembers" visible="yes" title="" intro=""/> </tab> - <tab type="structs" visible="yes" title=""> + <tab type="structs" visible="no" title=""> <tab type="structlist" visible="yes" title="" intro=""/> <tab type="structindex" visible="$ALPHABETICAL_INDEX" title=""/> </tab> - <tab type="exceptions" visible="yes" title=""> + <tab type="exceptions" visible="no" title=""> <tab type="exceptionlist" visible="yes" title="" intro=""/> <tab type="exceptionindex" visible="$ALPHABETICAL_INDEX" title=""/> <tab type="exceptionhierarchy" visible="yes" title="" intro=""/> </tab> - <tab type="files" visible="yes" title=""> + <tab type="files" visible="no" title=""> <tab type="filelist" visible="yes" title="" intro=""/> <tab type="globals" visible="yes" title="" intro=""/> </tab> - <tab type="examples" visible="yes" title="" intro=""/> + <tab type="examples" visible="no" title="" intro=""/> </navindex> <class> <briefdescription visible="yes"/> 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; } |