From c0378ac9208a9faf210c70542625369dbfcfa33b Mon Sep 17 00:00:00 2001 From: mechalynx Date: Fri, 22 Nov 2024 03:21:58 +0200 Subject: [PATCH] Update PackedArray explanation to match Godot 4.0 behavior (#10304) Add paragraphs describing the differences between PackedArray and normal or typed Array. --------- Co-authored-by: tetrapod <145553014+tetrapod00@users.noreply.github.com> --- .../scripting/gdscript/gdscript_basics.rst | 26 ++++++++++++++----- 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/tutorials/scripting/gdscript/gdscript_basics.rst b/tutorials/scripting/gdscript/gdscript_basics.rst index d5656179c99..8c6947de20b 100644 --- a/tutorials/scripting/gdscript/gdscript_basics.rst +++ b/tutorials/scripting/gdscript/gdscript_basics.rst @@ -893,12 +893,26 @@ native or user class, or enum. Nested array types (like ``Array[Array[int]]``) a Packed arrays ^^^^^^^^^^^^^ -GDScript arrays are allocated linearly in memory for speed. -Large arrays (more than tens of thousands of elements) may however cause -memory fragmentation. If this is a concern, special types of -arrays are available. These only accept a single data type. They avoid memory -fragmentation and use less memory, but are atomic and tend to run slower than generic -arrays. They are therefore only recommended to use for large data sets: +PackedArrays are generally faster to iterate on and modify compared to a typed +Array of the same type (e.g. PackedInt64Array versus Array[int]) and consume +less memory. In the worst case, they are expected to be as fast as an untyped +Array. Conversely, non-Packed Arrays (typed or not) have extra convenience +methods such as :ref:`Array.map ` that PackedArrays +lack. Consult the :ref:`class reference ` for details +on the methods available. Typed Arrays are generally faster to iterate on and +modify than untyped Arrays. + +While all Arrays can cause memory fragmentation when they become large enough, +if memory usage and performance (iteration and modification speed) is a concern +and the type of data you're storing is compatible with one of the ``Packed`` +Array types, then using those may yield improvements. However, if you do not +have such concerns (e.g. the size of your array does not reach the tens of +thousands of elements) it is likely more helpful to use regular or typed +Arrays, as they provide convenience methods that can make your code easier to +write and maintain (and potentially faster if your data requires such +operations a lot). If the data you will store is of a known type (including +your own defined classes), prefer to use a typed Array as it may yield better +performance in iteration and modification compared to an untyped Array. - :ref:`PackedByteArray `: An array of bytes (integers from 0 to 255). - :ref:`PackedInt32Array `: An array of 32-bit integers.