Add documentations on the optional API

Author: SMJSProductions

docs/getting-started/dependency-setup.md

@@ -12,10 +12,7 @@ Add the following in your `mod.json`:
 ```json
 {
   "dependencies": {
-    "smjs.object-collab": {
-      "version": ">={the latest version}",
-      "required": true
-    }
+    "smjs.object-collab": ">={the latest version}"
   }
 }
 ```

docs/utilities/optional-api.md

@@ -0,0 +1,41 @@
+---
+title: Optional API
+order: 3
+---
+
+# Optional API
+
+Object-Collab comes with a small optional API to get access to the internal object register. This way you can find the details about an object and under what IDs they are registered without explicitly depending on Object-Collab.
+
+All information provided by this method is made as minimal as possible to avoid over-reliance on Object-Collab to resolve the information.
+
+## Example
+
+### Mod.json
+
+```json
+{
+  "dependencies": {
+		"smjs.object-collab": {
+      "version": ">={the latest version}",
+      "required": false
+    }
+  }
+}
+```
+
+### C++
+
+```cpp
+#include <smjs.object-collab/include/object_collab_optional.hpp>
+
+using namespace object_collab::prelude;
+
+void MyObjectHandling::handleCustomObjects() {
+    object_collab::getOptionalRegister().listen([](OptionalRegister objectRegister) {
+        for (auto& [numericID, info] : objectRegister) {
+            // Do whatever you want with the object.
+        }
+    });
+}
+```

include/object_collab.hpp

@@ -18,6 +18,7 @@
 
 namespace object_collab {
     namespace prelude {
+        using namespace object_collab;
         using namespace editor_popup;
     }
 }

include/Optionals.hpp include/object_collab_optional.hppinclude/Optionals.hpp renamed to include/object_collab_optional.hpp

@@ -6,6 +6,10 @@
 #define MY_MOD_ID "smjs.object-collab"
 
 namespace object_collab {
+    namespace prelude {
+        using namespace object_collab;
+    }
+
     /// The simplified object info for optional inclusions
     struct OptionalObjectInfo {
         std::string id;
@@ -20,5 +24,6 @@ namespace object_collab {
     using OptionalRegister = std::unordered_map<uint32_t, OptionalObjectInfo>;
 
     /// Gets the simplified register
+    /// @warning Numeric IDs are subject to change between levels. It's not recommended to cache the output of this method.
     inline geode::Result<OptionalRegister> getOptionalRegister() GEODE_EVENT_EXPORT(&getOptionalRegister, ());
 }