Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update PackedArray explanation to match Godot 4.0 behavior #10304

Merged
merged 3 commits into from
Nov 22, 2024
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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. PackedInt32Array versus Array[int]) and consume
mechalynx marked this conversation as resolved.
Show resolved Hide resolved
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`
mechalynx marked this conversation as resolved.
Show resolved Hide resolved
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