classref: Sync with current master branch (9c31ef2)

classes/class_@gdscript.rst

@@ -950,6 +950,8 @@ Method Descriptions
 
 :ref:`Color<class_Color>` **Color8**\ (\ r8\: :ref:`int<class_int>`, g8\: :ref:`int<class_int>`, b8\: :ref:`int<class_int>`, a8\: :ref:`int<class_int>` = 255\ ) :ref:`🔗<class_@GDScript_method_Color8>`
 
+**Deprecated:** Use :ref:`Color.from_rgba8<class_Color_method_from_rgba8>` instead.
+
 Returns a :ref:`Color<class_Color>` constructed from red (``r8``), green (``g8``), blue (``b8``), and optionally alpha (``a8``) integer channels, each divided by ``255.0`` for their final value. Using :ref:`Color8<class_@GDScript_method_Color8>` instead of the standard :ref:`Color<class_Color>` constructor is useful when you need to match exact color values in an :ref:`Image<class_Image>`.
 
 ::
@@ -1038,6 +1040,8 @@ Converts ``what`` to ``type`` in the best way possible. The ``type`` uses the :r
 
 :ref:`Object<class_Object>` **dict_to_inst**\ (\ dictionary\: :ref:`Dictionary<class_Dictionary>`\ ) :ref:`🔗<class_@GDScript_method_dict_to_inst>`
 
+**Deprecated:** Consider using :ref:`JSON.to_native<class_JSON_method_to_native>` or :ref:`Object.get_property_list<class_Object_method_get_property_list>` instead.
+
 Converts a ``dictionary`` (created with :ref:`inst_to_dict<class_@GDScript_method_inst_to_dict>`) back to an Object instance. Can be useful for deserializing.
 
 .. rst-class:: classref-item-separator
@@ -1083,9 +1087,9 @@ Starting from ``_ready()``, ``bar()`` would print:
 
 :ref:`Dictionary<class_Dictionary>` **inst_to_dict**\ (\ instance\: :ref:`Object<class_Object>`\ ) :ref:`🔗<class_@GDScript_method_inst_to_dict>`
 
-Returns the passed ``instance`` converted to a Dictionary. Can be useful for serializing.
+**Deprecated:** Consider using :ref:`JSON.from_native<class_JSON_method_from_native>` or :ref:`Object.get_property_list<class_Object_method_get_property_list>` instead.
 
-\ **Note:** Cannot be used to serialize objects with built-in scripts attached or objects allocated within built-in scripts.
+Returns the passed ``instance`` converted to a Dictionary. Can be useful for serializing.
 
 ::
 
@@ -1102,6 +1106,10 @@ Prints out:
     [@subpath, @path, foo]
     [, res://test.gd, bar]
 
+\ **Note:** This function can only be used to serialize objects with an attached :ref:`GDScript<class_GDScript>` stored in a separate file. Objects without an attached script, with a script written in another language, or with a built-in script are not supported.
+
+\ **Note:** This function is not recursive, which means that nested objects will not be represented as dictionaries. Also, properties passed by reference (:ref:`Object<class_Object>`, :ref:`Dictionary<class_Dictionary>`, :ref:`Array<class_Array>`, and packed arrays) are copied by reference, not duplicated.
+
 .. rst-class:: classref-item-separator
 
 ----

classes/class_@globalscope.rst

@@ -2329,7 +2329,7 @@ Key Code mask.
 
 .. rst-class:: classref-enumeration-constant
 
-:ref:`KeyModifierMask<enum_@GlobalScope_KeyModifierMask>` **KEY_MODIFIER_MASK** = ``532676608``
+:ref:`KeyModifierMask<enum_@GlobalScope_KeyModifierMask>` **KEY_MODIFIER_MASK** = ``2130706432``
 
 Modifier key mask.
 
@@ -5767,9 +5767,9 @@ Returns a human-readable name for the given :ref:`Error<enum_@GlobalScope_Error>
 ::
 
     print(OK)                              # Prints 0
-    print(error_string(OK))                # Prints OK
-    print(error_string(ERR_BUSY))          # Prints Busy
-    print(error_string(ERR_OUT_OF_MEMORY)) # Prints Out of memory
+    print(error_string(OK))                # Prints "OK"
+    print(error_string(ERR_BUSY))          # Prints "Busy"
+    print(error_string(ERR_OUT_OF_MEMORY)) # Prints "Out of memory"
 
 .. rst-class:: classref-item-separator
 
@@ -5934,24 +5934,24 @@ Returns the :ref:`Object<class_Object>` that corresponds to ``instance_id``. All
 
  .. code-tab:: gdscript
 
-    var foo = "bar"
+    var drink = "water"
 
     func _ready():
         var id = get_instance_id()
-        var inst = instance_from_id(id)
-        print(inst.foo) # Prints bar
+        var instance = instance_from_id(id)
+        print(instance.foo) # Prints "water"
 
  .. code-tab:: csharp
 
     public partial class MyNode : Node
     {
-        public string Foo { get; set; } = "bar";
+        public string Drink { get; set; } = "water";
 
         public override void _Ready()
         {
             ulong id = GetInstanceId();
-            var inst = (MyNode)InstanceFromId(Id);
-            GD.Print(inst.Foo); // Prints bar
+            var instance = (MyNode)InstanceFromId(Id);
+            GD.Print(instance.Drink); // Prints "water"
         }
     }
 
@@ -6448,12 +6448,12 @@ Converts one or more arguments of any type to string in the best way possible an
  .. code-tab:: gdscript
 
     var a = [1, 2, 3]
-    print("a", "b", a) # Prints ab[1, 2, 3]
+    print("a", "b", a) # Prints "ab[1, 2, 3]"
 
  .. code-tab:: csharp
 
-    var a = new Godot.Collections.Array { 1, 2, 3 };
-    GD.Print("a", "b", a); // Prints ab[1, 2, 3]
+    Godot.Collections.Array a = [1, 2, 3];
+    GD.Print("a", "b", a); // Prints "ab[1, 2, 3]"
 
 
 
@@ -6482,11 +6482,11 @@ When printing to standard output, the supported subset of BBCode is converted to
 
  .. code-tab:: gdscript
 
-    print_rich("[color=green][b]Hello world![/b][/color]") # Prints out "Hello world!" in green with a bold font
+    print_rich("[color=green][b]Hello world![/b][/color]") # Prints "Hello world!", in green with a bold font.
 
  .. code-tab:: csharp
 
-    GD.PrintRich("[color=green][b]Hello world![/b][/color]"); // Prints out "Hello world!" in green with a bold font
+    GD.PrintRich("[color=green][b]Hello world![/b][/color]"); // Prints "Hello world!", in green with a bold font.
 
 
 
@@ -6552,17 +6552,17 @@ Prints one or more arguments to strings in the best way possible to the OS termi
 
  .. code-tab:: gdscript
 
+    # Prints "ABC" to terminal.
     printraw("A")
     printraw("B")
     printraw("C")
-    # Prints ABC to terminal
 
  .. code-tab:: csharp
 
+    // Prints "ABC" to terminal.
     GD.PrintRaw("A");
     GD.PrintRaw("B");
     GD.PrintRaw("C");
-    // Prints ABC to terminal
 
 
 
@@ -6583,11 +6583,11 @@ Prints one or more arguments to the console with a space between each argument.
 
  .. code-tab:: gdscript
 
-    prints("A", "B", "C") # Prints A B C
+    prints("A", "B", "C") # Prints "A B C"
 
  .. code-tab:: csharp
 
-    GD.PrintS("A", "B", "C"); // Prints A B C
+    GD.PrintS("A", "B", "C"); // Prints "A B C"
 
 
 
@@ -6608,11 +6608,11 @@ Prints one or more arguments to the console with a tab between each argument.
 
  .. code-tab:: gdscript
 
-    printt("A", "B", "C") # Prints A       B       C
+    printt("A", "B", "C") # Prints "A       B       C"
 
  .. code-tab:: csharp
 
-    GD.PrintT("A", "B", "C"); // Prints A       B       C
+    GD.PrintT("A", "B", "C"); // Prints "A       B       C"
 
 
 
@@ -6633,11 +6633,11 @@ Pushes an error message to Redot's built-in debugger and to the OS terminal.
 
  .. code-tab:: gdscript
 
-    push_error("test error") # Prints "test error" to debugger and terminal as error call
+    push_error("test error") # Prints "test error" to debugger and terminal as an error.
 
  .. code-tab:: csharp
 
-    GD.PushError("test error"); // Prints "test error" to debugger and terminal as error call
+    GD.PushError("test error"); // Prints "test error" to debugger and terminal as an error.
 
 
 
@@ -6660,11 +6660,11 @@ Pushes a warning message to Redot's built-in debugger and to the OS terminal.
 
  .. code-tab:: gdscript
 
-    push_warning("test warning") # Prints "test warning" to debugger and terminal as warning call
+    push_warning("test warning") # Prints "test warning" to debugger and terminal as a warning.
 
  .. code-tab:: csharp
 
-    GD.PushWarning("test warning"); // Prints "test warning" to debugger and terminal as warning call
+    GD.PushWarning("test warning"); // Prints "test warning" to debugger and terminal as a warning.
 
 
 
@@ -7337,9 +7337,9 @@ Returns a human-readable name of the given ``type``, using the :ref:`Variant.Typ
 
 ::
 
-    print(TYPE_INT) # Prints 2.
-    print(type_string(TYPE_INT)) # Prints "int".
-    print(type_string(TYPE_STRING)) # Prints "String".
+    print(TYPE_INT) # Prints 2
+    print(type_string(TYPE_INT)) # Prints "int"
+    print(type_string(TYPE_STRING)) # Prints "String"
 
 See also :ref:`typeof<class_@GlobalScope_method_typeof>`.
 
@@ -7360,10 +7360,10 @@ Returns the internal type of the given ``variable``, using the :ref:`Variant.Typ
     var json = JSON.new()
     json.parse('["a", "b", "c"]')
     var result = json.get_data()
-    if typeof(result) == TYPE_ARRAY:
-        print(result[0]) # Prints a
+    if result is Array:
+        print(result[0]) # Prints "a"
     else:
-        print("Unexpected result")
+        print("Unexpected result!")
 
 See also :ref:`type_string<class_@GlobalScope_method_type_string>`.
 

classes/class_array.rst

@@ -35,14 +35,14 @@ An array data structure that can contain a sequence of elements of any :ref:`Var
 
  .. code-tab:: csharp
 
-    var array = new Godot.Collections.Array{"First", 2, 3, "Last"};
+    Godot.Collections.Array array = ["First", 2, 3, "Last"];
     GD.Print(array[0]); // Prints "First"
     GD.Print(array[2]); // Prints 3
-    GD.Print(array[array.Count - 1]); // Prints "Last"
+    GD.Print(array[^1]); // Prints "Last"
 
-    array[2] = "Second";
+    array[1] = "Second";
     GD.Print(array[1]); // Prints "Second"
-    GD.Print(array[array.Count - 3]); // Prints "Second"
+    GD.Print(array[^3]); // Prints "Second"
 
 
 
@@ -707,7 +707,7 @@ This method can often be combined with :ref:`resize<class_Array_method_resize>`
 
  .. code-tab:: csharp
 
-    var array = new Godot.Collections.Array();
+    Godot.Collections.Array array = [];
     array.Resize(5);
     array.Fill(2);
     GD.Print(array); // Prints [2, 2, 2, 2, 2]
@@ -784,7 +784,7 @@ Returns the index of the **first** element in the array that causes ``method`` t
         return number % 2 == 0
 
     func _ready():
-        print([1, 3, 4, 7].find_custom(is_even.bind())) # prints 2
+        print([1, 3, 4, 7].find_custom(is_even.bind())) # Prints 2
 
 
 
@@ -874,7 +874,7 @@ Returns ``true`` if the array contains the given ``value``.
 
  .. code-tab:: csharp
 
-    var arr = new Godot.Collections.Array { "inside", 7 };
+    Godot.Collections.Array arr = ["inside", 7];
     // By C# convention, this method is renamed to `Contains`.
     GD.Print(arr.Contains("inside"));  // Prints True
     GD.Print(arr.Contains("outside")); // Prints False
@@ -1068,7 +1068,7 @@ Returns a random element from the array. Generates an error and returns ``null``
 
  .. code-tab:: csharp
 
-    var array = new Godot.Collections.Array { 1, 2, 3.25f, "Hi" };
+    Godot.Collections.Array array = [1, 2, 3.25f, "Hi"];
     GD.Print(array.PickRandom()); // May print 1, 2, 3.25, or "Hi".
 
 
@@ -1172,10 +1172,10 @@ If :ref:`max<class_Array_method_max>` is not desirable, this method may also be
 ::
 
     func _ready():
-        var arr = [Vector2(5, 0), Vector2(3, 4), Vector2(1, 2)]
+        var arr = [Vector2i(5, 0), Vector2i(3, 4), Vector2i(1, 2)]
 
         var longest_vec = arr.reduce(func(max, vec): return vec if is_length_greater(vec, max) else max)
-        print(longest_vec) # Prints Vector2(3, 4).
+        print(longest_vec) # Prints (3, 4)
 
     func is_length_greater(a, b):
         return a.length() > b.length()
@@ -1189,11 +1189,11 @@ This method can also be used to count how many elements in an array satisfy a ce
 
     func _ready():
         var arr = [1, 2, 3, 4, 5]
-        # Increment count if it's even, else leaves count the same.
+        # If the current element is even, increment count, otherwise leave count the same.
         var even_count = arr.reduce(func(count, next): return count + 1 if is_even(next) else count, 0)
         print(even_count) # Prints 2
 
-See also :ref:`map<class_Array_method_map>`, :ref:`filter<class_Array_method_filter>`, :ref:`any<class_Array_method_any>` and :ref:`all<class_Array_method_all>`.
+See also :ref:`map<class_Array_method_map>`, :ref:`filter<class_Array_method_filter>`, :ref:`any<class_Array_method_any>`, and :ref:`all<class_Array_method_all>`.
 
 .. rst-class:: classref-item-separator
 
@@ -1355,7 +1355,7 @@ Sorts the array in ascending order. The final order is dependent on the "less th
 
  .. code-tab:: csharp
 
-    var numbers = new Godot.Collections.Array { 10, 5, 2.5, 8 };
+    Godot.Collections.Array numbers = [10, 5, 2.5, 8];
     numbers.Sort();
     GD.Print(numbers); // Prints [2.5, 5, 8, 10]
 
@@ -1448,8 +1448,8 @@ Appends the ``right`` array to the left operand, creating a new **Array**. This
  .. code-tab:: csharp
 
     // Note that concatenation is not possible with C#'s native Array type.
-    var array1 = new Godot.Collections.Array{"One", 2};
-    var array2 = new Godot.Collections.Array{3, "Four"};
+    Godot.Collections.Array array1 = ["One", 2];
+    Godot.Collections.Array array2 = [3, "Four"];
     GD.Print(array1 + array2); // Prints ["One", 2, 3, "Four"]
 
 

classes/class_arraymesh.rst

@@ -46,16 +46,16 @@ The most basic example is the creation of a single triangle:
 
  .. code-tab:: csharp
 
-    var vertices = new Vector3[]
-    {
+    Vector3[] vertices =
+    [
         new Vector3(0, 1, 0),
         new Vector3(1, 0, 0),
         new Vector3(0, 0, 1),
-    };
+    ];
 
     // Initialize the ArrayMesh.
     var arrMesh = new ArrayMesh();
-    var arrays = new Godot.Collections.Array();
+    Godot.Collections.Array arrays = [];
     arrays.Resize((int)Mesh.ArrayType.Max);
     arrays[(int)Mesh.ArrayType.Vertex] = vertices;
 
@@ -240,7 +240,7 @@ The ``blend_shapes`` argument is an array of vertex data for each blend shape. E
 
 The ``lods`` argument is a dictionary with :ref:`float<class_float>` keys and :ref:`PackedInt32Array<class_PackedInt32Array>` values. Each entry in the dictionary represents an LOD level of the surface, where the value is the :ref:`Mesh.ARRAY_INDEX<class_Mesh_constant_ARRAY_INDEX>` array to use for the LOD level and the key is roughly proportional to the distance at which the LOD stats being used. I.e., increasing the key of an LOD also increases the distance that the objects has to be from the camera before the LOD is used.
 
-The ``flags`` argument is the bitwise or of, as required: One value of :ref:`ArrayCustomFormat<enum_Mesh_ArrayCustomFormat>` left shifted by ``ARRAY_FORMAT_CUSTOMn_SHIFT`` for each custom channel in use, :ref:`Mesh.ARRAY_FLAG_USE_DYNAMIC_UPDATE<class_Mesh_constant_ARRAY_FLAG_USE_DYNAMIC_UPDATE>`, :ref:`Mesh.ARRAY_FLAG_USE_8_BONE_WEIGHTS<class_Mesh_constant_ARRAY_FLAG_USE_8_BONE_WEIGHTS>`, or :ref:`Mesh.ARRAY_FLAG_USES_EMPTY_VERTEX_ARRAY<class_Mesh_constant_ARRAY_FLAG_USES_EMPTY_VERTEX_ARRAY>`.
+The ``flags`` argument is the bitwise OR of, as required: One value of :ref:`ArrayCustomFormat<enum_Mesh_ArrayCustomFormat>` left shifted by ``ARRAY_FORMAT_CUSTOMn_SHIFT`` for each custom channel in use, :ref:`Mesh.ARRAY_FLAG_USE_DYNAMIC_UPDATE<class_Mesh_constant_ARRAY_FLAG_USE_DYNAMIC_UPDATE>`, :ref:`Mesh.ARRAY_FLAG_USE_8_BONE_WEIGHTS<class_Mesh_constant_ARRAY_FLAG_USE_8_BONE_WEIGHTS>`, or :ref:`Mesh.ARRAY_FLAG_USES_EMPTY_VERTEX_ARRAY<class_Mesh_constant_ARRAY_FLAG_USES_EMPTY_VERTEX_ARRAY>`.
 
 \ **Note:** When using indices, it is recommended to only use points, lines, or triangles.
 

classes/class_astargrid2d.rst

@@ -41,8 +41,8 @@ To use **AStarGrid2D**, you only need to set the :ref:`region<class_AStarGrid2D_
     astarGrid.Region = new Rect2I(0, 0, 32, 32);
     astarGrid.CellSize = new Vector2I(16, 16);
     astarGrid.Update();
-    GD.Print(astarGrid.GetIdPath(Vector2I.Zero, new Vector2I(3, 4))); // prints (0, 0), (1, 1), (2, 2), (3, 3), (3, 4)
-    GD.Print(astarGrid.GetPointPath(Vector2I.Zero, new Vector2I(3, 4))); // prints (0, 0), (16, 16), (32, 32), (48, 48), (48, 64)
+    GD.Print(astarGrid.GetIdPath(Vector2I.Zero, new Vector2I(3, 4))); // Prints [(0, 0), (1, 1), (2, 2), (3, 3), (3, 4)]
+    GD.Print(astarGrid.GetPointPath(Vector2I.Zero, new Vector2I(3, 4))); // Prints [(0, 0), (16, 16), (32, 32), (48, 48), (48, 64)]
 
 
 

classes/class_basis.rst

@@ -598,7 +598,9 @@ Creates a new **Basis** with a rotation such that the forward axis (-Z) points t
 
 By default, the -Z axis (camera forward) is treated as forward (implies +X is right). If ``use_model_front`` is ``true``, the +Z axis (asset front) is treated as forward (implies +X is left) and points toward the ``target`` position.
 
-The up axis (+Y) points as close to the ``up`` vector as possible while staying perpendicular to the forward axis. The returned basis is orthonormalized (see :ref:`orthonormalized<class_Basis_method_orthonormalized>`). The ``target`` and ``up`` vectors cannot be :ref:`Vector3.ZERO<class_Vector3_constant_ZERO>`, and cannot be parallel to each other.
+The up axis (+Y) points as close to the ``up`` vector as possible while staying perpendicular to the forward axis. The returned basis is orthonormalized (see :ref:`orthonormalized<class_Basis_method_orthonormalized>`).
+
+The ``target`` and the ``up`` cannot be :ref:`Vector3.ZERO<class_Vector3_constant_ZERO>`, and shouldn't be colinear to avoid unintended rotation around local Z axis.
 
 .. rst-class:: classref-item-separator