From 4da057cc49082192bbc45689d80dec3410e41f27 Mon Sep 17 00:00:00 2001 From: sfan5 Date: Wed, 12 Feb 2020 14:59:06 +0100 Subject: [PATCH] Script API: Document ObjectRef handling in a comment --- src/script/cpp_api/s_base.cpp | 14 ++++++++++++++ 1 file changed, 14 insertions(+) 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