Skip to content

Commit

Permalink
Update PackedArray explanation to match Godot 4.0 behavior (#10304)
Browse files Browse the repository at this point in the history
Add paragraphs describing the differences between PackedArray and
normal or typed Array.

---------

Co-authored-by: tetrapod <[email protected]>
  • Loading branch information
mechalynx and tetrapod00 authored Nov 22, 2024
1 parent 0ceba58 commit c0378ac
Showing 1 changed file with 20 additions and 6 deletions.
26 changes: 20 additions & 6 deletions tutorials/scripting/gdscript/gdscript_basics.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <class_Array_method_map>` that PackedArrays
lack. Consult the :ref:`class reference <class_PackedFloat32Array>` 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 <class_PackedByteArray>`: An array of bytes (integers from 0 to 255).
- :ref:`PackedInt32Array <class_PackedInt32Array>`: An array of 32-bit integers.
Expand Down

0 comments on commit c0378ac

Please sign in to comment.