godotengine / godotengine/godot-docs
Clarify array- / dictionary-typed variable defaults
- 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