From 80a1307e1e4c4f749d0d885c65c07b5508a73fac Mon Sep 17 00:00:00 2001
From: Loek Le Blansch <loek@pipeframe.xyz>
Date: Sat, 7 Dec 2024 18:35:32 +0100
Subject: add update feature pages

---
 src/doc/feature/script.dox     | 42 ++++++++++++++++---------------
 src/doc/feature/script_ecs.dox | 57 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 79 insertions(+), 20 deletions(-)
 create mode 100644 src/doc/feature/script_ecs.dox

(limited to 'src/doc/feature')

diff --git a/src/doc/feature/script.dox b/src/doc/feature/script.dox
index d25a63b..e3b5508 100644
--- a/src/doc/feature/script.dox
+++ b/src/doc/feature/script.dox
@@ -2,19 +2,14 @@
 namespace crepe {
 /**
 
-\defgroup feature_script Scripting
+\defgroup feature_script Scripting basics
 \ingroup feature
-\brief User-defined scripts for game objects
+\brief Create a concrete Script and attach it to a GameObject
 
 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)
+Script, which are added to \ref GameObject "game objects" using the \ref
+BehaviorScript \ref Component "component".
 
 \see Script
 \see BehaviorScript
@@ -22,11 +17,14 @@ Script, which are added to game objects using the BehaviorScript \ref Component
 
 \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*.
+\note This example assumes you already have a GameObject. If not, read
+\"\ref feature_gameobject\" first.
+
+First, define a class (anywhere) that inherits from Script. The Script 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 <crepe/api/Script.h>
@@ -42,19 +40,23 @@ class MyScript : public crepe::Script {
 };
 ```
 
-Concrete scripts can be instantiated and attached to \ref GameObject
-"game objects" using the BehaviorScript \ref Component "component".
+After defining a concrete script, it can be instantiated and attached to \ref
+feature_gameobject "game objects" during \ref feature_scene
+"scene initialization" using a BehaviorScript component:
 
 ```cpp
 using namespace crepe;
-GameObject obj = component_manager.new_object("name");
+GameObject obj;
 
-// create BehaviorScript instance
+// Create a BehaviorScript component to hold MyScript
 BehaviorScript & behavior_script = obj.add_component<BehaviorScript>();
-// attach (and instantiate) MyScript to behavior_script
+
+// Instantiate (and attach) MyScript to behavior_script
 behavior_script.set_script<MyScript>();
+```
 
-// the above can also be done in a single call for convenience:
+The above can also be done in a single call for convenience:
+```cpp
 obj.add_component<BehaviorScript>().set_script<MyScript>();
 ```
 
diff --git a/src/doc/feature/script_ecs.dox b/src/doc/feature/script_ecs.dox
new file mode 100644
index 0000000..bbe1abc
--- /dev/null
+++ b/src/doc/feature/script_ecs.dox
@@ -0,0 +1,57 @@
+// vim:ft=doxygen
+namespace crepe {
+/**
+
+\defgroup feature_script_ecs Using ECS inside Script
+\ingroup feature
+\brief Query the component manager inside a concrete Script
+
+Script provides several methods to request references to components during
+runtime. These methods may be used in cases where it is either not practical or
+impossible to manually pass the references required to implement a certain
+behavior.
+
+\see Script
+\see ComponentManager
+
+\par Example
+
+\note This example assumes you already have a concrete Script. If not, read
+\"\ref feature_script\" first.
+
+The component manager can be queried for components inside Script using the
+following methods:
+
+- For requesting components on the same GameObject as this Script instance:
+	- Script::get_component(): \copybrief Script::get_component
+	- Script::get_components(): \copybrief Script::get_components
+- For requesting components in the current Scene:
+	- Script::get_components_by_id(): \copybrief Script::get_components_by_id
+	- Script::get_components_by_name(): \copybrief Script::get_components_by_name
+	- Script::get_components_by_tag(): \copybrief Script::get_components_by_tag
+
+```cpp
+#include <crepe/util/Log.h>
+#include <crepe/api/Script.h>
+#include <crepe/api/Metadata.h>
+
+using namespace crepe;
+
+class MyScript : public Script {
+	void show_self() {
+		Metadata & own_metadata = get_component<Metadata>();
+		Log::logf("My name is {}", own_metadata.name);
+	}
+
+	void list_enemies() {
+		RefVector<Metadata> enemies = get_components_by_tag<Metadata>("enemy");
+		Log::logf("There are {} enemies:", enemies.size());
+		for (const Metadata & enemy : enemies) {
+			Log::logf("- {}", enemy.name);
+		}
+	}
+};
+```
+
+*/
+}
-- 
cgit v1.2.3