1 files changed, 68 insertions, 0 deletions
diff --git a/src/doc/feature/script.dox b/src/doc/feature/script.dox
new file mode 100644
index 0000000..162b0f5
--- /dev/null
+++ b/src/doc/feature/script.dox
@@ -0,0 +1,68 @@
+// vim:ft=doxygen
+namespace crepe {
+/**
+
+\defgroup feature_script Scripting basics
+\ingroup feature
+\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 \ref GameObject "game objects" using the \ref
+BehaviorScript \ref Component "component".
+
+\see Script
+\see BehaviorScript
+\see GameObject
+
+\par Example
+
+\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 three functions (\ref Script::init "\c init()",
+\ref Script::fixed_update "\c fixed_update()" and \ref Script::frame_update
+"\c frame_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>
+#include <crepe/api/BehaviorScript.h>
+
+class MyScript : public crepe::Script {
+	void init() {
+		// called once
+	}
+
+	void fixed_update(crepe::duration_t delta_time) {
+		// called on fixed update
+	}
+	void frame_update(crepe::duration_t delta_time) {
+		// called for every rendered frame
+	}
+};
+```
+
+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;
+
+// Create a BehaviorScript component to hold MyScript
+BehaviorScript & behavior_script = obj.add_component<BehaviorScript>();
+
+// Instantiate (and attach) MyScript to behavior_script
+behavior_script.set_script<MyScript>();
+```
+
+The above can also be done in a single call for convenience:
+```cpp
+obj.add_component<BehaviorScript>().set_script<MyScript>();
+```
+
+*/
+}