Improve the components manual

Author: 60k41p

documentation/Components.md

@@ -4,11 +4,31 @@ Stagehand introduces facilities and patterns to streamline working with componen
 
 ## Defining and Registering Components
 
-Through macros, boilerplate-free component definition and registration of components is possible. The macros also handle the per-component setup of [automatic change detection](ChangeDetection.md) behind the scenes.
-
+Through macros, boilerplate-free component definition and registration of components is possible. The macros also handle the per-component setup of [automatic change detection](ChangeDetection.md) behind the scenes. Appending an underscore to a macro name (e.g., `FLOAT_` instead of `FLOAT`) opts out of change detection for that component.
 
 ### Manually defined & registered components
 
+When none of the macro categories below fit your needs — for example, when defining a component that inherits from an arbitrary base class or requires custom Flecs hooks — you can register components manually using the `REGISTER` macro together with the Flecs and Stagehand APIs directly.
+
+```cpp
+// 1. Define your struct.
+struct Velocity {
+    float x = 0.0f;
+    float y = 0.0f;
+    float z = 0.0f;
+};
+
+// 2. Register it. stagehand::register_component<T>() enables GDScript get/set access.
+REGISTER([](flecs::world& world) {
+    world.component<Velocity>()
+        .member<float>("x")
+        .member<float>("y")
+        .member<float>("z");
+    stagehand::register_component<Velocity>("Velocity");
+});
+```
+
+Change detection is not set up automatically with manual registration. To add it, declare a tag struct and call `stagehand::internal::register_change_detection_for_component<T, ChangeTag>(world)` inside your `REGISTER` block.
 
 ### Primitive C++ Types
 
@@ -75,12 +95,16 @@ UINT64(AVeryHighInteger, 53925713520814); // Initialised with a default value.
 ### Other C++ Types
 
 #### `TAG(Name)` / `TAG_(Name)`
+
+Empty marker component for entity classification and filtering. Tags carry no data; change detection does not apply to them.
 ```cpp
 TAG(IsPlayer); // Defines a tag component.
-TAG_(IsGrounded); // Alias for TAG, no change detection applicable for tags.
+TAG_(IsGrounded); // Alias for TAG; change detection is not applicable to tags.
 ```
 
 #### `ENUM(Name, [UnderlyingType])` / `ENUM_(Name, [UnderlyingType])`
+
+Registers an existing C++ `enum class` as an ECS component. The optional `UnderlyingType` tells Stagehand which integer type to use for GDScript serialisation; it should match the enum's declared underlying type (defaults to `uint8_t`).
 ```cpp
 enum class AIState { Idle, Patrol, Chase };
 ENUM(AIState); // Defaults to uint8_t underlying type.
@@ -93,24 +117,32 @@ ENUM_(Weather); // Opt out of change detection.
 ```
 
 #### `POINTER(Name, Type, [DefaultValue])` / `POINTER_(Name, Type, [DefaultValue])`
+
+Component wrapping a raw `Type*` pointer to an external object. Default-initialises to `nullptr` unless a value is provided.
 ```cpp
 POINTER(CurrentTarget, Targetable); // Default-initialised to nullptr.
 POINTER(GameWindow, void, nullptr); // Initialised with an explicit default value.
 ```
 
 #### `VECTOR(Name, ElementType, [Initialiser])` / `VECTOR_(Name, ElementType, [Initialiser])`
+
+Dynamic-size array component backed by `std::vector<ElementType>`.
 ```cpp
 VECTOR(PathNodes, godot::Vector3); // Default-initialised to an empty vector.
 VECTOR(ItemIDs, int, {10, 23, 42}); // Initialised with a default list.
 ```
 
-#### `ARRAY(Name, ElementType, Size, [Initialiser])` / `ARRAY_(Name, ElementType, Size, [Initialiser])`
+#### `ARRAY(Name, ElementType, Count, [Initialiser])` / `ARRAY_(Name, ElementType, Count, [Initialiser])`
+
+Fixed-size array component backed by `std::array<ElementType, Count>`. `Count` must be a compile-time constant.
 ```cpp
 ARRAY(InputBuffer, uint8_t, 8); // An array of 8 elements that are default-initialised.
 ARRAY(ModelView, float, 4, {1,0,0,1}); // Initialised with a default list.
 ```
 
 #### `STRUCT(Name, { ... })` / `STRUCT_(Name, { ... })`
+
+Multi-field aggregate struct component with automatic member reflection via Boost.PFR. All fields are individually registered with Flecs and exposed to GDScript as a `Dictionary`. The struct must be an aggregate type: no user-declared constructors, no virtual functions, and no private or protected non-static data members. All field types must be individually convertible to `godot::Variant`.
 ```cpp
 STRUCT(PlayerStats, { float age; int rank; }); // Members are default-initialised.
 STRUCT(ColoredPoint, { godot::Vector3 position = godot::Vector3(0, 0, 0); godot::Color color = godot::Color(1, 1, 1); }); // Members initialised with default values.
@@ -121,7 +153,7 @@ STRUCT_(TrackedPosition, { float x = 0.0f; float y = 0.0f; float z = 0.0f; }); /
 
 #### `GODOT_VARIANT(Name, Type, [DefaultValue])` / `GODOT_VARIANT_(Name, Type, [DefaultValue])`
 
-These macros wrap Godot's built-in Variant types as components. They support both struct-based (Plain Old Data) types and class-based (handle) types.
+These macros wrap Godot's built-in Variant types as components. They support both struct-based (Plain Old Data) types and class-based (handle) types. `GODOT_VARIANT` includes change detection; `GODOT_VARIANT_` opts out of it.
 
 #### Struct-based (Plain Old Data) Variants
 ```cpp