From 0476a8e9dbe7afb422862f7b1c15aaed7f3c416e Mon Sep 17 00:00:00 2001
From: Loek Le Blansch <loek@pipeframe.xyz>
Date: Tue, 19 Nov 2024 12:11:11 +0100
Subject: add some more doxygen

---
 src/doc/layout.xml | 252 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 252 insertions(+)
 create mode 100644 src/doc/layout.xml

(limited to 'src/doc/layout.xml')

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 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<doxygenlayout version="1.0">
+	<navindex>
+		<tab type="mainpage" visible="yes" title=""/>
+		<tab type="pages" visible="no" title="" intro=""/>
+		<tab type="topics" visible="yes" title="" intro=""/>
+		<tab type="modules" visible="yes" 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="namespacelist" visible="yes" title="" intro=""/>
+			<tab type="namespacemembers" visible="yes" title="" intro=""/>
+		</tab>
+		<tab type="concepts" visible="yes" title="">
+		</tab>
+		<tab type="interfaces" visible="yes" title="">
+			<tab type="interfacelist" visible="yes" title="" intro=""/>
+			<tab type="interfaceindex" visible="$ALPHABETICAL_INDEX" title=""/>
+			<tab type="interfacehierarchy" visible="yes" title="" intro=""/>
+		</tab>
+		<tab type="classes" visible="yes" title="">
+			<tab type="classlist" visible="yes" title="" intro=""/>
+			<tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
+			<tab type="hierarchy" visible="yes" title="" intro=""/>
+			<tab type="classmembers" visible="yes" title="" intro=""/>
+		</tab>
+		<tab type="structs" visible="yes" title="">
+			<tab type="structlist" visible="yes" title="" intro=""/>
+			<tab type="structindex" visible="$ALPHABETICAL_INDEX" title=""/>
+		</tab>
+		<tab type="exceptions" visible="yes" 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="filelist" visible="yes" title="" intro=""/>
+			<tab type="globals" visible="yes" title="" intro=""/>
+		</tab>
+		<tab type="examples" visible="yes" title="" intro=""/>
+	</navindex>
+	<class>
+		<briefdescription visible="yes"/>
+		<includes visible="$SHOW_HEADERFILE"/>
+		<inheritancegraph visible="yes"/>
+		<collaborationgraph visible="yes"/>
+		<memberdecl>
+			<nestedclasses visible="yes" title=""/>
+			<publictypes title=""/>
+			<services title=""/>
+			<interfaces title=""/>
+			<publicslots title=""/>
+			<signals title=""/>
+			<publicmethods title=""/>
+			<publicstaticmethods title=""/>
+			<publicattributes title=""/>
+			<publicstaticattributes title=""/>
+			<protectedtypes title=""/>
+			<protectedslots title=""/>
+			<protectedmethods title=""/>
+			<protectedstaticmethods title=""/>
+			<protectedattributes title=""/>
+			<protectedstaticattributes title=""/>
+			<packagetypes title=""/>
+			<packagemethods title=""/>
+			<packagestaticmethods title=""/>
+			<packageattributes title=""/>
+			<packagestaticattributes title=""/>
+			<properties title=""/>
+			<events title=""/>
+			<privatetypes title=""/>
+			<privateslots title=""/>
+			<privatemethods title=""/>
+			<privatestaticmethods title=""/>
+			<privateattributes title=""/>
+			<privatestaticattributes title=""/>
+			<friends title=""/>
+			<related title="" subtitle=""/>
+			<membergroups visible="yes"/>
+		</memberdecl>
+		<detaileddescription title=""/>
+		<memberdef>
+			<inlineclasses title=""/>
+			<typedefs title=""/>
+			<enums title=""/>
+			<services title=""/>
+			<interfaces title=""/>
+			<constructors title=""/>
+			<functions title=""/>
+			<related title=""/>
+			<variables title=""/>
+			<properties title=""/>
+			<events title=""/>
+		</memberdef>
+		<allmemberslink visible="yes"/>
+		<usedfiles visible="$SHOW_USED_FILES"/>
+		<authorsection visible="yes"/>
+	</class>
+	<namespace>
+		<briefdescription visible="yes"/>
+		<memberdecl>
+			<nestednamespaces visible="yes" title=""/>
+			<constantgroups visible="yes" title=""/>
+			<interfaces visible="yes" title=""/>
+			<classes visible="yes" title=""/>
+			<concepts visible="yes" title=""/>
+			<structs visible="yes" title=""/>
+			<exceptions visible="yes" title=""/>
+			<typedefs title=""/>
+			<sequences title=""/>
+			<dictionaries title=""/>
+			<enums title=""/>
+			<functions title=""/>
+			<variables title=""/>
+			<properties title=""/>
+			<membergroups visible="yes"/>
+		</memberdecl>
+		<detaileddescription title=""/>
+		<memberdef>
+			<inlineclasses title=""/>
+			<typedefs title=""/>
+			<sequences title=""/>
+			<dictionaries title=""/>
+			<enums title=""/>
+			<functions title=""/>
+			<variables title=""/>
+			<properties title=""/>
+		</memberdef>
+		<authorsection visible="yes"/>
+	</namespace>
+	<concept>
+		<briefdescription visible="yes"/>
+		<includes visible="$SHOW_HEADERFILE"/>
+		<definition visible="yes" title=""/>
+		<detaileddescription title=""/>
+		<authorsection visible="yes"/>
+	</concept>
+	<file>
+		<briefdescription visible="yes"/>
+		<includes visible="$SHOW_INCLUDE_FILES"/>
+		<includegraph visible="yes"/>
+		<includedbygraph visible="yes"/>
+		<sourcelink visible="yes"/>
+		<memberdecl>
+			<interfaces visible="yes" title=""/>
+			<classes visible="yes" title=""/>
+			<structs visible="yes" title=""/>
+			<exceptions visible="yes" title=""/>
+			<namespaces visible="yes" title=""/>
+			<concepts visible="yes" title=""/>
+			<constantgroups visible="yes" title=""/>
+			<defines title=""/>
+			<typedefs title=""/>
+			<sequences title=""/>
+			<dictionaries title=""/>
+			<enums title=""/>
+			<functions title=""/>
+			<variables title=""/>
+			<properties title=""/>
+			<membergroups visible="yes"/>
+		</memberdecl>
+		<detaileddescription title=""/>
+		<memberdef>
+			<inlineclasses title=""/>
+			<defines title=""/>
+			<typedefs title=""/>
+			<sequences title=""/>
+			<dictionaries title=""/>
+			<enums title=""/>
+			<functions title=""/>
+			<variables title=""/>
+			<properties title=""/>
+		</memberdef>
+		<authorsection/>
+	</file>
+	<group>
+		<detaileddescription title=""/>
+		<groupgraph visible="yes"/>
+		<memberdecl>
+			<nestedgroups visible="yes" title=""/>
+			<modules visible="yes" title=""/>
+			<dirs visible="yes" title=""/>
+			<files visible="yes" title=""/>
+			<namespaces visible="yes" title=""/>
+			<concepts visible="yes" title=""/>
+			<classes visible="yes" title=""/>
+			<defines title=""/>
+			<typedefs title=""/>
+			<sequences title=""/>
+			<dictionaries title=""/>
+			<enums title=""/>
+			<enumvalues title=""/>
+			<functions title=""/>
+			<variables title=""/>
+			<signals title=""/>
+			<publicslots title=""/>
+			<protectedslots title=""/>
+			<privateslots title=""/>
+			<events title=""/>
+			<properties title=""/>
+			<friends title=""/>
+			<membergroups visible="yes"/>
+		</memberdecl>
+		<memberdef>
+			<pagedocs/>
+			<inlineclasses title=""/>
+			<defines title=""/>
+			<typedefs title=""/>
+			<sequences title=""/>
+			<dictionaries title=""/>
+			<enums title=""/>
+			<enumvalues title=""/>
+			<functions title=""/>
+			<variables title=""/>
+			<signals title=""/>
+			<publicslots title=""/>
+			<protectedslots title=""/>
+			<privateslots title=""/>
+			<events title=""/>
+			<properties title=""/>
+			<friends title=""/>
+		</memberdef>
+		<authorsection visible="yes"/>
+	</group>
+	<module>
+		<briefdescription visible="yes"/>
+		<exportedmodules visible="yes"/>
+		<memberdecl>
+			<concepts visible="yes" title=""/>
+			<classes visible="yes" title=""/>
+			<enums title=""/>
+			<typedefs title=""/>
+			<functions title=""/>
+			<variables title=""/>
+			<membergroups title=""/>
+		</memberdecl>
+		<detaileddescription title=""/>
+		<memberdecl>
+			<files visible="yes"/>
+		</memberdecl>
+	</module>
+	<directory>
+		<briefdescription visible="yes"/>
+		<directorygraph visible="yes"/>
+		<memberdecl>
+			<dirs visible="yes"/>
+			<files visible="yes"/>
+		</memberdecl>
+		<detaileddescription title=""/>
+	</directory>
+</doxygenlayout>
-- 
cgit v1.2.3


From 502fb8e8d1dcfe10f55fdef2cdfb71afec806204 Mon Sep 17 00:00:00 2001
From: Loek Le Blansch <loek@pipeframe.xyz>
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/layout.xml')

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 <class T>
-	BehaviorScript & set_script();
+	template <class T, typename... Args>
+	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 <class T>
-BehaviorScript & BehaviorScript::set_script() {
+template <class T, typename... Args>
+BehaviorScript & BehaviorScript::set_script(Args &&... args) {
 	dbg_trace();
 	static_assert(std::is_base_of<Script, T>::value);
-	Script * s = new T();
-	s->game_object_id = this->game_object_id;
+	Script * s = new T(std::forward<Args>(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<Script>(s);
 	return *this;
 }
diff --git a/src/crepe/api/Event.h b/src/crepe/api/Event.h
index 06cf7f3..ab4be2b 100644
--- a/src/crepe/api/Event.h
+++ b/src/crepe/api/Event.h
@@ -1,10 +1,12 @@
-// TODO discussing the location of these events
 #pragma once
+// TODO discussing the location of these events
 
 #include <string>
 
 #include "KeyCodes.h"
 
+namespace crepe {
+
 /**
  * \brief Base class for all event types in the system.
  */
@@ -91,11 +93,7 @@ public:
 /**
  * \brief Event triggered during a collision between objects.
  */
-class CollisionEvent : public Event {
-public:
-	//! Data describing the collision (currently not implemented).
-	// Collision collisionData;
-};
+class CollisionEvent : public Event { };
 
 /**
  * \brief Event triggered when text is submitted, e.g., from a text input.
@@ -110,3 +108,5 @@ public:
  * \brief Event triggered to indicate the application is shutting down.
  */
 class ShutDownEvent : public Event {};
+
+}
diff --git a/src/crepe/api/EventManager.h b/src/crepe/api/EventManager.h
index 348a04d..1a33023 100644
--- a/src/crepe/api/EventManager.h
+++ b/src/crepe/api/EventManager.h
@@ -77,7 +77,7 @@ public:
 	 * \param channel The channel to trigger the event on (default is CHANNEL_ALL, which triggers on all channels).
 	 */
 	template <typename EventType>
-	void trigger_event(const EventType & event, event_channel_t channel = CHANNEL_ALL);
+	void trigger_event(const EventType & event = {}, event_channel_t channel = CHANNEL_ALL);
 
 	/**
 	 * \brief Queue an event for later processing.
@@ -89,7 +89,7 @@ public:
 	 * \param channel The channel to associate with the event (default is CHANNEL_ALL).
 	 */
 	template <typename EventType>
-	void queue_event(const EventType & event, event_channel_t channel = CHANNEL_ALL);
+	void queue_event(const EventType & event = {}, event_channel_t channel = CHANNEL_ALL);
 
 	/**
 	 * \brief Process all queued events.
diff --git a/src/crepe/api/Script.cpp b/src/crepe/api/Script.cpp
index 9ebb074..d3fae07 100644
--- a/src/crepe/api/Script.cpp
+++ b/src/crepe/api/Script.cpp
@@ -9,3 +9,9 @@ Script::~Script() {
 	}
 }
 
+template <>
+void Script::subscribe(const EventHandler<CollisionEvent> & callback) {
+	const game_object_id_t & game_object_id = *this->game_object_id_ref;
+	this->subscribe_internal(callback, game_object_id);
+}
+
diff --git a/src/crepe/api/Script.h b/src/crepe/api/Script.h
index c9eb211..373b253 100644
--- a/src/crepe/api/Script.h
+++ b/src/crepe/api/Script.h
@@ -18,8 +18,10 @@ class ComponentManager;
  * This class is used as a base class for user-defined scripts that can be added to game
  * objects using the \c BehaviorScript component.
  *
- * \note Additional *events* (like Unity's OnDisable and OnEnable) should be implemented as
+ * \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().
+ *
+ * \see feature_script
  */
 class Script {
 protected:
@@ -88,18 +90,40 @@ protected:
 	void logf(Args &&... args);
 
 	/**
-	 * \brief Subscribe to an event
-	 *
+	 * \brief Subscribe to an event with an explicit channel
+	 * \see EventManager::subscribe
+	 */
+	template <typename EventType>
+	void subscribe(const EventHandler<EventType> & callback, event_channel_t channel);
+	/**
+	 * \brief Subscribe to an event on EventManager::CHANNEL_ALL
 	 * \see EventManager::subscribe
 	 */
 	template <typename EventType>
-	void subscribe(const EventHandler<EventType> & callback, event_channel_t channel = EventManager::CHANNEL_ALL);
+	void subscribe(const EventHandler<EventType> & callback);
 
 	//! \}
 
+private:
+	/**
+	 * \brief Internal subscribe function
+	 *
+	 * This function exists so certain template specializations of Script::subscribe can be
+	 * explicitly deleted, and does the following:
+	 * - Wrap the user-provided callback in a check that tests if the parent BehaviorScript
+	 *   component is still active
+	 * - Store the subscriber handle returned by the event manager so this listener is
+	 *   automatically unsubscribed at the end of this Script instance's life
+	 *
+	 * \tparam EventType concrete Event class
+	 * \param callback User-provided callback function
+	 * \param channel Event channel (may have been overridden by template specializations)
+	 */
+	template <typename EventType>
+	void subscribe_internal(const EventHandler<EventType> & callback, event_channel_t channel);
+
 protected:
-	// NOTE: Script must have a constructor without arguments so the game programmer doesn't need
-	// to manually add `using Script::Script` to their concrete script class.
+	// NOTE: This must be the only constructor on Script, see "Late references" below
 	Script() = default;
 	//! Only \c BehaviorScript instantiates Script
 	friend class BehaviorScript;
@@ -107,6 +131,7 @@ public:
 	// std::unique_ptr destroys script
 	virtual ~Script();
 
+private:
 	Script(const Script &) = delete;
 	Script(Script &&) = delete;
 	Script & operator=(const Script &) = delete;
@@ -119,10 +144,19 @@ private:
 	 * These references are set by BehaviorScript immediately after calling the constructor of
 	 * Script.
 	 *
+	 * \note Script must have a constructor without arguments so the game programmer doesn't need
+	 * to manually add `using Script::Script` to their concrete script class if they want to
+	 * implement a non-default constructor (e.g. for passing references to their own concrete
+	 * Script classes).
+	 *
+	 * \todo These should be converted to OptionalRef<> once `loek/util` is merged
+	 *
 	 * \{
 	 */
 	//! Game object ID of game object parent BehaviorScript is attached to
-	game_object_id_t game_object_id = -1;
+	const game_object_id_t * game_object_id_ref = nullptr;
+	//! Reference to parent component
+	bool * active_ref = nullptr;
 	//! Reference to component manager instance
 	ComponentManager * component_manager_ref = nullptr;
 	//! Reference to event manager instance
@@ -136,6 +170,18 @@ private:
 	std::vector<subscription_t> listeners;
 };
 
+/**
+ * \brief Subscribe to CollisionEvent for the current GameObject
+ *
+ * This is a template specialization for Script::subscribe which automatically sets the event
+ * channel so the callback handler is only called for CollisionEvent events that apply to the
+ * current GameObject the parent BehaviorScript is attached to.
+ */
+template <>
+void Script::subscribe(const EventHandler<CollisionEvent> & callback);
+template <>
+void Script::subscribe(const EventHandler<CollisionEvent> & callback, event_channel_t) = delete;
+
 } // namespace crepe
 
 #include "Script.hpp"
diff --git a/src/crepe/api/Script.hpp b/src/crepe/api/Script.hpp
index 42c8f0b..8186bd4 100644
--- a/src/crepe/api/Script.hpp
+++ b/src/crepe/api/Script.hpp
@@ -22,7 +22,7 @@ template <typename T>
 std::vector<std::reference_wrapper<T>> Script::get_components() const {
 	ComponentManager & mgr = *this->component_manager_ref;
 
-	return mgr.get_components_by_id<T>(this->game_object_id);
+	return mgr.get_components_by_id<T>(*this->game_object_id_ref);
 }
 
 template <typename... Args>
@@ -31,10 +31,24 @@ void Script::logf(Args &&... args) {
 }
 
 template <typename EventType>
-void Script::subscribe(const EventHandler<EventType> & callback, event_channel_t channel) {
+void Script::subscribe_internal(const EventHandler<EventType> & callback, event_channel_t channel) {
 	EventManager & mgr = *this->event_manager_ref;
-	subscription_t listener = mgr.subscribe<EventType>(callback, channel);
+	subscription_t listener = mgr.subscribe<EventType>([this, callback](const EventType & data) -> bool {
+		bool & active = *this->active_ref;
+		if (!active) return false;
+		return callback(data);
+	}, channel);
 	this->listeners.push_back(listener);
 }
 
+template <typename EventType>
+void Script::subscribe(const EventHandler<EventType> & callback, event_channel_t channel) {
+	this->subscribe_internal(callback, channel);
+}
+
+template <typename EventType>
+void Script::subscribe(const EventHandler<EventType> & callback) {
+	this->subscribe_internal(callback, EventManager::CHANNEL_ALL);
+}
+
 } // namespace crepe
diff --git a/src/doc/layout.xml b/src/doc/layout.xml
index 2244fa7..7f514d4 100644
--- a/src/doc/layout.xml
+++ b/src/doc/layout.xml
@@ -42,6 +42,7 @@
 	</navindex>
 	<class>
 		<briefdescription visible="yes"/>
+		<detaileddescription title=""/>
 		<includes visible="$SHOW_HEADERFILE"/>
 		<inheritancegraph visible="yes"/>
 		<collaborationgraph visible="yes"/>
@@ -79,7 +80,6 @@
 			<related title="" subtitle=""/>
 			<membergroups visible="yes"/>
 		</memberdecl>
-		<detaileddescription title=""/>
 		<memberdef>
 			<inlineclasses title=""/>
 			<typedefs title=""/>
diff --git a/src/test/ScriptTest.cpp b/src/test/ScriptTest.cpp
index 19fef6d..875c422 100644
--- a/src/test/ScriptTest.cpp
+++ b/src/test/ScriptTest.cpp
@@ -9,26 +9,44 @@
 #include <crepe/api/GameObject.h>
 #include <crepe/api/Script.h>
 #include <crepe/api/Vector2.h>
+#include <crepe/api/Event.h>
+#include <crepe/api/EventManager.h>
 #include <crepe/system/ScriptSystem.h>
 
 using namespace std;
 using namespace crepe;
 using namespace testing;
 
+class MyEvent : public Event { };
+
 class ScriptTest : public Test {
 public:
 	ComponentManager component_manager{};
 	ScriptSystem system{component_manager};
+	EventManager & evmgr = EventManager::get_instance();
 
 	class MyScript : public Script {
 		// NOTE: default (private) visibility of init and update shouldn't cause
 		// issues!
-		void init() { this->init_count++; }
-		void update() { this->update_count++; }
+		void init() {
+			this->init_count++;
+
+			subscribe<MyEvent>([this](const MyEvent &) {
+				this->event_count++;
+				return true;
+			});
+
+			// init should never be called more than once
+			EXPECT_LE(this->init_count, 1);
+		}
+		void update() {
+			this->update_count++;
+		}
 
 	public:
 		unsigned init_count = 0;
 		unsigned update_count = 0;
+		unsigned event_count = 0;
 	};
 
 	BehaviorScript * behaviorscript_ref = nullptr;
@@ -46,21 +64,58 @@ public:
 
 		this->script_ref = (MyScript *) this->behaviorscript_ref->script.get();
 		ASSERT_NE(this->script_ref, nullptr);
+
+		// sanity
+		ASSERT_EQ(script_ref->init_count, 0);
+		ASSERT_EQ(script_ref->update_count, 0);
+		ASSERT_EQ(script_ref->event_count, 0);
 	}
 };
 
 TEST_F(ScriptTest, Default) {
 	EXPECT_EQ(0, this->script_ref->init_count);
 	EXPECT_EQ(0, this->script_ref->update_count);
+	EXPECT_EQ(0, this->script_ref->event_count);
 }
 
 TEST_F(ScriptTest, UpdateOnce) {
+	this->system.update();
+	EXPECT_EQ(1, this->script_ref->init_count);
+	EXPECT_EQ(1, this->script_ref->update_count);
+	EXPECT_EQ(0, this->script_ref->event_count);
+}
+
+TEST_F(ScriptTest, UpdateInactive) {
+	this->behaviorscript_ref->active = false;
+	this->system.update();
 	EXPECT_EQ(0, this->script_ref->init_count);
 	EXPECT_EQ(0, this->script_ref->update_count);
+	EXPECT_EQ(0, this->script_ref->event_count);
+
+	this->behaviorscript_ref->active = true;
+	this->system.update();
+	EXPECT_EQ(1, this->script_ref->init_count);
+	EXPECT_EQ(1, this->script_ref->update_count);
+	EXPECT_EQ(0, this->script_ref->event_count);
+}
 
+TEST_F(ScriptTest, EventInactive) {
 	this->system.update();
+	this->behaviorscript_ref->active = false;
 	EXPECT_EQ(1, this->script_ref->init_count);
 	EXPECT_EQ(1, this->script_ref->update_count);
+	EXPECT_EQ(0, this->script_ref->event_count);
+
+	this->evmgr.trigger_event<MyEvent>();
+	EXPECT_EQ(1, this->script_ref->init_count);
+	EXPECT_EQ(1, this->script_ref->update_count);
+	EXPECT_EQ(0, this->script_ref->event_count);
+
+	this->behaviorscript_ref->active = true;
+	this->evmgr.trigger_event<MyEvent>();
+	EXPECT_EQ(1, this->script_ref->init_count);
+	EXPECT_EQ(1, this->script_ref->update_count);
+	EXPECT_EQ(1, this->script_ref->event_count);
 }
 
 TEST_F(ScriptTest, ListScripts) {
@@ -70,3 +125,4 @@ TEST_F(ScriptTest, ListScripts) {
 	}
 	ASSERT_EQ(1, script_count);
 }
+
-- 
cgit v1.2.3


From 610461763977597c5df213d272a514730dd2364e Mon Sep 17 00:00:00 2001
From: Loek Le Blansch <loek@pipeframe.xyz>
Date: Fri, 22 Nov 2024 16:33:08 +0100
Subject: add custom tabs to doxygen

---
 src/doc/layout.xml | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

(limited to 'src/doc/layout.xml')

diff --git a/src/doc/layout.xml b/src/doc/layout.xml
index 7f514d4..6bde443 100644
--- a/src/doc/layout.xml
+++ b/src/doc/layout.xml
@@ -2,8 +2,11 @@
 <doxygenlayout version="1.0">
 	<navindex>
 		<tab type="mainpage" visible="yes" title=""/>
+		<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="topics" visible="no" title="" intro=""/>
 		<tab type="modules" visible="yes" title="" intro="">
 			<tab type="modulelist" visible="yes" title="" intro=""/>
 			<tab type="modulemembers" visible="yes" title="" intro=""/>
-- 
cgit v1.2.3


From 1499363d85abedbdb571e33801b821f4dfabc638 Mon Sep 17 00:00:00 2001
From: Loek Le Blansch <loek@pipeframe.xyz>
Date: Fri, 22 Nov 2024 17:28:28 +0100
Subject: more documentation

---
 contributing.md                | 24 ++++++++++++++++++++++++
 src/crepe/api/Script.h         |  7 +++++--
 src/doc/internal/component.dox | 41 +++++++++++++++++++++++++++++++++++++++++
 src/doc/internal/resource.dox  | 12 ++++++++++++
 src/doc/internal/style.dox     |  9 +++++++++
 src/doc/internal/system.dox    | 26 ++++++++++++++++++++++++++
 src/doc/internals.dox          | 10 ++++++++++
 src/doc/layout.xml             | 16 ++++++++--------
 src/doc/style.css              |  2 ++
 9 files changed, 137 insertions(+), 10 deletions(-)
 create mode 100644 src/doc/internal/component.dox
 create mode 100644 src/doc/internal/resource.dox
 create mode 100644 src/doc/internal/style.dox
 create mode 100644 src/doc/internal/system.dox
 create mode 100644 src/doc/internals.dox

(limited to 'src/doc/layout.xml')

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; }
-- 
cgit v1.2.3