From 0476a8e9dbe7afb422862f7b1c15aaed7f3c416e Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Tue, 19 Nov 2024 12:11:11 +0100 Subject: add some more doxygen --- src/doc/feature/script.dox | 62 +++++++++++ src/doc/features.dox | 10 ++ src/doc/index.dox | 10 ++ src/doc/installing.dox | 9 ++ src/doc/layout.xml | 252 +++++++++++++++++++++++++++++++++++++++++++++ src/doc/style.css | 4 + 6 files changed, 347 insertions(+) create mode 100644 src/doc/feature/script.dox create mode 100644 src/doc/features.dox create mode 100644 src/doc/index.dox create mode 100644 src/doc/installing.dox create mode 100644 src/doc/layout.xml create mode 100644 src/doc/style.css (limited to 'src/doc') diff --git a/src/doc/feature/script.dox b/src/doc/feature/script.dox new file mode 100644 index 0000000..d25a63b --- /dev/null +++ b/src/doc/feature/script.dox @@ -0,0 +1,62 @@ +// vim:ft=doxygen +namespace crepe { +/** + +\defgroup feature_script Scripting +\ingroup feature +\brief User-defined scripts for game objects + +Scripts can be used to implement game behavior, and allow arbitrary code to run +as part of the game loop. Scripts are implemented as derivative classes of +Script, which are added to game objects using the BehaviorScript \ref Component +"component". + +\todo This section is incomplete: +- Utility functions to get components/events/etc inside script +- How to listen for events +- Extensions of script (keylistener) + +\see Script +\see BehaviorScript +\see GameObject + +\par Example + +First, define a class that inherits from Script. This class acts as an +interface, and has two functions (\ref Script::init "\c init()" and \ref +Script::update "\c update()"), which may be implemented (they are empty by +default). From now on, this derivative class will be referred to as a *concrete +script*. + +```cpp +#include +#include + +class MyScript : public crepe::Script { + void init() { + // called once + } + void update() { + // called on fixed update + } +}; +``` + +Concrete scripts can be instantiated and attached to \ref GameObject +"game objects" using the BehaviorScript \ref Component "component". + +```cpp +using namespace crepe; +GameObject obj = component_manager.new_object("name"); + +// create BehaviorScript instance +BehaviorScript & behavior_script = obj.add_component(); +// attach (and instantiate) MyScript to behavior_script +behavior_script.set_script(); + +// the above can also be done in a single call for convenience: +obj.add_component().set_script(); +``` + +*/ +} diff --git a/src/doc/features.dox b/src/doc/features.dox new file mode 100644 index 0000000..4786bed --- /dev/null +++ b/src/doc/features.dox @@ -0,0 +1,10 @@ +// vim:ft=doxygen +/** + +\defgroup feature Features +\brief Engine components + +This page lists engine features and contains usage instructions for each +feature. + +*/ diff --git a/src/doc/index.dox b/src/doc/index.dox new file mode 100644 index 0000000..5ec7889 --- /dev/null +++ b/src/doc/index.dox @@ -0,0 +1,10 @@ +// vim:ft=doxygen +/** + +\mainpage crêpe game engine + +Welcome to the documentation for the crêpe game engine. + +\see feature + +*/ diff --git a/src/doc/installing.dox b/src/doc/installing.dox new file mode 100644 index 0000000..48b27d7 --- /dev/null +++ b/src/doc/installing.dox @@ -0,0 +1,9 @@ +// vim:ft=doxygen +/** + +\defgroup install Installation +\brief Engine installation instructions + +\todo This entire page + +*/ diff --git a/src/doc/layout.xml b/src/doc/layout.xml new file mode 100644 index 0000000..2244fa7 --- /dev/null +++ b/src/doc/layout.xml @@ -0,0 +1,252 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/doc/style.css b/src/doc/style.css new file mode 100644 index 0000000..08bc9f5 --- /dev/null +++ b/src/doc/style.css @@ -0,0 +1,4 @@ +#titlearea, +address { + display: none; +} -- cgit v1.2.3 From e585e01b625fcdbc00709c1bbade1b542b1f6139 Mon Sep 17 00:00:00 2001 From: max-001 Date: Wed, 20 Nov 2024 11:42:23 +0100 Subject: Added Doxygen comments/explanation for GameObjects and Scenes --- src/crepe/api/Scene.h | 14 ++++++++++ src/crepe/api/SceneManager.h | 10 +++++++ src/doc/feature/gameobject.dox | 18 +++++++++++++ src/doc/feature/scene.dox | 60 ++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 102 insertions(+) create mode 100644 src/doc/feature/gameobject.dox create mode 100644 src/doc/feature/scene.dox (limited to 'src/doc') diff --git a/src/crepe/api/Scene.h b/src/crepe/api/Scene.h index 0e516b6..6647135 100644 --- a/src/crepe/api/Scene.h +++ b/src/crepe/api/Scene.h @@ -7,19 +7,33 @@ namespace crepe { class SceneManager; class ComponentManager; +/** + * \brief Represents a Scene + * + * This class represents a Scene. The Scene class is only used as an interface for the game + * programmer. + */ class Scene { protected: + /** + * \param mgr Reference to the ComponentManager + * \param name Name of the scene + */ Scene(ComponentManager & mgr, const std::string & name); + //! SceneManager instances Scene friend class SceneManager; public: virtual ~Scene() = default; public: + //! Load the scene virtual void load_scene() = 0; + //! The scene name const std::string name; protected: + //! Reference to the ComponentManager ComponentManager & component_manager; }; diff --git a/src/crepe/api/SceneManager.h b/src/crepe/api/SceneManager.h index e854794..16d6004 100644 --- a/src/crepe/api/SceneManager.h +++ b/src/crepe/api/SceneManager.h @@ -10,8 +10,15 @@ namespace crepe { class ComponentManager; +/** + * \brief Manages scenes + * + * This class manages scenes. It can add new scenes and load them. It also manages the current scene + * and the next scene. + */ class SceneManager { public: + //! \param mgr Reference to the ComponentManager SceneManager(ComponentManager & mgr); public: @@ -35,8 +42,11 @@ public: void load_next_scene(); private: + //! Vector of scenes std::vector> scenes; + //! Next scene to load std::string next_scene; + //! Reference to the ComponentManager ComponentManager & component_manager; }; diff --git a/src/doc/feature/gameobject.dox b/src/doc/feature/gameobject.dox new file mode 100644 index 0000000..603c98d --- /dev/null +++ b/src/doc/feature/gameobject.dox @@ -0,0 +1,18 @@ +// vim:ft=doxygen +namespace crepe { +/** + +\defgroup feature_gameobject GameObjects +\ingroup feature +\brief GameObject to create a Scene + +GameObjects are the fundamental building blocks of a Scene. They represent entities +in the game world and can have various components attached to them to define their +behavior and properties. GameObjects can be created, and modified within the +Scene, allowing for a flexible and dynamic game environment. + +\see Component +\see Scene + +*/ +} diff --git a/src/doc/feature/scene.dox b/src/doc/feature/scene.dox new file mode 100644 index 0000000..50f5ebd --- /dev/null +++ b/src/doc/feature/scene.dox @@ -0,0 +1,60 @@ +// vim:ft=doxygen +namespace crepe { +/** + +\defgroup feature_scene Scenes +\ingroup feature +\brief User-defined scenes + +Scenes can be used to implement game environments, and allow arbitrary game objects to be organized +as part of the game structure. Scenes are implemented as derivative classes of Scene, which are +added to the game using the SceneManager. Scenes describe the start of a Scene and cannot modify +GameObject during runtime of a Scene (use Scripting for this purpose). + +\see SceneManager +\see GameObject +\see Script +\see Scene + +\par Example + +This example demonstrates how to define and add scenes to a scene manager in the `crepe` framework. +Two concrete scene classes, `ConcreteScene1` and `ConcreteScene2`, are derived from the base `Scene` class. +Each scene class overrides the `load_scene` method to create and initialize game objects specific to the scene. +Finally, the scenes are added to the scene manager. + +```cpp +using namespace crepe; + +class ConcreteScene1 : public Scene { +public: + using Scene::Scene; + + void load_scene() { + auto & mgr = this->component_manager; + GameObject object1 = mgr.new_object("scene_1", "tag_scene_1", Vector2{0, 0}, 0, 1); + GameObject object2 = mgr.new_object("scene_1", "tag_scene_1", Vector2{1, 0}, 0, 1); + GameObject object3 = mgr.new_object("scene_1", "tag_scene_1", Vector2{2, 0}, 0, 1); + } +}; + +class ConcreteScene2 : public Scene { +public: + using Scene::Scene; + + void load_scene() { + auto & mgr = this->component_manager; + GameObject object1 = mgr.new_object("scene_2", "tag_scene_2", Vector2{0, 0}, 0, 1); + GameObject object2 = mgr.new_object("scene_2", "tag_scene_2", Vector2{0, 1}, 0, 1); + GameObject object3 = mgr.new_object("scene_2", "tag_scene_2", Vector2{0, 2}, 0, 1); + GameObject object4 = mgr.new_object("scene_2", "tag_scene_2", Vector2{0, 3}, 0, 1); + } +}; + +// Add the scenes to the scene manager +scene_mgr.add_scene("scene1"); +scene_mgr.add_scene("scene2"); +``` + +*/ +} -- cgit v1.2.3 From 8b5fd6188862bf9bdfc06a5419c8525d2dfd5f7f Mon Sep 17 00:00:00 2001 From: max-001 Date: Thu, 21 Nov 2024 08:53:48 +0100 Subject: Deleted comma --- src/doc/feature/gameobject.dox | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/doc') diff --git a/src/doc/feature/gameobject.dox b/src/doc/feature/gameobject.dox index 603c98d..c561874 100644 --- a/src/doc/feature/gameobject.dox +++ b/src/doc/feature/gameobject.dox @@ -8,7 +8,7 @@ namespace crepe { GameObjects are the fundamental building blocks of a Scene. They represent entities in the game world and can have various components attached to them to define their -behavior and properties. GameObjects can be created, and modified within the +behavior and properties. GameObjects can be created and modified within the Scene, allowing for a flexible and dynamic game environment. \see Component -- cgit v1.2.3 From ba3b97467ffa9df03d74e87bd567e3dfc521df05 Mon Sep 17 00:00:00 2001 From: max-001 Date: Thu, 21 Nov 2024 09:42:50 +0100 Subject: Improved example --- src/doc/feature/scene.dox | 55 ++++++++++++++++++++++++++--------------------- 1 file changed, 31 insertions(+), 24 deletions(-) (limited to 'src/doc') diff --git a/src/doc/feature/scene.dox b/src/doc/feature/scene.dox index 50f5ebd..5f34446 100644 --- a/src/doc/feature/scene.dox +++ b/src/doc/feature/scene.dox @@ -9,7 +9,7 @@ namespace crepe { Scenes can be used to implement game environments, and allow arbitrary game objects to be organized as part of the game structure. Scenes are implemented as derivative classes of Scene, which are added to the game using the SceneManager. Scenes describe the start of a Scene and cannot modify -GameObject during runtime of a Scene (use Scripting for this purpose). +GameObjects during runtime of a Scene (use \ref feature_script "Scripting" for this purpose). \see SceneManager \see GameObject @@ -18,42 +18,49 @@ GameObject during runtime of a Scene (use Scripting for this purpose). \par Example -This example demonstrates how to define and add scenes to a scene manager in the `crepe` framework. -Two concrete scene classes, `ConcreteScene1` and `ConcreteScene2`, are derived from the base `Scene` class. -Each scene class overrides the `load_scene` method to create and initialize game objects specific to the scene. -Finally, the scenes are added to the scene manager. +This example demonstrates how to define and add scenes to the loop/scene manager in the `crepe` framework. +Each concrete scene should be derived from Scene. In the example below, the concrete scene is named MyScene. +A concrete scene should, at least, implement (override) two methods, namely load_scene() and get_name(). The +scene is build (using GameObjects) in the load_scene() method. GameObjects should be made using the +component_manager::new_object(). In the example below, two GameObjects (named object1 and object2) are added +to MyScene. object1 and object2 do not have any non-default Components attached to them, however, if needed, +this should also be done in load_scene(). Each concrete scene must have a unique name. This unique name is +used to load a new concrete scene (via a Script). The unique name is set using the get_name() method. In the +example below, MyScene's unique name is my_scene. +After setting up one or more concrete scene(s), the concrete scene(s) should be added to the loop/scene manager. +This is done in your main(). Firstly, the LoopManager should be instantiated. Than, all the concrete scene(s) +should be added to the loop/scene manger via loop_mgr::add_scene<>(). The templated argument should define the +concrete scene to be added. ```cpp +#include +#include +#include +#include + using namespace crepe; -class ConcreteScene1 : public Scene { +class MyScene : public Scene { public: using Scene::Scene; void load_scene() { auto & mgr = this->component_manager; - GameObject object1 = mgr.new_object("scene_1", "tag_scene_1", Vector2{0, 0}, 0, 1); - GameObject object2 = mgr.new_object("scene_1", "tag_scene_1", Vector2{1, 0}, 0, 1); - GameObject object3 = mgr.new_object("scene_1", "tag_scene_1", Vector2{2, 0}, 0, 1); + 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); } -}; - -class ConcreteScene2 : public Scene { -public: - using Scene::Scene; - void load_scene() { - auto & mgr = this->component_manager; - GameObject object1 = mgr.new_object("scene_2", "tag_scene_2", Vector2{0, 0}, 0, 1); - GameObject object2 = mgr.new_object("scene_2", "tag_scene_2", Vector2{0, 1}, 0, 1); - GameObject object3 = mgr.new_object("scene_2", "tag_scene_2", Vector2{0, 2}, 0, 1); - GameObject object4 = mgr.new_object("scene_2", "tag_scene_2", Vector2{0, 3}, 0, 1); - } + string get_name() const { return "my_scene"; } }; -// Add the scenes to the scene manager -scene_mgr.add_scene("scene1"); -scene_mgr.add_scene("scene2"); +int main() { + LoopManager loop_mgr; + + // Add the scenes to the loop manager + loop_mgr.add_scene(); + + loop_mgr.start(); +} ``` */ -- cgit v1.2.3 From 502fb8e8d1dcfe10f55fdef2cdfb71afec806204 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Thu, 21 Nov 2024 09:43:13 +0100 Subject: pull script/event changes from `loek/collision-system` --- Doxyfile | 6 ++-- src/crepe/api/BehaviorScript.h | 7 +++-- src/crepe/api/BehaviorScript.hpp | 11 +++++--- src/crepe/api/Event.h | 12 ++++---- src/crepe/api/EventManager.h | 4 +-- src/crepe/api/Script.cpp | 6 ++++ src/crepe/api/Script.h | 60 +++++++++++++++++++++++++++++++++++----- src/crepe/api/Script.hpp | 20 ++++++++++++-- src/doc/layout.xml | 2 +- src/test/ScriptTest.cpp | 60 ++++++++++++++++++++++++++++++++++++++-- 10 files changed, 159 insertions(+), 29 deletions(-) (limited to 'src/doc') diff --git a/Doxyfile b/Doxyfile index e0a31df..f2714cd 100644 --- a/Doxyfile +++ b/Doxyfile @@ -19,15 +19,17 @@ TAB_SIZE = 2 HTML_INDEX_NUM_ENTRIES = 2 HTML_EXTRA_STYLESHEET = src/doc/style.css +SHOW_HEADERFILE = NO USE_MDFILE_AS_MAINPAGE = ./readme.md REPEAT_BRIEF = NO -INTERNAL_DOCS = YES -EXTRACT_PRIVATE = YES EXTRACT_STATIC = YES HIDE_UNDOC_NAMESPACES = YES HIDE_UNDOC_CLASSES = YES QUIET = YES +# set these to NO for user-only docs +INTERNAL_DOCS = YES +EXTRACT_PRIVATE = YES diff --git a/src/crepe/api/BehaviorScript.h b/src/crepe/api/BehaviorScript.h index 9d85d4c..d556fe5 100644 --- a/src/crepe/api/BehaviorScript.h +++ b/src/crepe/api/BehaviorScript.h @@ -39,11 +39,14 @@ public: * \brief Set the concrete script of this component * * \tparam T Concrete script type (derived from \c crepe::Script) + * \tparam Args Arguments for concrete script constructor + * + * \param args Arguments for concrete script constructor (forwarded using perfect forwarding) * * \returns Reference to BehaviorScript component (`*this`) */ - template - BehaviorScript & set_script(); + template + BehaviorScript & set_script(Args &&... args); protected: //! Script instance diff --git a/src/crepe/api/BehaviorScript.hpp b/src/crepe/api/BehaviorScript.hpp index dd1efd5..5b5a418 100644 --- a/src/crepe/api/BehaviorScript.hpp +++ b/src/crepe/api/BehaviorScript.hpp @@ -9,14 +9,17 @@ namespace crepe { -template -BehaviorScript & BehaviorScript::set_script() { +template +BehaviorScript & BehaviorScript::set_script(Args &&... args) { dbg_trace(); static_assert(std::is_base_of::value); - Script * s = new T(); - s->game_object_id = this->game_object_id; + Script * s = new T(std::forward(args)...); + + s->game_object_id_ref = &this->game_object_id; + s->active_ref = &this->active; s->component_manager_ref = &this->component_manager; s->event_manager_ref = &EventManager::get_instance(); + this->script = std::unique_ptr