diff options
Diffstat (limited to 'src/doc')
| -rw-r--r-- | src/doc/feature/animator_creation.dox | 0 | ||||
| -rw-r--r-- | src/doc/feature/proxy.dox | 43 | ||||
| -rw-r--r-- | src/doc/feature/savemgr.dox | 80 | ||||
| -rw-r--r-- | src/doc/feature/scene.dox | 47 | ||||
| -rw-r--r-- | src/doc/features.dox | 18 | ||||
| -rw-r--r-- | src/doc/index.dox | 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 | 31 | ||||
| -rw-r--r-- | src/doc/style.css | 8 |
13 files changed, 294 insertions, 38 deletions
diff --git a/src/doc/feature/animator_creation.dox b/src/doc/feature/animator_creation.dox new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/src/doc/feature/animator_creation.dox diff --git a/src/doc/feature/proxy.dox b/src/doc/feature/proxy.dox new file mode 100644 index 0000000..66bbd2f --- /dev/null +++ b/src/doc/feature/proxy.dox @@ -0,0 +1,43 @@ +// vim:ft=doxygen +namespace crepe { +/** + +\defgroup feature_proxy Proxy utility +\ingroup feature +\brief Use ValueBroker as if it were a regular variable + +Proxy provides operators that allow you to use a ValueBroker instance as if it +were a regular variable. Proxy implements a constructor that allows it to be +used as a substitute return type for any function that returns ValueBroker. + +\see ValueBroker +\see Proxy + +\par Example + +```cpp +#include <crepe/util/Proxy.h> +#include <crepe/ValueBroker.h> + +int calculation(int value) { + return 3 * value; +} + +void anywhere() { + crepe::ValueBroker<int> foo_handle; + crepe::Proxy foo = foo_handle; + + // implicitly calls .set() + foo += 10; + + // implicitly calls .get() + int out = calculation(foo); + + // explicitly cast (also calls .get()) + int casted = int(foo); +} + +``` + +*/ +} diff --git a/src/doc/feature/savemgr.dox b/src/doc/feature/savemgr.dox new file mode 100644 index 0000000..6aeab03 --- /dev/null +++ b/src/doc/feature/savemgr.dox @@ -0,0 +1,80 @@ +// vim:ft=doxygen +namespace crepe { +/** + +\defgroup feature_savemgr Save data +\ingroup feature +\brief Functions to persistently store and retrieve arbitrary values + +The SaveManager may be used to persistently store game state such as player +progress, statistics, achievements, etc. It works like a key-value store, where +the key is a string and the value is an arbitrary type. + +SaveManager implements the following: + +- Storage and retrieval of primitive types and strings. +- Automatic initialization of the database using default values. +- The underlying database format is journaled, which reduces the likelihood of + players losing save data when an unexpected crash occurs while the SaveManager + is writing to disk. + +\see SaveManager + +\par Example + +The SaveManager instance reference may be retrieved by calling \c +get_save_manager(). This function is available--- + +- Within (derivatives of) Script + +- \todo Within (derivatives of) Scene + +- \todo As a public member function of LoopManager + +```cpp +// Retrieve save manager +crepe::SaveManager & save_manager = get_save_manager(); +``` + +SaveManager may be used *explicitly*, using the \ref SaveManager::set "set()", +\ref SaveManager::get "get()" and \ref SaveManager::has "has()" methods: +```cpp +// Check if the key "foo" exists, and initialize it to 3 if it doesn't +if (!save_manager.has("foo")) + save_manager.set<int>("foo", 3); +// Get value of key "foo" +int foo = save_manager.get<int>("foo"); + +// ~~~ arbitrary game code ~~~ +foo += 10; +// ~~~ arbitrary game code ~~~ + +// Save "foo" back to database +save_manager.set<int>("foo", foo); +``` + +Alternatively, SaveManager::get may be called with a default value as second +parameter. This changes its return type to ValueBroker, which acts as a +read/write handle to the specific key requested, and remembers the key and its +value type for you: +```cpp +// Get a read/write handle to the value stored in key "foo", and initialize it +// to 3 if it doesn't exist yet +ValueBroker foo_handle = save_manager.get<int>("foo", 3); +int foo = foo_handle.get(); + +// ~~~ arbitrary game code ~~~ +foo += 10; +// ~~~ arbitrary game code ~~~ + +// Save back to database +foo_handle.set(foo); +``` + +To further simplify game code, the return value of SaveManager::get may be +implicitly cast to Proxy instead of ValueBroker. This allows the database value +to be used as if it were a regular variable. This usage is detailed separately +in \"\ref feature_proxy\". + +*/ +} diff --git a/src/doc/feature/scene.dox b/src/doc/feature/scene.dox index eedc69a..4124e37 100644 --- a/src/doc/feature/scene.dox +++ b/src/doc/feature/scene.dox @@ -6,10 +6,11 @@ namespace crepe { \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 -GameObjects during runtime of a Scene (use \ref feature_script "Scripting" for this purpose). +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 GameObjects during +runtime of a Scene (use \ref feature_script for this purpose). \see SceneManager \see GameObject @@ -18,34 +19,38 @@ GameObjects during runtime of a Scene (use \ref feature_script "Scripting" for t \par Example -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. +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 <crepe/api/LoopManager.h> #include <crepe/api/GameObject.h> #include <crepe/api/Scene.h> -#include <crepe/api/Vector2.h> +#include <crepe/types.h> 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", vec2{0, 0}, 0, 1); GameObject object2 = mgr.new_object("object2", "tag_my_scene", vec2{1, 0}, 0, 1); } diff --git a/src/doc/features.dox b/src/doc/features.dox index 4786bed..21a040a 100644 --- a/src/doc/features.dox +++ b/src/doc/features.dox @@ -1,10 +1,28 @@ // vim:ft=doxygen /** +\htmlonly +<style> +table.memberdecls { display: none; } +ul { margin: 1ex 0pt; } +</style> +\endhtmlonly + \defgroup feature Features \brief Engine components This page lists engine features and contains usage instructions for each feature. +\par Features + +- Scripting + - \ref feature_script \n\copybrief feature_script + +- Game flow management + - \ref feature_scene \n\copybrief feature_scene + +- Entity + - \ref feature_gameobject \n\copybrief feature_gameobject + */ diff --git a/src/doc/index.dox b/src/doc/index.dox index 5ec7889..7796f34 100644 --- a/src/doc/index.dox +++ b/src/doc/index.dox @@ -8,3 +8,10 @@ Welcome to the documentation for the crêpe game engine. \see feature */ + +/** + +\namespace crepe +\brief Engine namespace + +*/ 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 7f514d4..6336655 100644 --- a/src/doc/layout.xml +++ b/src/doc/layout.xml @@ -1,20 +1,23 @@ <?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="yes" title="" intro=""/> - <tab type="modules" visible="yes" title="" intro=""> + <tab type="topics" visible="no" title="" intro=""/> + <tab type="modules" visible="no" title="" intro=""> <tab type="modulelist" visible="yes" title="" intro=""/> <tab type="modulemembers" visible="yes" title="" intro=""/> </tab> - <tab type="namespaces" visible="no" title=""> + <tab type="namespaces" visible="yes" title=""> <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=""/> @@ -25,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"/> @@ -53,10 +56,10 @@ <interfaces title=""/> <publicslots title=""/> <signals title=""/> - <publicmethods title=""/> - <publicstaticmethods title=""/> <publicattributes title=""/> <publicstaticattributes title=""/> + <publicmethods title=""/> + <publicstaticmethods title=""/> <protectedtypes title=""/> <protectedslots title=""/> <protectedmethods title=""/> @@ -99,11 +102,12 @@ </class> <namespace> <briefdescription visible="yes"/> + <detaileddescription title=""/> <memberdecl> <nestednamespaces visible="yes" title=""/> <constantgroups visible="yes" title=""/> <interfaces visible="yes" title=""/> - <classes visible="yes" title=""/> + <classes visible="no" title=""/> <concepts visible="yes" title=""/> <structs visible="yes" title=""/> <exceptions visible="yes" title=""/> @@ -116,7 +120,6 @@ <properties title=""/> <membergroups visible="yes"/> </memberdecl> - <detaileddescription title=""/> <memberdef> <inlineclasses title=""/> <typedefs title=""/> diff --git a/src/doc/style.css b/src/doc/style.css index 08bc9f5..c12240c 100644 --- a/src/doc/style.css +++ b/src/doc/style.css @@ -1,4 +1,6 @@ #titlearea, -address { - display: none; -} +address, +a[href="namespaces.html"] +{ display: none; } + +h2.groupheader { margin-top: revert; } |