diff --git a/engine_details/architecture/core_types.rst b/engine_details/architecture/core_types.rst index be5f976e7cc..7e4d8fc069c 100644 --- a/engine_details/architecture/core_types.rst +++ b/engine_details/architecture/core_types.rst @@ -150,6 +150,21 @@ scripting API. .. |typed_dictionary| replace:: `TypedDictionary `__ .. |pair| replace:: `Pair `__ +Relocation safety +^^^^^^^^^^^^^^^^^ + +Godot's containers assume their elements are `trivially relocatable `__. + +This means that, if you store data types in it that have pointers to themselves, or are otherwise +`not trivially relocatable `__, +Godot might crash. Note that storing **pointers to** objects that are not trivially relocatable, such as some Object +subclasses, is unproblematic and supported. + +The reason to assume trivial relocatability is that it allows us to make use of important optimization techniques, such +as relocation by ``memcpy`` or ``realloc``. + +`GH-100509 `__ tracks this decision. + .. _doc_core_concurrency_types: Multithreading / Concurrency