merge with `master`

1 files changed, 67 insertions, 0 deletions

diff --git a/src/doc/feature/scene.dox b/src/doc/feature/scene.dox
new file mode 100644
index 0000000..eedc69a
--- /dev/null
+++ b/src/doc/feature/scene.dox
@@ -0,0 +1,67 @@
+// 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
+GameObjects during runtime of a Scene (use \ref feature_script "Scripting" for this purpose).
+
+\see SceneManager
+\see GameObject
+\see Script
+\see Scene
+
+\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.
+
+```cpp
+#include <crepe/api/LoopManager.h>
+#include <crepe/api/GameObject.h>
+#include <crepe/api/Scene.h>
+#include <crepe/api/Vector2.h>
+
+using namespace crepe;
+
+class MyScene : public Scene {
+public:
+	using Scene::Scene;
+
+	void load_scene() {
+		auto & 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);
+	}
+
+	string get_name() const { return "my_scene"; }
+};
+
+int main() {
+	LoopManager loop_mgr;
+	
+	// Add the scenes to the loop manager
+	loop_mgr.add_scene<MyScene>();
+
+	loop_mgr.start();
+}
+```
+
+*/
+}