classref: Sync with current 3.6 branch (46104d488)

classes/class_@gdscript.rst

@@ -722,7 +722,7 @@ Returns the Object that corresponds to ``instance_id``. All Objects have a uniqu
 
 - :ref:`float<class_float>` **inverse_lerp** **(** :ref:`float<class_float>` from, :ref:`float<class_float>` to, :ref:`float<class_float>` weight **)**
 
-Returns an interpolation or extrapolation factor considering the range specified in ``from`` and ``to``, and the interpolated value specified in ``weight``. The returned value will be between ``0.0`` and ``1.0`` if ``weight`` is between ``from`` and ``to`` (inclusive). If ``weight`` is located outside this range, then an extrapolation factor will be returned (return value lower than ``0.0`` or greater than ``1.0``).
+Returns an interpolation or extrapolation factor considering the range specified in ``from`` and ``to``, and the interpolated value specified in ``weight``. The returned value will be between ``0.0`` and ``1.0`` if ``weight`` is between ``from`` and ``to`` (inclusive). If ``weight`` is located outside this range, then an extrapolation factor will be returned (return value lower than ``0.0`` or greater than ``1.0``). Use :ref:`clamp<class_@GDScript_method_clamp>` on the result of :ref:`inverse_lerp<class_@GDScript_method_inverse_lerp>` if this is not desired.
 
 ::
 
@@ -733,7 +733,7 @@ Returns an interpolation or extrapolation factor considering the range specified
     var ratio = inverse_lerp(20, 30, 27.5)
     # `ratio` is now 0.75.
 
-See also :ref:`lerp<class_@GDScript_method_lerp>` which performs the reverse of this operation.
+See also :ref:`lerp<class_@GDScript_method_lerp>` which performs the reverse of this operation, and :ref:`range_lerp<class_@GDScript_method_range_lerp>` to map a continuous series of values to another.
 
 ----
 
@@ -802,7 +802,7 @@ Returns length of Variant ``var``. Length is the character count of String, elem
 
 - :ref:`Variant<class_Variant>` **lerp** **(** :ref:`Variant<class_Variant>` from, :ref:`Variant<class_Variant>` to, :ref:`float<class_float>` weight **)**
 
-Linearly interpolates between two values by the factor defined in ``weight``. To perform interpolation, ``weight`` should be between ``0.0`` and ``1.0`` (inclusive). However, values outside this range are allowed and can be used to perform *extrapolation*.
+Linearly interpolates between two values by the factor defined in ``weight``. To perform interpolation, ``weight`` should be between ``0.0`` and ``1.0`` (inclusive). However, values outside this range are allowed and can be used to perform *extrapolation*. Use :ref:`clamp<class_@GDScript_method_clamp>` on the result of :ref:`lerp<class_@GDScript_method_lerp>` if this is not desired.
 
 If the ``from`` and ``to`` arguments are of type :ref:`int<class_int>` or :ref:`float<class_float>`, the return value is a :ref:`float<class_float>`.
 
@@ -813,7 +813,7 @@ If both are of the same vector type (:ref:`Vector2<class_Vector2>`, :ref:`Vector
     lerp(0, 4, 0.75) # Returns 3.0
     lerp(Vector2(1, 5), Vector2(3, 2), 0.5) # Returns Vector2(2, 3.5)
 
-See also :ref:`inverse_lerp<class_@GDScript_method_inverse_lerp>` which performs the reverse of this operation. To perform eased interpolation with :ref:`lerp<class_@GDScript_method_lerp>`, combine it with :ref:`ease<class_@GDScript_method_ease>` or :ref:`smoothstep<class_@GDScript_method_smoothstep>`.
+See also :ref:`inverse_lerp<class_@GDScript_method_inverse_lerp>` which performs the reverse of this operation. To perform eased interpolation with :ref:`lerp<class_@GDScript_method_lerp>`, combine it with :ref:`ease<class_@GDScript_method_ease>` or :ref:`smoothstep<class_@GDScript_method_smoothstep>`. See also :ref:`range_lerp<class_@GDScript_method_range_lerp>` to map a continuous series of values to another.
 
 ----
 
@@ -1293,12 +1293,14 @@ Output:
 
 - :ref:`float<class_float>` **range_lerp** **(** :ref:`float<class_float>` value, :ref:`float<class_float>` istart, :ref:`float<class_float>` istop, :ref:`float<class_float>` ostart, :ref:`float<class_float>` ostop **)**
 
-Maps a ``value`` from range ``[istart, istop]`` to ``[ostart, ostop]``.
+Maps a ``value`` from range ``[istart, istop]`` to ``[ostart, ostop]``. See also :ref:`lerp<class_@GDScript_method_lerp>` and :ref:`inverse_lerp<class_@GDScript_method_inverse_lerp>`. If ``value`` is outside ``[istart, istop]``, then the resulting value will also be outside ``[ostart, ostop]``. Use :ref:`clamp<class_@GDScript_method_clamp>` on the result of :ref:`range_lerp<class_@GDScript_method_range_lerp>` if this is not desired.
 
 ::
 
     range_lerp(75, 0, 100, -1, 1) # Returns 0.5
 
+For complex use cases where you need multiple ranges, consider using :ref:`Curve<class_Curve>` or :ref:`Gradient<class_Gradient>` instead.
+
 ----
 
 .. _class_@GDScript_method_round:

classes/class_@globalscope.rst

@@ -667,7 +667,7 @@ enum **KeyList**:
 
 - **KEY_TAB** = **16777218** --- Tab key.
 
-- **KEY_BACKTAB** = **16777219** --- Shift+Tab key.
+- **KEY_BACKTAB** = **16777219** --- Shift + Tab key.
 
 - **KEY_BACKSPACE** = **16777220** --- Backspace key.
 
@@ -1944,6 +1944,8 @@ Since :ref:`OK<class_@GlobalScope_constant_OK>` has value 0, and all other failu
 
 .. _class_@GlobalScope_constant_PROPERTY_HINT_IMAGE_COMPRESS_LOSSLESS:
 
+.. _class_@GlobalScope_constant_PROPERTY_HINT_LOCALE_ID:
+
 enum **PropertyHint**:
 
 - **PROPERTY_HINT_NONE** = **0** --- No hint for the edited property.
@@ -2000,6 +2002,8 @@ Unlike :ref:`PROPERTY_HINT_ENUM<class_@GlobalScope_constant_PROPERTY_HINT_ENUM>`
 
 - **PROPERTY_HINT_IMAGE_COMPRESS_LOSSLESS** = **24** --- Hints that an image is compressed using lossless compression.
 
+- **PROPERTY_HINT_LOCALE_ID** = **40** --- Hints that a string property is a locale code. Editing it will show a locale dialog for picking language and country.
+
 ----
 
 .. _enum_@GlobalScope_PropertyUsageFlags:

classes/class_animationnode.rst

@@ -63,7 +63,7 @@ Methods
 +-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | :ref:`Array<class_Array>`           | :ref:`get_parameter_list<class_AnimationNode_method_get_parameter_list>` **(** **)** |virtual|                                                                                                                                                                                                                                                             |
 +-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`String<class_String>`         | :ref:`has_filter<class_AnimationNode_method_has_filter>` **(** **)** |virtual|                                                                                                                                                                                                                                                                             |
+| :ref:`bool<class_bool>`             | :ref:`has_filter<class_AnimationNode_method_has_filter>` **(** **)** |virtual|                                                                                                                                                                                                                                                                             |
 +-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | :ref:`bool<class_bool>`             | :ref:`is_path_filtered<class_AnimationNode_method_is_path_filtered>` **(** :ref:`NodePath<class_NodePath>` path **)** |const|                                                                                                                                                                                                                              |
 +-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -170,23 +170,23 @@ Blend another animation node (in case this node contains children animation node
 
 - :ref:`String<class_String>` **get_caption** **(** **)** |virtual|
 
-Gets the text caption for this node (used by some editors).
+When inheriting from :ref:`AnimationRootNode<class_AnimationRootNode>`, implement this virtual method to override the text caption for this node.
 
 ----
 
 .. _class_AnimationNode_method_get_child_by_name:
 
 - :ref:`Object<class_Object>` **get_child_by_name** **(** :ref:`String<class_String>` name **)** |virtual|
 
-Gets a child node by index (used by editors inheriting from :ref:`AnimationRootNode<class_AnimationRootNode>`).
+When inheriting from :ref:`AnimationRootNode<class_AnimationRootNode>`, implement this virtual method to return a child node by its ``name``.
 
 ----
 
 .. _class_AnimationNode_method_get_child_nodes:
 
 - :ref:`Dictionary<class_Dictionary>` **get_child_nodes** **(** **)** |virtual|
 
-Gets all children nodes in order as a ``name: node`` dictionary. Only useful when inheriting :ref:`AnimationRootNode<class_AnimationRootNode>`.
+When inheriting from :ref:`AnimationRootNode<class_AnimationRootNode>`, implement this virtual method to return all children nodes in order as a ``name: node`` dictionary.
 
 ----
 
@@ -218,23 +218,23 @@ Gets the value of a parameter. Parameters are custom local memory used for your
 
 - :ref:`Variant<class_Variant>` **get_parameter_default_value** **(** :ref:`String<class_String>` name **)** |virtual|
 
-Gets the default value of a parameter. Parameters are custom local memory used for your nodes, given a resource can be reused in multiple trees.
+When inheriting from :ref:`AnimationRootNode<class_AnimationRootNode>`, implement this virtual method to return the default value of parameter "``name``". Parameters are custom local memory used for your nodes, given a resource can be reused in multiple trees.
 
 ----
 
 .. _class_AnimationNode_method_get_parameter_list:
 
 - :ref:`Array<class_Array>` **get_parameter_list** **(** **)** |virtual|
 
-Gets the property information for parameter. Parameters are custom local memory used for your nodes, given a resource can be reused in multiple trees. Format is similar to :ref:`Object.get_property_list<class_Object_method_get_property_list>`.
+When inheriting from :ref:`AnimationRootNode<class_AnimationRootNode>`, implement this virtual method to return a list of the properties on this node. Parameters are custom local memory used for your nodes, given a resource can be reused in multiple trees. Format is similar to :ref:`Object.get_property_list<class_Object_method_get_property_list>`.
 
 ----
 
 .. _class_AnimationNode_method_has_filter:
 
-- :ref:`String<class_String>` **has_filter** **(** **)** |virtual|
+- :ref:`bool<class_bool>` **has_filter** **(** **)** |virtual|
 
-Returns ``true`` whether you want the blend tree editor to display filter editing on this node.
+When inheriting from :ref:`AnimationRootNode<class_AnimationRootNode>`, implement this virtual method to return whether the blend tree editor should display filter editing on this node.
 
 ----
 
@@ -250,7 +250,7 @@ Returns whether the given path is filtered.
 
 - void **process** **(** :ref:`float<class_float>` time, :ref:`bool<class_bool>` seek **)** |virtual|
 
-User-defined callback called when a custom node is processed. The ``time`` parameter is a relative delta, unless ``seek`` is ``true``, in which case it is absolute.
+When inheriting from :ref:`AnimationRootNode<class_AnimationRootNode>`, implement this virtual method to run some code when this node is processed. The ``time`` parameter is a relative delta, unless ``seek`` is ``true``, in which case it is absolute.
 
 Here, call the :ref:`blend_input<class_AnimationNode_method_blend_input>`, :ref:`blend_node<class_AnimationNode_method_blend_node>` or :ref:`blend_animation<class_AnimationNode_method_blend_animation>` functions. You can also use :ref:`get_parameter<class_AnimationNode_method_get_parameter>` and :ref:`set_parameter<class_AnimationNode_method_set_parameter>` to modify local memory.
 

classes/class_animationnodestatemachinetransition.rst

@@ -79,7 +79,7 @@ Property Descriptions
 | *Getter*  | get_advance_condition()      |
 +-----------+------------------------------+
 
-Turn on auto advance when this condition is set. The provided name will become a boolean parameter on the :ref:`AnimationTree<class_AnimationTree>` that can be controlled from code (see `#controlling-from-code <../tutorials/animation/animation_tree.html#controlling-from-code>`__ in :doc:`../tutorials/animation/animation_tree`). For example, if :ref:`AnimationTree.tree_root<class_AnimationTree_property_tree_root>` is an :ref:`AnimationNodeStateMachine<class_AnimationNodeStateMachine>` and :ref:`advance_condition<class_AnimationNodeStateMachineTransition_property_advance_condition>` is set to ``"idle"``:
+Turn on auto advance when this condition is set. The provided name will become a boolean parameter on the :ref:`AnimationTree<class_AnimationTree>` that can be controlled from code (see `Using AnimationTree <../tutorials/animation/animation_tree.html#controlling-from-code>`__). For example, if :ref:`AnimationTree.tree_root<class_AnimationTree_property_tree_root>` is an :ref:`AnimationNodeStateMachine<class_AnimationNodeStateMachine>` and :ref:`advance_condition<class_AnimationNodeStateMachineTransition_property_advance_condition>` is set to ``"idle"``:
 
 ::
 

classes/class_animationplayer.rst

@@ -426,7 +426,7 @@ Returns the name of ``animation`` or an empty string if not found.
 
 - :ref:`Animation<class_Animation>` **get_animation** **(** :ref:`String<class_String>` name **)** |const|
 
-Returns the :ref:`Animation<class_Animation>` with key ``name`` or ``null`` if not found.
+Returns the :ref:`Animation<class_Animation>` with the key ``name``. If the animation does not exist, ``null`` is returned and an error is logged.
 
 ----
 

classes/class_audioeffectcapture.rst

@@ -19,7 +19,16 @@ Description
 
 AudioEffectCapture is an AudioEffect which copies all audio frames from the attached audio effect bus into its internal ring buffer.
 
-Application code should consume these audio frames from this ring buffer using :ref:`get_buffer<class_AudioEffectCapture_method_get_buffer>` and process it as needed, for example to capture data from a microphone, implement application defined effects, or to transmit audio over the network. When capturing audio data from a microphone, the format of the samples will be stereo 32-bit floating point PCM.
+Application code should consume these audio frames from this ring buffer using :ref:`get_buffer<class_AudioEffectCapture_method_get_buffer>` and process it as needed, for example to capture data from an :ref:`AudioStreamMicrophone<class_AudioStreamMicrophone>`, implement application-defined effects, or to transmit audio over the network. When capturing audio data from a microphone, the format of the samples will be stereo 32-bit floating point PCM.
+
+\ **Note:** :ref:`ProjectSettings.audio/enable_audio_input<class_ProjectSettings_property_audio/enable_audio_input>` must be ``true`` for audio input to work. See also that setting's description for caveats related to permissions and operating system privacy settings.
+
+Tutorials
+---------
+
+- :doc:`Audio buses <../tutorials/audio/audio_buses>`
+
+- `Audio Mic Record Demo <https://github.com/godotengine/godot-demo-projects/tree/master/audio/mic_record>`__
 
 Properties
 ----------

classes/class_audioserver.rst

@@ -187,7 +187,9 @@ Number of available audio buses.
 | *Getter*  | capture_get_device()      |
 +-----------+---------------------------+
 
-Name of the current device for audio input (see :ref:`get_device_list<class_AudioServer_method_get_device_list>`). On systems with multiple audio inputs (such as analog, USB and HDMI audio), this can be used to select the audio input device. The value ``"Default"`` will record audio on the system-wide default audio input. If an invalid device name is set, the value will be reverted back to ``"Default"``.
+Name of the current device for audio input (see :ref:`capture_get_device_list<class_AudioServer_method_capture_get_device_list>`). On systems with multiple audio inputs (such as analog, USB and HDMI audio), this can be used to select the audio input device. The value ``"Default"`` will record audio on the system-wide default audio input. If an invalid device name is set, the value will be reverted back to ``"Default"``.
+
+\ **Note:** :ref:`ProjectSettings.audio/enable_audio_input<class_ProjectSettings_property_audio/enable_audio_input>` must be ``true`` for audio input to work. See also that setting's description for caveats related to permissions and operating system privacy settings.
 
 ----
 
@@ -246,6 +248,8 @@ Adds an :ref:`AudioEffect<class_AudioEffect>` effect to the bus ``bus_idx`` at `
 
 Returns the names of all audio input devices detected on the system.
 
+\ **Note:** :ref:`ProjectSettings.audio/enable_audio_input<class_ProjectSettings_property_audio/enable_audio_input>` must be ``true`` for audio input to work. See also that setting's description for caveats related to permissions and operating system privacy settings.
+
 ----
 
 .. _class_AudioServer_method_generate_bus_layout:

classes/class_audiostreammicrophone.rst

@@ -12,7 +12,19 @@ AudioStreamMicrophone
 
 **Inherits:** :ref:`AudioStream<class_AudioStream>` **<** :ref:`Resource<class_Resource>` **<** :ref:`Reference<class_Reference>` **<** :ref:`Object<class_Object>`
 
+Plays real-time audio input data.
 
+Description
+-----------
+
+When used directly in an :ref:`AudioStreamPlayer<class_AudioStreamPlayer>` node, ``AudioStreamMicrophone`` plays back microphone input in real-time. This can be used in conjunction with :ref:`AudioEffectCapture<class_AudioEffectCapture>` to process the data or save it.
+
+\ **Note:** :ref:`ProjectSettings.audio/enable_audio_input<class_ProjectSettings_property_audio/enable_audio_input>` must be ``true`` for audio input to work. See also that setting's description for caveats related to permissions and operating system privacy settings.
+
+Tutorials
+---------
+
+- `Audio Mic Record Demo <https://github.com/godotengine/godot-demo-projects/tree/master/audio/mic_record>`__
 
 .. |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.)`