From 6be7150cd5c18869911bcba8e5833155521d2780 Mon Sep 17 00:00:00 2001 From: sfan5 Date: Thu, 13 Feb 2020 19:44:38 +0100 Subject: Documementation: Add advice on lifetime of ObjectRefs --- doc/lua_api.txt | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/lua_api.txt b/doc/lua_api.txt index b87353b6a..75ad07cad 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -5706,8 +5706,21 @@ Can be gotten via `minetest.get_node_timer(pos)`. ----------- Moving things in the game are generally these. +This is basically a reference to a C++ `ServerActiveObject`. + +### Advice on handling `ObjectRefs` + +When you receive an `ObjectRef` as a callback argument or from another API +function, it is possible to store the reference somewhere and keep it around. +It will keep functioning until the object is unloaded or removed. + +However, doing this is **NOT** recommended as there is (intentionally) no method +to test if a previously acquired `ObjectRef` is still valid. +Instead, `ObjectRefs` should be "let go" of as soon as control is returned from +Lua back to the engine. +Doing so is much less error-prone and you will never need to wonder if the +object you are working with still exists. -This is basically a reference to a C++ `ServerActiveObject` ### Methods -- cgit v1.2.3