From: sfan5 <sfan5@live.de>
Date: Wed, 12 Feb 2020 13:59:06 +0000 (+0100)
Subject: Script API: Document ObjectRef handling in a comment
X-Git-Tag: 5.2.0~106
X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=4da057cc49082192bbc45689d80dec3410e41f27;p=oweals%2Fminetest.git

Script API: Document ObjectRef handling in a comment
---

diff --git a/src/script/cpp_api/s_base.cpp b/src/script/cpp_api/s_base.cpp
index 1f40bb06a..ecb1ba39b 100644
--- a/src/script/cpp_api/s_base.cpp
+++ b/src/script/cpp_api/s_base.cpp
@@ -333,6 +333,20 @@ void ScriptApiBase::setOriginFromTableRaw(int index, const char *fxn)
 #endif
 }
 
+/*
+ * How ObjectRefs are handled in Lua:
+ * When an active object is created, an ObjectRef is created on the Lua side
+ * and stored in core.object_refs[id].
+ * Methods that require an ObjectRef to a certain object retrieve it from that
+ * table instead of creating their own.(*)
+ * When an active object is removed, the existing ObjectRef is invalidated
+ * using ::set_null() and removed from the core.object_refs table.
+ * (*) An exception to this are NULL ObjectRefs and anonymous ObjectRefs
+ *     for objects without ID.
+ *     It's unclear what the latter are needed for and their use is problematic
+ *     since we lose control over the ref and the contained pointer.
+ */
+
 void ScriptApiBase::addObjectReference(ServerActiveObject *cobj)
 {
 	SCRIPTAPI_PRECHECKHEADER