classref: Sync with current master branch (68412af)

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_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_audiostreamgenerator.rst

@@ -31,14 +31,14 @@ Here's a sample on how to use it to generate a sine wave:
     var playback # Will hold the AudioStreamGeneratorPlayback.
     @onready var sample_hz = $AudioStreamPlayer.stream.mix_rate
     var pulse_hz = 440.0 # The frequency of the sound wave.
+    var phase = 0.0
 
     func _ready():
         $AudioStreamPlayer.play()
         playback = $AudioStreamPlayer.get_stream_playback()
         fill_buffer()
 
     func fill_buffer():
-        var phase = 0.0
         var increment = pulse_hz / sample_hz
         var frames_available = playback.get_frames_available()
 
@@ -53,6 +53,7 @@ Here's a sample on how to use it to generate a sine wave:
     private AudioStreamGeneratorPlayback _playback; // Will hold the AudioStreamGeneratorPlayback.
     private float _sampleHz;
     private float _pulseHz = 440.0f; // The frequency of the sound wave.
+    private double phase = 0.0;
 
     public override void _Ready()
     {
@@ -67,7 +68,6 @@ Here's a sample on how to use it to generate a sine wave:
 
     public void FillBuffer()
     {
-        double phase = 0.0;
         float increment = _pulseHz / _sampleHz;
         int framesAvailable = _playback.GetFramesAvailable();
 
@@ -101,11 +101,60 @@ Properties
 .. table::
    :widths: auto
 
-   +---------------------------+-------------------------------------------------------------------------+-------------+
-   | :ref:`float<class_float>` | :ref:`buffer_length<class_AudioStreamGenerator_property_buffer_length>` | ``0.5``     |
-   +---------------------------+-------------------------------------------------------------------------+-------------+
-   | :ref:`float<class_float>` | :ref:`mix_rate<class_AudioStreamGenerator_property_mix_rate>`           | ``44100.0`` |
-   +---------------------------+-------------------------------------------------------------------------+-------------+
+   +-------------------------------------------------------------------------------------------+-------------------------------------------------------------------------+-------------+
+   | :ref:`float<class_float>`                                                                 | :ref:`buffer_length<class_AudioStreamGenerator_property_buffer_length>` | ``0.5``     |
+   +-------------------------------------------------------------------------------------------+-------------------------------------------------------------------------+-------------+
+   | :ref:`float<class_float>`                                                                 | :ref:`mix_rate<class_AudioStreamGenerator_property_mix_rate>`           | ``44100.0`` |
+   +-------------------------------------------------------------------------------------------+-------------------------------------------------------------------------+-------------+
+   | :ref:`AudioStreamGeneratorMixRate<enum_AudioStreamGenerator_AudioStreamGeneratorMixRate>` | :ref:`mix_rate_mode<class_AudioStreamGenerator_property_mix_rate_mode>` | ``2``       |
+   +-------------------------------------------------------------------------------------------+-------------------------------------------------------------------------+-------------+
+
+.. rst-class:: classref-section-separator
+
+----
+
+.. rst-class:: classref-descriptions-group
+
+Enumerations
+------------
+
+.. _enum_AudioStreamGenerator_AudioStreamGeneratorMixRate:
+
+.. rst-class:: classref-enumeration
+
+enum **AudioStreamGeneratorMixRate**: :ref:`🔗<enum_AudioStreamGenerator_AudioStreamGeneratorMixRate>`
+
+.. _class_AudioStreamGenerator_constant_MIX_RATE_OUTPUT:
+
+.. rst-class:: classref-enumeration-constant
+
+:ref:`AudioStreamGeneratorMixRate<enum_AudioStreamGenerator_AudioStreamGeneratorMixRate>` **MIX_RATE_OUTPUT** = ``0``
+
+Current :ref:`AudioServer<class_AudioServer>` output mixing rate.
+
+.. _class_AudioStreamGenerator_constant_MIX_RATE_INPUT:
+
+.. rst-class:: classref-enumeration-constant
+
+:ref:`AudioStreamGeneratorMixRate<enum_AudioStreamGenerator_AudioStreamGeneratorMixRate>` **MIX_RATE_INPUT** = ``1``
+
+Current :ref:`AudioServer<class_AudioServer>` input mixing rate.
+
+.. _class_AudioStreamGenerator_constant_MIX_RATE_CUSTOM:
+
+.. rst-class:: classref-enumeration-constant
+
+:ref:`AudioStreamGeneratorMixRate<enum_AudioStreamGenerator_AudioStreamGeneratorMixRate>` **MIX_RATE_CUSTOM** = ``2``
+
+Custom mixing rate, specified by :ref:`mix_rate<class_AudioStreamGenerator_property_mix_rate>`.
+
+.. _class_AudioStreamGenerator_constant_MIX_RATE_MAX:
+
+.. rst-class:: classref-enumeration-constant
+
+:ref:`AudioStreamGeneratorMixRate<enum_AudioStreamGenerator_AudioStreamGeneratorMixRate>` **MIX_RATE_MAX** = ``3``
+
+Maximum value for the mixing rate mode enum.
 
 .. rst-class:: classref-section-separator
 
@@ -150,6 +199,27 @@ In games, common sample rates in use are ``11025``, ``16000``, ``22050``, ``3200
 
 According to the `Nyquist-Shannon sampling theorem <https://en.wikipedia.org/wiki/Nyquist%E2%80%93Shannon_sampling_theorem>`__, there is no quality difference to human hearing when going past 40,000 Hz (since most humans can only hear up to ~20,000 Hz, often less). If you are generating lower-pitched sounds such as voices, lower sample rates such as ``32000`` or ``22050`` may be usable with no loss in quality.
 
+\ **Note:** **AudioStreamGenerator** is not automatically resampling input data, to produce expected result :ref:`mix_rate_mode<class_AudioStreamGenerator_property_mix_rate_mode>` should match the sampling rate of input data.
+
+\ **Note:** If you are using :ref:`AudioEffectCapture<class_AudioEffectCapture>` as the source of your data, set :ref:`mix_rate_mode<class_AudioStreamGenerator_property_mix_rate_mode>` to :ref:`MIX_RATE_INPUT<class_AudioStreamGenerator_constant_MIX_RATE_INPUT>` or :ref:`MIX_RATE_OUTPUT<class_AudioStreamGenerator_constant_MIX_RATE_OUTPUT>` to automatically match current :ref:`AudioServer<class_AudioServer>` mixing rate.
+
+.. rst-class:: classref-item-separator
+
+----
+
+.. _class_AudioStreamGenerator_property_mix_rate_mode:
+
+.. rst-class:: classref-property
+
+:ref:`AudioStreamGeneratorMixRate<enum_AudioStreamGenerator_AudioStreamGeneratorMixRate>` **mix_rate_mode** = ``2`` :ref:`🔗<class_AudioStreamGenerator_property_mix_rate_mode>`
+
+.. rst-class:: classref-property-setget
+
+- |void| **set_mix_rate_mode**\ (\ value\: :ref:`AudioStreamGeneratorMixRate<enum_AudioStreamGenerator_AudioStreamGeneratorMixRate>`\ )
+- :ref:`AudioStreamGeneratorMixRate<enum_AudioStreamGenerator_AudioStreamGeneratorMixRate>` **get_mix_rate_mode**\ (\ )
+
+Mixing rate mode. If set to :ref:`MIX_RATE_CUSTOM<class_AudioStreamGenerator_constant_MIX_RATE_CUSTOM>`, :ref:`mix_rate<class_AudioStreamGenerator_property_mix_rate>` is used, otherwise current :ref:`AudioServer<class_AudioServer>` mixing rate is used.
+
 .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
 .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
 .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`