Skip to content

Commit 6be7150

Browse files
committedFeb 23, 2020
Documementation: Add advice on lifetime of ObjectRefs
1 parent 217f3a4 commit 6be7150

File tree

1 file changed

+14
-1
lines changed

1 file changed

+14
-1
lines changed
 

‎doc/lua_api.txt

+14-1
Original file line numberDiff line numberDiff line change
@@ -5706,8 +5706,21 @@ Can be gotten via `minetest.get_node_timer(pos)`.
57065706
-----------
57075707

57085708
Moving things in the game are generally these.
5709+
This is basically a reference to a C++ `ServerActiveObject`.
5710+
5711+
### Advice on handling `ObjectRefs`
5712+
5713+
When you receive an `ObjectRef` as a callback argument or from another API
5714+
function, it is possible to store the reference somewhere and keep it around.
5715+
It will keep functioning until the object is unloaded or removed.
5716+
5717+
However, doing this is **NOT** recommended as there is (intentionally) no method
5718+
to test if a previously acquired `ObjectRef` is still valid.
5719+
Instead, `ObjectRefs` should be "let go" of as soon as control is returned from
5720+
Lua back to the engine.
5721+
Doing so is much less error-prone and you will never need to wonder if the
5722+
object you are working with still exists.
57095723

5710-
This is basically a reference to a C++ `ServerActiveObject`
57115724

57125725
### Methods
57135726

0 commit comments

Comments
 (0)
Please sign in to comment.