godotengine / godotengine/godot-docs

Clarify array- / dictionary-typed variable defaults

Open
#12,195 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
reStructuredText
Stars
5.7k
Forks
3.8k
Avg merge
1d 20h
Merged PRs (30d)
25

Description

**Your Godot version:**
Godot 4.7 documentation

**Issue description:**
The documentation does clearly state that primitives (`int`, `String`, `bool`) are initialized as empty. This is logical, given that they are passed by copy rather than by reference.

But, because arrays and dictionaries are passed by reference instead, the documentation needs to clarify what happens when we do this:

```gdscript
var array: Array
print(array)
array.append("abc")

var dict: Dictionary
print(dict)
dict["abc"] = 4

var typedArray: PackedInt32Array
print(typedArray)
typedArray.append(1234)

# applies to other Packed*Array types
```

Does this crash at runtime? Does it print an empty array / dictionary? Do the assignments work?

If unassigned arrays / dictionaries are given empty instances (which the docs seem to suggest, but do not state clearly), then, since arrays / dictionaries are passed by reference, does this mean that the following wastefully generates an unused array / dictionary that is immediately replaced?

```gdscript
var array: Array
var dict: Dictionary

array = [1, 2, 3]
dict = {"a": 1, "b": 2}
```

It is evident that the default value cannot be `null`, since that isn't a legal value (even though that would be far more preferable):

```gdscript
var array: Array = null # Cannot assign a value of type "null" as "Array".
array = null # Cannot assign a value of type "null" as "Array".
```

Finally, the docs also need to clarify garbage collection protocol for arrays and dictionaries. This is clearly documented for objects, which are not freed automatically, unless we use `RefCounted` and the count reaches 0.

Like objects, dictionaries and arrays are also passed by reference. But, because the docs don't clarify GC protocol, it becomes unclear whether or not something like the following creates a memory leak:

```gdscript
var dict: Dictionary
for i in 50:
dict = {"a": {"b": {}}}
dict.a.b.c = dict
# if Dictionary extends something like RefCounted, this creates a memory leak
```

Leaving out details like this makes it very hard for professionals to use a good engine like Godot with confidence that their code doesn't contain severe memory leaks or other issues.

**URL to the documentation page (if already existing):**
https://docs.godotengine.org/en/4.7/tutorials/scripting/gdscript/gdscript_basics.html#initialization-order

Contributor guide

No contributing guide indexed for this repository

Research direction

Start at the linked GDScript basics page and its “Initialization order” section. Check the shown unassigned Array, Dictionary, and Packed*Array examples against the documented language behavior, including the reference and cyclic-container questions. Done means the documentation clearly states default values, assignment behavior, and memory-management expectations for these cases.

Written by the indexing model from the issue text.

Assessment

Tech stack
godot
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.