Documementation: Add advice on lifetime of ObjectRefs

This commit is contained in:
sfan5 2020-02-13 19:44:38 +01:00
parent 217f3a42f4
commit 6be7150cd5

@ -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