classref: Sync with current 3.5 branch (26a28d6bb)

classes/[email protected]

@@ -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_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,7 +170,7 @@ 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.
 
 ----
 
@@ -178,7 +178,7 @@ Gets the text caption for this node (used by some editors).
 
 - :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``.
 
 ----
 
@@ -186,7 +186,7 @@ Gets a child node by index (used by editors inheriting from :ref:`AnimationRootN
 
 - :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,7 +218,7 @@ 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.
 
 ----
 
@@ -226,15 +226,15 @@ Gets the default value of a parameter. Parameters are custom local memory used f
 
 - :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.)`

classes/class_audiostreamplayer2d.rst

@@ -17,7 +17,9 @@ Plays positional sound in 2D space.
 Description
 -----------
 
-Plays audio that dampens with distance from screen center.
+Plays audio that dampens with distance from a given position.
+
+By default, audio is heard from the screen center. This can be changed by adding a :ref:`Listener2D<class_Listener2D>` node to the scene and enabling it by calling :ref:`Listener2D.make_current<class_Listener2D_method_make_current>` on it.
 
 See also :ref:`AudioStreamPlayer<class_AudioStreamPlayer>` to play a sound non-positionally.
 

classes/class_camera.rst

@@ -270,6 +270,8 @@ For reference, the default vertical field of view value (``70.0``) is equivalent
 
 The camera's frustum offset. This can be changed from the default to create "tilted frustum" effects such as `Y-shearing <https://zdoom.org/wiki/Y-shearing>`__.
 
+\ **Note:** Only effective if :ref:`projection<class_Camera_property_projection>` is :ref:`PROJECTION_FRUSTUM<class_Camera_constant_PROJECTION_FRUSTUM>`.
+
 ----
 
 .. _class_Camera_property_h_offset:
@@ -348,7 +350,7 @@ The camera's projection mode. In :ref:`PROJECTION_PERSPECTIVE<class_Camera_const
 | *Getter*  | get_size()      |
 +-----------+-----------------+
 
-The camera's size measured as 1/2 the width or height. Only applicable in orthogonal and frustum modes. Since :ref:`keep_aspect<class_Camera_property_keep_aspect>` locks on axis, ``size`` sets the other axis' size length.
+The camera's size in meters measured as the diameter of the width or height, depending on :ref:`keep_aspect<class_Camera_property_keep_aspect>`. Only applicable in orthogonal and frustum modes.
 
 ----
 
@@ -471,7 +473,7 @@ Enables or disables the given ``layer`` in the :ref:`cull_mask<class_Camera_prop
 
 - void **set_frustum** **(** :ref:`float<class_float>` size, :ref:`Vector2<class_Vector2>` offset, :ref:`float<class_float>` z_near, :ref:`float<class_float>` z_far **)**
 
-Sets the camera projection to frustum mode (see :ref:`PROJECTION_FRUSTUM<class_Camera_constant_PROJECTION_FRUSTUM>`), by specifying a ``size``, an ``offset``, and the ``z_near`` and ``z_far`` clip planes in world space units.
+Sets the camera projection to frustum mode (see :ref:`PROJECTION_FRUSTUM<class_Camera_constant_PROJECTION_FRUSTUM>`), by specifying a ``size``, an ``offset``, and the ``z_near`` and ``z_far`` clip planes in world space units. See also :ref:`frustum_offset<class_Camera_property_frustum_offset>`.
 
 ----
 

classes/class_canvasitem.rst

@@ -21,7 +21,7 @@ Description
 
 Base class of anything 2D. Canvas items are laid out in a tree; children inherit and extend their parent's transform. ``CanvasItem`` is extended by :ref:`Control<class_Control>` for anything GUI-related, and by :ref:`Node2D<class_Node2D>` for anything related to the 2D engine.
 
-Any ``CanvasItem`` can draw. For this, :ref:`update<class_CanvasItem_method_update>` must be called, then :ref:`NOTIFICATION_DRAW<class_CanvasItem_constant_NOTIFICATION_DRAW>` will be received on idle time to request redraw. Because of this, canvas items don't need to be redrawn on every frame, improving the performance significantly. Several functions for drawing on the ``CanvasItem`` are provided (see ``draw_*`` functions). However, they can only be used inside the :ref:`Object._notification<class_Object_method__notification>`, signal or :ref:`_draw<class_CanvasItem_method__draw>` virtual functions.
+Any ``CanvasItem`` can draw. For this, :ref:`update<class_CanvasItem_method_update>` is called by the engine, then :ref:`NOTIFICATION_DRAW<class_CanvasItem_constant_NOTIFICATION_DRAW>` will be received on idle time to request redraw. Because of this, canvas items don't need to be redrawn on every frame, improving the performance significantly. Several functions for drawing on the ``CanvasItem`` are provided (see ``draw_*`` functions). However, they can only be used inside :ref:`_draw<class_CanvasItem_method__draw>`, its corresponding :ref:`Object._notification<class_Object_method__notification>` or methods connected to the :ref:`draw<class_CanvasItem_signal_draw>` signal.
 
 Canvas items are drawn in tree order. By default, children are on top of their parents so a root ``CanvasItem`` will be drawn behind everything. This behavior can be changed on a per-item basis.
 
@@ -165,7 +165,9 @@ Signals
 
 - **draw** **(** **)**
 
-Emitted when the ``CanvasItem`` must redraw. This can only be connected realtime, as deferred will not allow drawing.
+Emitted when the ``CanvasItem`` must redraw, *after* the related :ref:`NOTIFICATION_DRAW<class_CanvasItem_constant_NOTIFICATION_DRAW>` notification, and *before* :ref:`_draw<class_CanvasItem_method__draw>` is called.
+
+\ **Note:** Deferred connections do not allow drawing through the ``draw_*`` methods.
 
 ----
 
@@ -241,7 +243,7 @@ Constants
 
 - **NOTIFICATION_LOCAL_TRANSFORM_CHANGED** = **35** --- The ``CanvasItem``'s local transform has changed. This notification is only received if enabled by :ref:`set_notify_local_transform<class_CanvasItem_method_set_notify_local_transform>`.
 
-- **NOTIFICATION_DRAW** = **30** --- The ``CanvasItem`` is requested to draw.
+- **NOTIFICATION_DRAW** = **30** --- The ``CanvasItem`` is requested to draw (see :ref:`_draw<class_CanvasItem_method__draw>`).
 
 - **NOTIFICATION_VISIBILITY_CHANGED** = **31** --- The ``CanvasItem``'s visibility has changed.
 
@@ -377,7 +379,9 @@ Method Descriptions
 
 - void **_draw** **(** **)** |virtual|
 
-Overridable function called by the engine (if defined) to draw the canvas item.
+Called when ``CanvasItem`` has been requested to redraw (when :ref:`update<class_CanvasItem_method_update>` is called, either manually or by the engine).
+
+Corresponds to the :ref:`NOTIFICATION_DRAW<class_CanvasItem_constant_NOTIFICATION_DRAW>` notification in :ref:`Object._notification<class_Object_method__notification>`.
 
 ----
 
@@ -719,7 +723,7 @@ Returns ``true`` if global transform notifications are communicated to children.
 
 - :ref:`bool<class_bool>` **is_visible_in_tree** **(** **)** |const|
 
-Returns ``true`` if the node is present in the :ref:`SceneTree<class_SceneTree>`, its :ref:`visible<class_CanvasItem_property_visible>` property is ``true`` and all its antecedents are also visible. If any antecedent is hidden, this node will not be visible in the scene tree.
+Returns ``true`` if the node is present in the :ref:`SceneTree<class_SceneTree>`, its :ref:`visible<class_CanvasItem_property_visible>` property is ``true`` and all its antecedents are also visible. If any antecedent is hidden, this node will not be visible in the scene tree, and is consequently not drawn (see :ref:`_draw<class_CanvasItem_method__draw>`).
 
 ----
 
@@ -775,7 +779,7 @@ Show the ``CanvasItem`` if it's currently hidden. This is equivalent to setting
 
 - void **update** **(** **)**
 
-Queue the ``CanvasItem`` for update. :ref:`NOTIFICATION_DRAW<class_CanvasItem_constant_NOTIFICATION_DRAW>` will be called on idle time to request redraw.
+Queues the ``CanvasItem`` to redraw. During idle time, if ``CanvasItem`` is visible, :ref:`NOTIFICATION_DRAW<class_CanvasItem_constant_NOTIFICATION_DRAW>` is sent and :ref:`_draw<class_CanvasItem_method__draw>` is called. This only occurs **once** per frame, even if this method has been called multiple times.
 
 .. |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.)`

classes/class_canvaslayer.rst

@@ -104,7 +104,9 @@ The custom :ref:`Viewport<class_Viewport>` node assigned to the ``CanvasLayer``.
 | *Getter*  | is_following_viewport()    |
 +-----------+----------------------------+
 
-Sets the layer to follow the viewport in order to simulate a pseudo 3D effect.
+If enabled, the ``CanvasLayer`` will use the viewport's transform, so it will move when camera moves instead of being anchored in a fixed position on the screen.
+
+Together with :ref:`follow_viewport_scale<class_CanvasLayer_property_follow_viewport_scale>` it can be used for a pseudo 3D effect.
 
 ----
 

classes/class_control.rst

@@ -1697,6 +1697,8 @@ Creates an :ref:`InputEventMouseButton<class_InputEventMouseButton>` that attemp
 
 Steal the focus from another control and become the focused control (see :ref:`focus_mode<class_Control_property_focus_mode>`).
 
+\ **Note**: Using this method together with :ref:`Object.call_deferred<class_Object_method_call_deferred>` makes it more reliable, especially when called inside :ref:`Node._ready<class_Node_method__ready>`.
+
 ----
 
 .. _class_Control_method_has_color:

classes/class_curve.rst

@@ -19,6 +19,8 @@ Description
 
 A curve that can be saved and re-used for other objects. By default, it ranges between ``0`` and ``1`` on the Y axis and positions points relative to the ``0.5`` Y position.
 
+See also :ref:`Gradient<class_Gradient>` which is designed for color interpolation. See also :ref:`Curve2D<class_Curve2D>` and :ref:`Curve3D<class_Curve3D>`.
+
 Properties
 ----------
 

classes/class_curve2d.rst

@@ -31,43 +31,43 @@ Properties
 Methods
 -------
 
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| void                                            | :ref:`add_point<class_Curve2D_method_add_point>` **(** :ref:`Vector2<class_Vector2>` position, :ref:`Vector2<class_Vector2>` in=Vector2( 0, 0 ), :ref:`Vector2<class_Vector2>` out=Vector2( 0, 0 ), :ref:`int<class_int>` at_position=-1 **)** |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| void                                            | :ref:`clear_points<class_Curve2D_method_clear_points>` **(** **)**                                                                                                                                                                             |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`float<class_float>`                       | :ref:`get_baked_length<class_Curve2D_method_get_baked_length>` **(** **)** |const|                                                                                                                                                             |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`PoolVector2Array<class_PoolVector2Array>` | :ref:`get_baked_points<class_Curve2D_method_get_baked_points>` **(** **)** |const|                                                                                                                                                             |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`float<class_float>`                       | :ref:`get_closest_offset<class_Curve2D_method_get_closest_offset>` **(** :ref:`Vector2<class_Vector2>` to_point **)** |const|                                                                                                                  |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`Vector2<class_Vector2>`                   | :ref:`get_closest_point<class_Curve2D_method_get_closest_point>` **(** :ref:`Vector2<class_Vector2>` to_point **)** |const|                                                                                                                    |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`int<class_int>`                           | :ref:`get_point_count<class_Curve2D_method_get_point_count>` **(** **)** |const|                                                                                                                                                               |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`Vector2<class_Vector2>`                   | :ref:`get_point_in<class_Curve2D_method_get_point_in>` **(** :ref:`int<class_int>` idx **)** |const|                                                                                                                                           |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`Vector2<class_Vector2>`                   | :ref:`get_point_out<class_Curve2D_method_get_point_out>` **(** :ref:`int<class_int>` idx **)** |const|                                                                                                                                         |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`Vector2<class_Vector2>`                   | :ref:`get_point_position<class_Curve2D_method_get_point_position>` **(** :ref:`int<class_int>` idx **)** |const|                                                                                                                               |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`Vector2<class_Vector2>`                   | :ref:`interpolate<class_Curve2D_method_interpolate>` **(** :ref:`int<class_int>` idx, :ref:`float<class_float>` t **)** |const|                                                                                                                |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`Vector2<class_Vector2>`                   | :ref:`interpolate_baked<class_Curve2D_method_interpolate_baked>` **(** :ref:`float<class_float>` offset, :ref:`bool<class_bool>` cubic=false **)** |const|                                                                                     |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`Vector2<class_Vector2>`                   | :ref:`interpolatef<class_Curve2D_method_interpolatef>` **(** :ref:`float<class_float>` fofs **)** |const|                                                                                                                                      |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| void                                            | :ref:`remove_point<class_Curve2D_method_remove_point>` **(** :ref:`int<class_int>` idx **)**                                                                                                                                                   |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| void                                            | :ref:`set_point_in<class_Curve2D_method_set_point_in>` **(** :ref:`int<class_int>` idx, :ref:`Vector2<class_Vector2>` position **)**                                                                                                           |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| void                                            | :ref:`set_point_out<class_Curve2D_method_set_point_out>` **(** :ref:`int<class_int>` idx, :ref:`Vector2<class_Vector2>` position **)**                                                                                                         |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| void                                            | :ref:`set_point_position<class_Curve2D_method_set_point_position>` **(** :ref:`int<class_int>` idx, :ref:`Vector2<class_Vector2>` position **)**                                                                                               |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`PoolVector2Array<class_PoolVector2Array>` | :ref:`tessellate<class_Curve2D_method_tessellate>` **(** :ref:`int<class_int>` max_stages=5, :ref:`float<class_float>` tolerance_degrees=4 **)** |const|                                                                                       |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| void                                            | :ref:`add_point<class_Curve2D_method_add_point>` **(** :ref:`Vector2<class_Vector2>` position, :ref:`Vector2<class_Vector2>` in=Vector2( 0, 0 ), :ref:`Vector2<class_Vector2>` out=Vector2( 0, 0 ), :ref:`int<class_int>` index=-1 **)** |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| void                                            | :ref:`clear_points<class_Curve2D_method_clear_points>` **(** **)**                                                                                                                                                                       |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`float<class_float>`                       | :ref:`get_baked_length<class_Curve2D_method_get_baked_length>` **(** **)** |const|                                                                                                                                                       |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`PoolVector2Array<class_PoolVector2Array>` | :ref:`get_baked_points<class_Curve2D_method_get_baked_points>` **(** **)** |const|                                                                                                                                                       |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`float<class_float>`                       | :ref:`get_closest_offset<class_Curve2D_method_get_closest_offset>` **(** :ref:`Vector2<class_Vector2>` to_point **)** |const|                                                                                                            |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`Vector2<class_Vector2>`                   | :ref:`get_closest_point<class_Curve2D_method_get_closest_point>` **(** :ref:`Vector2<class_Vector2>` to_point **)** |const|                                                                                                              |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`int<class_int>`                           | :ref:`get_point_count<class_Curve2D_method_get_point_count>` **(** **)** |const|                                                                                                                                                         |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`Vector2<class_Vector2>`                   | :ref:`get_point_in<class_Curve2D_method_get_point_in>` **(** :ref:`int<class_int>` idx **)** |const|                                                                                                                                     |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`Vector2<class_Vector2>`                   | :ref:`get_point_out<class_Curve2D_method_get_point_out>` **(** :ref:`int<class_int>` idx **)** |const|                                                                                                                                   |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`Vector2<class_Vector2>`                   | :ref:`get_point_position<class_Curve2D_method_get_point_position>` **(** :ref:`int<class_int>` idx **)** |const|                                                                                                                         |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`Vector2<class_Vector2>`                   | :ref:`interpolate<class_Curve2D_method_interpolate>` **(** :ref:`int<class_int>` idx, :ref:`float<class_float>` t **)** |const|                                                                                                          |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`Vector2<class_Vector2>`                   | :ref:`interpolate_baked<class_Curve2D_method_interpolate_baked>` **(** :ref:`float<class_float>` offset, :ref:`bool<class_bool>` cubic=false **)** |const|                                                                               |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`Vector2<class_Vector2>`                   | :ref:`interpolatef<class_Curve2D_method_interpolatef>` **(** :ref:`float<class_float>` fofs **)** |const|                                                                                                                                |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| void                                            | :ref:`remove_point<class_Curve2D_method_remove_point>` **(** :ref:`int<class_int>` idx **)**                                                                                                                                             |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| void                                            | :ref:`set_point_in<class_Curve2D_method_set_point_in>` **(** :ref:`int<class_int>` idx, :ref:`Vector2<class_Vector2>` position **)**                                                                                                     |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| void                                            | :ref:`set_point_out<class_Curve2D_method_set_point_out>` **(** :ref:`int<class_int>` idx, :ref:`Vector2<class_Vector2>` position **)**                                                                                                   |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| void                                            | :ref:`set_point_position<class_Curve2D_method_set_point_position>` **(** :ref:`int<class_int>` idx, :ref:`Vector2<class_Vector2>` position **)**                                                                                         |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`PoolVector2Array<class_PoolVector2Array>` | :ref:`tessellate<class_Curve2D_method_tessellate>` **(** :ref:`int<class_int>` max_stages=5, :ref:`float<class_float>` tolerance_degrees=4 **)** |const|                                                                                 |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
 Property Descriptions
 ---------------------
@@ -91,11 +91,11 @@ Method Descriptions
 
 .. _class_Curve2D_method_add_point:
 
-- void **add_point** **(** :ref:`Vector2<class_Vector2>` position, :ref:`Vector2<class_Vector2>` in=Vector2( 0, 0 ), :ref:`Vector2<class_Vector2>` out=Vector2( 0, 0 ), :ref:`int<class_int>` at_position=-1 **)**
+- void **add_point** **(** :ref:`Vector2<class_Vector2>` position, :ref:`Vector2<class_Vector2>` in=Vector2( 0, 0 ), :ref:`Vector2<class_Vector2>` out=Vector2( 0, 0 ), :ref:`int<class_int>` index=-1 **)**
 
-Adds a point to a curve at ``position`` relative to the ``Curve2D``'s position, with control points ``in`` and ``out``.
+Adds a point with the specified ``position`` relative to the curve's own position, with control points ``in`` and ``out``. Appends the new point at the end of the point list.
 
-If ``at_position`` is given, the point is inserted before the point number ``at_position``, moving that point (and every point after) after the inserted point. If ``at_position`` is not given, or is an illegal value (``at_position <0`` or ``at_position >= [method get_point_count]``), the point will be appended at the end of the point list.
+If ``index`` is given, the new point is inserted before the existing point identified by index ``index``. Every existing point starting from ``index`` is shifted further down the list of points. The index must be greater than or equal to ``0`` and must not exceed the number of existing points in the line. See :ref:`get_point_count<class_Curve2D_method_get_point_count>`.
 
 ----
 

classes/class_curve3d.rst

@@ -33,53 +33,53 @@ Properties
 Methods
 -------
 
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| void                                            | :ref:`add_point<class_Curve3D_method_add_point>` **(** :ref:`Vector3<class_Vector3>` position, :ref:`Vector3<class_Vector3>` in=Vector3( 0, 0, 0 ), :ref:`Vector3<class_Vector3>` out=Vector3( 0, 0, 0 ), :ref:`int<class_int>` at_position=-1 **)** |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| void                                            | :ref:`clear_points<class_Curve3D_method_clear_points>` **(** **)**                                                                                                                                                                                   |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`float<class_float>`                       | :ref:`get_baked_length<class_Curve3D_method_get_baked_length>` **(** **)** |const|                                                                                                                                                                   |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`PoolVector3Array<class_PoolVector3Array>` | :ref:`get_baked_points<class_Curve3D_method_get_baked_points>` **(** **)** |const|                                                                                                                                                                   |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`PoolRealArray<class_PoolRealArray>`       | :ref:`get_baked_tilts<class_Curve3D_method_get_baked_tilts>` **(** **)** |const|                                                                                                                                                                     |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`PoolVector3Array<class_PoolVector3Array>` | :ref:`get_baked_up_vectors<class_Curve3D_method_get_baked_up_vectors>` **(** **)** |const|                                                                                                                                                           |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`float<class_float>`                       | :ref:`get_closest_offset<class_Curve3D_method_get_closest_offset>` **(** :ref:`Vector3<class_Vector3>` to_point **)** |const|                                                                                                                        |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`Vector3<class_Vector3>`                   | :ref:`get_closest_point<class_Curve3D_method_get_closest_point>` **(** :ref:`Vector3<class_Vector3>` to_point **)** |const|                                                                                                                          |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`int<class_int>`                           | :ref:`get_point_count<class_Curve3D_method_get_point_count>` **(** **)** |const|                                                                                                                                                                     |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`Vector3<class_Vector3>`                   | :ref:`get_point_in<class_Curve3D_method_get_point_in>` **(** :ref:`int<class_int>` idx **)** |const|                                                                                                                                                 |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`Vector3<class_Vector3>`                   | :ref:`get_point_out<class_Curve3D_method_get_point_out>` **(** :ref:`int<class_int>` idx **)** |const|                                                                                                                                               |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`Vector3<class_Vector3>`                   | :ref:`get_point_position<class_Curve3D_method_get_point_position>` **(** :ref:`int<class_int>` idx **)** |const|                                                                                                                                     |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`float<class_float>`                       | :ref:`get_point_tilt<class_Curve3D_method_get_point_tilt>` **(** :ref:`int<class_int>` idx **)** |const|                                                                                                                                             |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`Vector3<class_Vector3>`                   | :ref:`interpolate<class_Curve3D_method_interpolate>` **(** :ref:`int<class_int>` idx, :ref:`float<class_float>` t **)** |const|                                                                                                                      |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`Vector3<class_Vector3>`                   | :ref:`interpolate_baked<class_Curve3D_method_interpolate_baked>` **(** :ref:`float<class_float>` offset, :ref:`bool<class_bool>` cubic=false **)** |const|                                                                                           |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`Vector3<class_Vector3>`                   | :ref:`interpolate_baked_up_vector<class_Curve3D_method_interpolate_baked_up_vector>` **(** :ref:`float<class_float>` offset, :ref:`bool<class_bool>` apply_tilt=false **)** |const|                                                                  |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`Vector3<class_Vector3>`                   | :ref:`interpolatef<class_Curve3D_method_interpolatef>` **(** :ref:`float<class_float>` fofs **)** |const|                                                                                                                                            |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| void                                            | :ref:`remove_point<class_Curve3D_method_remove_point>` **(** :ref:`int<class_int>` idx **)**                                                                                                                                                         |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| void                                            | :ref:`set_point_in<class_Curve3D_method_set_point_in>` **(** :ref:`int<class_int>` idx, :ref:`Vector3<class_Vector3>` position **)**                                                                                                                 |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| void                                            | :ref:`set_point_out<class_Curve3D_method_set_point_out>` **(** :ref:`int<class_int>` idx, :ref:`Vector3<class_Vector3>` position **)**                                                                                                               |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| void                                            | :ref:`set_point_position<class_Curve3D_method_set_point_position>` **(** :ref:`int<class_int>` idx, :ref:`Vector3<class_Vector3>` position **)**                                                                                                     |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| void                                            | :ref:`set_point_tilt<class_Curve3D_method_set_point_tilt>` **(** :ref:`int<class_int>` idx, :ref:`float<class_float>` tilt **)**                                                                                                                     |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`PoolVector3Array<class_PoolVector3Array>` | :ref:`tessellate<class_Curve3D_method_tessellate>` **(** :ref:`int<class_int>` max_stages=5, :ref:`float<class_float>` tolerance_degrees=4 **)** |const|                                                                                             |
-+-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| void                                            | :ref:`add_point<class_Curve3D_method_add_point>` **(** :ref:`Vector3<class_Vector3>` position, :ref:`Vector3<class_Vector3>` in=Vector3( 0, 0, 0 ), :ref:`Vector3<class_Vector3>` out=Vector3( 0, 0, 0 ), :ref:`int<class_int>` index=-1 **)** |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| void                                            | :ref:`clear_points<class_Curve3D_method_clear_points>` **(** **)**                                                                                                                                                                             |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`float<class_float>`                       | :ref:`get_baked_length<class_Curve3D_method_get_baked_length>` **(** **)** |const|                                                                                                                                                             |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`PoolVector3Array<class_PoolVector3Array>` | :ref:`get_baked_points<class_Curve3D_method_get_baked_points>` **(** **)** |const|                                                                                                                                                             |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`PoolRealArray<class_PoolRealArray>`       | :ref:`get_baked_tilts<class_Curve3D_method_get_baked_tilts>` **(** **)** |const|                                                                                                                                                               |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`PoolVector3Array<class_PoolVector3Array>` | :ref:`get_baked_up_vectors<class_Curve3D_method_get_baked_up_vectors>` **(** **)** |const|                                                                                                                                                     |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`float<class_float>`                       | :ref:`get_closest_offset<class_Curve3D_method_get_closest_offset>` **(** :ref:`Vector3<class_Vector3>` to_point **)** |const|                                                                                                                  |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`Vector3<class_Vector3>`                   | :ref:`get_closest_point<class_Curve3D_method_get_closest_point>` **(** :ref:`Vector3<class_Vector3>` to_point **)** |const|                                                                                                                    |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`int<class_int>`                           | :ref:`get_point_count<class_Curve3D_method_get_point_count>` **(** **)** |const|                                                                                                                                                               |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`Vector3<class_Vector3>`                   | :ref:`get_point_in<class_Curve3D_method_get_point_in>` **(** :ref:`int<class_int>` idx **)** |const|                                                                                                                                           |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`Vector3<class_Vector3>`                   | :ref:`get_point_out<class_Curve3D_method_get_point_out>` **(** :ref:`int<class_int>` idx **)** |const|                                                                                                                                         |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`Vector3<class_Vector3>`                   | :ref:`get_point_position<class_Curve3D_method_get_point_position>` **(** :ref:`int<class_int>` idx **)** |const|                                                                                                                               |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`float<class_float>`                       | :ref:`get_point_tilt<class_Curve3D_method_get_point_tilt>` **(** :ref:`int<class_int>` idx **)** |const|                                                                                                                                       |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`Vector3<class_Vector3>`                   | :ref:`interpolate<class_Curve3D_method_interpolate>` **(** :ref:`int<class_int>` idx, :ref:`float<class_float>` t **)** |const|                                                                                                                |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`Vector3<class_Vector3>`                   | :ref:`interpolate_baked<class_Curve3D_method_interpolate_baked>` **(** :ref:`float<class_float>` offset, :ref:`bool<class_bool>` cubic=false **)** |const|                                                                                     |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`Vector3<class_Vector3>`                   | :ref:`interpolate_baked_up_vector<class_Curve3D_method_interpolate_baked_up_vector>` **(** :ref:`float<class_float>` offset, :ref:`bool<class_bool>` apply_tilt=false **)** |const|                                                            |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`Vector3<class_Vector3>`                   | :ref:`interpolatef<class_Curve3D_method_interpolatef>` **(** :ref:`float<class_float>` fofs **)** |const|                                                                                                                                      |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| void                                            | :ref:`remove_point<class_Curve3D_method_remove_point>` **(** :ref:`int<class_int>` idx **)**                                                                                                                                                   |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| void                                            | :ref:`set_point_in<class_Curve3D_method_set_point_in>` **(** :ref:`int<class_int>` idx, :ref:`Vector3<class_Vector3>` position **)**                                                                                                           |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| void                                            | :ref:`set_point_out<class_Curve3D_method_set_point_out>` **(** :ref:`int<class_int>` idx, :ref:`Vector3<class_Vector3>` position **)**                                                                                                         |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| void                                            | :ref:`set_point_position<class_Curve3D_method_set_point_position>` **(** :ref:`int<class_int>` idx, :ref:`Vector3<class_Vector3>` position **)**                                                                                               |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| void                                            | :ref:`set_point_tilt<class_Curve3D_method_set_point_tilt>` **(** :ref:`int<class_int>` idx, :ref:`float<class_float>` tilt **)**                                                                                                               |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`PoolVector3Array<class_PoolVector3Array>` | :ref:`tessellate<class_Curve3D_method_tessellate>` **(** :ref:`int<class_int>` max_stages=5, :ref:`float<class_float>` tolerance_degrees=4 **)** |const|                                                                                       |
++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
 Property Descriptions
 ---------------------
@@ -119,11 +119,11 @@ Method Descriptions
 
 .. _class_Curve3D_method_add_point:
 
-- void **add_point** **(** :ref:`Vector3<class_Vector3>` position, :ref:`Vector3<class_Vector3>` in=Vector3( 0, 0, 0 ), :ref:`Vector3<class_Vector3>` out=Vector3( 0, 0, 0 ), :ref:`int<class_int>` at_position=-1 **)**
+- void **add_point** **(** :ref:`Vector3<class_Vector3>` position, :ref:`Vector3<class_Vector3>` in=Vector3( 0, 0, 0 ), :ref:`Vector3<class_Vector3>` out=Vector3( 0, 0, 0 ), :ref:`int<class_int>` index=-1 **)**
 
-Adds a point to a curve at ``position`` relative to the ``Curve3D``'s position, with control points ``in`` and ``out``.
+Adds a point with the specified ``position`` relative to the curve's own position, with control points ``in`` and ``out``. Appends the new point at the end of the point list.
 
-If ``at_position`` is given, the point is inserted before the point number ``at_position``, moving that point (and every point after) after the inserted point. If ``at_position`` is not given, or is an illegal value (``at_position <0`` or ``at_position >= [method get_point_count]``), the point will be appended at the end of the point list.
+If ``index`` is given, the new point is inserted before the existing point identified by index ``index``. Every existing point starting from ``index`` is shifted further down the list of points. The index must be greater than or equal to ``0`` and must not exceed the number of existing points in the line. See :ref:`get_point_count<class_Curve3D_method_get_point_count>`.
 
 ----
 

classes/class_editorproperty.rst

@@ -76,7 +76,7 @@ Used by sub-inspectors. Emit it if what was selected was an Object ID.
 
 .. _class_EditorProperty_signal_property_changed:
 
-- **property_changed** **(** :ref:`String<class_String>` property, :ref:`Variant<class_Variant>` value **)**
+- **property_changed** **(** :ref:`String<class_String>` property, :ref:`Variant<class_Variant>` value, :ref:`String<class_String>` field, :ref:`bool<class_bool>` changing **)**
 
 Do not emit this manually, use the :ref:`emit_changed<class_EditorProperty_method_emit_changed>` method instead.
 

classes/class_file.rst

@@ -76,7 +76,7 @@ Methods
 +-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | :ref:`int<class_int>`                         | :ref:`get_8<class_File_method_get_8>` **(** **)** |const|                                                                                                                                                                      |
 +-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`String<class_String>`                   | :ref:`get_as_text<class_File_method_get_as_text>` **(** **)** |const|                                                                                                                                                          |
+| :ref:`String<class_String>`                   | :ref:`get_as_text<class_File_method_get_as_text>` **(** :ref:`bool<class_bool>` skip_cr=true **)** |const|                                                                                                                     |
 +-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | :ref:`PoolByteArray<class_PoolByteArray>`     | :ref:`get_buffer<class_File_method_get_buffer>` **(** :ref:`int<class_int>` len **)** |const|                                                                                                                                  |
 +-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -297,11 +297,11 @@ Returns the next 8 bits from the file as an integer. See :ref:`store_8<class_Fil
 
 .. _class_File_method_get_as_text:
 
-- :ref:`String<class_String>` **get_as_text** **(** **)** |const|
+- :ref:`String<class_String>` **get_as_text** **(** :ref:`bool<class_bool>` skip_cr=true **)** |const|
 
-Returns the whole file as a :ref:`String<class_String>`.
+Returns the whole file as a :ref:`String<class_String>`. Text is interpreted as being UTF-8 encoded.
 
-Text is interpreted as being UTF-8 encoded.
+If ``skip_cr`` is ``true``, carriage return characters (``\r``, CR) will be ignored when parsing the UTF-8, so that only line feed characters (``\n``, LF) represent a new line (Unix convention).
 
 ----
 

classes/class_font.rst

@@ -104,6 +104,8 @@ See also :ref:`CanvasItem.draw_string<class_CanvasItem_method_draw_string>`.
 
 Draw character ``char`` into a canvas item using the font at a given position, with ``modulate`` color, and optionally kerning if ``next`` is passed. clipping the width. ``position`` specifies the baseline, not the top. To draw from the top, *ascent* must be added to the Y axis. The width used by the character is returned, making this function useful for drawing strings character by character.
 
+If ``outline`` is ``true``, the outline of the character is drawn instead of the character itself.
+
 ----
 
 .. _class_Font_method_get_ascent:

classes/class_gradient.rst

@@ -17,7 +17,9 @@ A color interpolator resource which can be used to generate colors between user-
 Description
 -----------
 
-Given a set of colors, this resource will interpolate them in order. This means that if you have color 1, color 2 and color 3, the ramp will interpolate from color 1 to color 2 and from color 2 to color 3. The ramp will initially have 2 colors (black and white), one (black) at ramp lower offset 0 and the other (white) at the ramp higher offset 1.
+Given a set of colors, this resource will interpolate them in order. This means that if you have color 1, color 2 and color 3, the gradient will interpolate from color 1 to color 2 and from color 2 to color 3. The gradient will initially have 2 colors (black and white), one (black) at gradient lower offset 0 and the other (white) at the gradient higher offset 1.
+
+See also :ref:`Curve<class_Curve>` which supports more complex easing methods, but does not support colors.
 
 Properties
 ----------

classes/class_httpclient.rst

@@ -17,7 +17,9 @@ Low-level hyper-text transfer protocol client.
 Description
 -----------
 
-Hyper-text transfer protocol client (sometimes called "User Agent"). Used to make HTTP requests to download web content, upload files and other data or to communicate with various services, among other use cases. **See the :ref:`HTTPRequest<class_HTTPRequest>` node for a higher-level alternative.**\ 
+Hyper-text transfer protocol client (sometimes called "User Agent"). Used to make HTTP requests to download web content, upload files and other data or to communicate with various services, among other use cases.
+
+See the :ref:`HTTPRequest<class_HTTPRequest>` node for a higher-level alternative.
 
 \ **Note:** This client only needs to connect to a host once (see :ref:`connect_to_host<class_HTTPClient_method_connect_to_host>`) to send multiple requests. Because of this, methods that take URLs usually take just the part after the host instead of the full URL, as the client is already connected to a host. See :ref:`request<class_HTTPClient_method_request>` for a full example and to get started.
 

classes/class_input.rst

@@ -713,12 +713,16 @@ Stops the vibration of the joypad.
 
 - void **vibrate_handheld** **(** :ref:`int<class_int>` duration_ms=500 **)**
 
-Vibrate Android and iOS devices.
+Vibrate handheld devices.
+
+\ **Note:** This method is implemented on Android, iOS, and HTML5.
 
 \ **Note:** For Android, it requires enabling the ``VIBRATE`` permission in the export preset.
 
 \ **Note:** For iOS, specifying the duration is supported in iOS 13 and later.
 
+\ **Note:** Some web browsers such as Safari and Firefox for Android do not support this method.
+
 ----
 
 .. _class_Input_method_warp_mouse_position:

classes/class_instanceplaceholder.rst

@@ -41,7 +41,9 @@ Method Descriptions
 
 - :ref:`Node<class_Node>` **create_instance** **(** :ref:`bool<class_bool>` replace=false, :ref:`PackedScene<class_PackedScene>` custom_scene=null **)**
 
-Not thread-safe. Use :ref:`Object.call_deferred<class_Object_method_call_deferred>` if calling from a thread.
+Call this method to actually load in the node. The created node will be placed as a sibling *above* the ``InstancePlaceholder`` in the scene tree. The :ref:`Node<class_Node>`'s reference is also returned for convenience.
+
+\ **Note:** :ref:`create_instance<class_InstancePlaceholder_method_create_instance>` is not thread-safe. Use :ref:`Object.call_deferred<class_Object_method_call_deferred>` if calling from a thread.
 
 ----
 
@@ -57,6 +59,10 @@ Gets the path to the :ref:`PackedScene<class_PackedScene>` resource file that is
 
 - :ref:`Dictionary<class_Dictionary>` **get_stored_values** **(** :ref:`bool<class_bool>` with_order=false **)**
 
+Returns the list of properties that will be applied to the node when :ref:`create_instance<class_InstancePlaceholder_method_create_instance>` is called.
+
+If ``with_order`` is ``true``, a key named ``.order`` (note the leading period) is added to the dictionary. This ``.order`` key is an :ref:`Array<class_Array>` of :ref:`String<class_String>` property names specifying the order in which properties will be applied (with index 0 being the first).
+
 ----
 
 .. _class_InstancePlaceholder_method_replace_by_instance:

classes/class_line2d.rst

@@ -62,19 +62,19 @@ Properties
 Methods
 -------
 
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
-| void                          | :ref:`add_point<class_Line2D_method_add_point>` **(** :ref:`Vector2<class_Vector2>` position, :ref:`int<class_int>` at_position=-1 **)**      |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
-| void                          | :ref:`clear_points<class_Line2D_method_clear_points>` **(** **)**                                                                             |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`int<class_int>`         | :ref:`get_point_count<class_Line2D_method_get_point_count>` **(** **)** |const|                                                               |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`Vector2<class_Vector2>` | :ref:`get_point_position<class_Line2D_method_get_point_position>` **(** :ref:`int<class_int>` i **)** |const|                                 |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
-| void                          | :ref:`remove_point<class_Line2D_method_remove_point>` **(** :ref:`int<class_int>` i **)**                                                     |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
-| void                          | :ref:`set_point_position<class_Line2D_method_set_point_position>` **(** :ref:`int<class_int>` i, :ref:`Vector2<class_Vector2>` position **)** |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
++-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
+| void                          | :ref:`add_point<class_Line2D_method_add_point>` **(** :ref:`Vector2<class_Vector2>` position, :ref:`int<class_int>` index=-1 **)**                |
++-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
+| void                          | :ref:`clear_points<class_Line2D_method_clear_points>` **(** **)**                                                                                 |
++-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`int<class_int>`         | :ref:`get_point_count<class_Line2D_method_get_point_count>` **(** **)** |const|                                                                   |
++-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`Vector2<class_Vector2>` | :ref:`get_point_position<class_Line2D_method_get_point_position>` **(** :ref:`int<class_int>` index **)** |const|                                 |
++-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
+| void                          | :ref:`remove_point<class_Line2D_method_remove_point>` **(** :ref:`int<class_int>` index **)**                                                     |
++-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
+| void                          | :ref:`set_point_position<class_Line2D_method_set_point_position>` **(** :ref:`int<class_int>` index, :ref:`Vector2<class_Vector2>` position **)** |
++-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
 
 Enumerations
 ------------
@@ -345,11 +345,11 @@ Method Descriptions
 
 .. _class_Line2D_method_add_point:
 
-- void **add_point** **(** :ref:`Vector2<class_Vector2>` position, :ref:`int<class_int>` at_position=-1 **)**
+- void **add_point** **(** :ref:`Vector2<class_Vector2>` position, :ref:`int<class_int>` index=-1 **)**
 
-Adds a point at the ``position``. Appends the point at the end of the line.
+Adds a point with the specified ``position`` relative to the line's own position. Appends the new point at the end of the point list.
 
-If ``at_position`` is given, the point is inserted before the point number ``at_position``, moving that point (and every point after) after the inserted point. If ``at_position`` is not given, or is an illegal value (``at_position < 0`` or ``at_position >= [method get_point_count]``), the point will be appended at the end of the point list.
+If ``index`` is given, the new point is inserted before the existing point identified by index ``index``. Every existing point starting from ``index`` is shifted further down the list of points. The index must be greater than or equal to ``0`` and must not exceed the number of existing points in the line. See :ref:`get_point_count<class_Line2D_method_get_point_count>`.
 
 ----
 
@@ -365,31 +365,31 @@ Removes all points from the line.
 
 - :ref:`int<class_int>` **get_point_count** **(** **)** |const|
 
-Returns the Line2D's amount of points.
+Returns the amount of points in the line.
 
 ----
 
 .. _class_Line2D_method_get_point_position:
 
-- :ref:`Vector2<class_Vector2>` **get_point_position** **(** :ref:`int<class_int>` i **)** |const|
+- :ref:`Vector2<class_Vector2>` **get_point_position** **(** :ref:`int<class_int>` index **)** |const|
 
-Returns point ``i``'s position.
+Returns the position of the point at index ``index``.
 
 ----
 
 .. _class_Line2D_method_remove_point:
 
-- void **remove_point** **(** :ref:`int<class_int>` i **)**
+- void **remove_point** **(** :ref:`int<class_int>` index **)**
 
-Removes the point at index ``i`` from the line.
+Removes the point at index ``index`` from the line.
 
 ----
 
 .. _class_Line2D_method_set_point_position:
 
-- void **set_point_position** **(** :ref:`int<class_int>` i, :ref:`Vector2<class_Vector2>` position **)**
+- void **set_point_position** **(** :ref:`int<class_int>` index, :ref:`Vector2<class_Vector2>` position **)**
 
-Overwrites the position in point ``i`` with the supplied ``position``.
+Overwrites the position of the point at index ``index`` with the supplied ``position``.
 
 .. |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.)`

classes/class_meshinstance.rst

@@ -19,7 +19,7 @@ Node that instances meshes into a scenario.
 Description
 -----------
 
-MeshInstance is a node that takes a :ref:`Mesh<class_Mesh>` resource and adds it to the current scenario by creating an instance of it. This is the class most often used to get 3D geometry rendered and can be used to instance a single :ref:`Mesh<class_Mesh>` in many places. This allows to reuse geometry and save on resources. When a :ref:`Mesh<class_Mesh>` has to be instanced more than thousands of times at close proximity, consider using a :ref:`MultiMesh<class_MultiMesh>` in a :ref:`MultiMeshInstance<class_MultiMeshInstance>` instead.
+MeshInstance is a node that takes a :ref:`Mesh<class_Mesh>` resource and adds it to the current scenario by creating an instance of it. This is the class most often used to get 3D geometry rendered and can be used to instance a single :ref:`Mesh<class_Mesh>` in many places. This allows reusing geometry, which can save on resources. When a :ref:`Mesh<class_Mesh>` has to be instanced more than thousands of times at close proximity, consider using a :ref:`MultiMesh<class_MultiMesh>` in a :ref:`MultiMeshInstance<class_MultiMeshInstance>` instead.
 
 Tutorials
 ---------

classes/class_multimesh.rst

@@ -343,7 +343,7 @@ When the order of instances is coherent, the simpler :ref:`set_as_bulk_array<cla
 
 Sets the color of a specific instance by *multiplying* the mesh's existing vertex colors.
 
-For the color to take effect, ensure that :ref:`color_format<class_MultiMesh_property_color_format>` is non-``null`` on the ``MultiMesh`` and :ref:`SpatialMaterial.vertex_color_use_as_albedo<class_SpatialMaterial_property_vertex_color_use_as_albedo>` is ``true`` on the material.
+For the color to take effect, ensure that :ref:`color_format<class_MultiMesh_property_color_format>` is non-``null`` on the ``MultiMesh`` and :ref:`SpatialMaterial.vertex_color_use_as_albedo<class_SpatialMaterial_property_vertex_color_use_as_albedo>` is ``true`` on the material. If the color doesn't look as expected, make sure the material's albedo color is set to pure white (``Color(1, 1, 1)``).
 
 ----
 

classes/class_navigation2dserver.rst

@@ -92,7 +92,7 @@ Methods
 +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | :ref:`Array<class_Array>`                       | :ref:`map_get_regions<class_Navigation2DServer_method_map_get_regions>` **(** :ref:`RID<class_RID>` map **)** |const|                                                                                                                                                         |
 +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`bool<class_bool>`                         | :ref:`map_is_active<class_Navigation2DServer_method_map_is_active>` **(** :ref:`RID<class_RID>` nap **)** |const|                                                                                                                                                             |
+| :ref:`bool<class_bool>`                         | :ref:`map_is_active<class_Navigation2DServer_method_map_is_active>` **(** :ref:`RID<class_RID>` map **)** |const|                                                                                                                                                             |
 +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | void                                            | :ref:`map_set_active<class_Navigation2DServer_method_map_set_active>` **(** :ref:`RID<class_RID>` map, :ref:`bool<class_bool>` active **)** |const|                                                                                                                           |
 +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -355,7 +355,7 @@ Returns all navigation regions :ref:`RID<class_RID>`\ s that are currently assig
 
 .. _class_Navigation2DServer_method_map_is_active:
 
-- :ref:`bool<class_bool>` **map_is_active** **(** :ref:`RID<class_RID>` nap **)** |const|
+- :ref:`bool<class_bool>` **map_is_active** **(** :ref:`RID<class_RID>` map **)** |const|
 
 Returns ``true`` if the map is active.
 

classes/class_navigationagent.rst

@@ -118,7 +118,7 @@ Notifies when the player-defined target, set with :ref:`set_target_location<clas
 
 - **velocity_computed** **(** :ref:`Vector3<class_Vector3>` safe_velocity **)**
 
-Notifies when the collision avoidance velocity is calculated after a call to :ref:`set_velocity<class_NavigationAgent_method_set_velocity>`.
+Notifies when the collision avoidance velocity is calculated after a call to :ref:`set_velocity<class_NavigationAgent_method_set_velocity>`. Only emitted when :ref:`avoidance_enabled<class_NavigationAgent_property_avoidance_enabled>` is true.
 
 Property Descriptions
 ---------------------

classes/class_navigationagent2d.rst

@@ -114,7 +114,7 @@ Notifies when the player-defined target, set with :ref:`set_target_location<clas
 
 - **velocity_computed** **(** :ref:`Vector2<class_Vector2>` safe_velocity **)**
 
-Notifies when the collision avoidance velocity is calculated after a call to :ref:`set_velocity<class_NavigationAgent2D_method_set_velocity>`.
+Notifies when the collision avoidance velocity is calculated after a call to :ref:`set_velocity<class_NavigationAgent2D_method_set_velocity>`. Only emitted when :ref:`avoidance_enabled<class_NavigationAgent2D_property_avoidance_enabled>` is true.
 
 Property Descriptions
 ---------------------

classes/class_navigationserver.rst

@@ -96,7 +96,7 @@ Methods
 +-------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | :ref:`Vector3<class_Vector3>`                   | :ref:`map_get_up<class_NavigationServer_method_map_get_up>` **(** :ref:`RID<class_RID>` map **)** |const|                                                                                                                                                                   |
 +-------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`bool<class_bool>`                         | :ref:`map_is_active<class_NavigationServer_method_map_is_active>` **(** :ref:`RID<class_RID>` nap **)** |const|                                                                                                                                                             |
+| :ref:`bool<class_bool>`                         | :ref:`map_is_active<class_NavigationServer_method_map_is_active>` **(** :ref:`RID<class_RID>` map **)** |const|                                                                                                                                                             |
 +-------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | void                                            | :ref:`map_set_active<class_NavigationServer_method_map_set_active>` **(** :ref:`RID<class_RID>` map, :ref:`bool<class_bool>` active **)** |const|                                                                                                                           |
 +-------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -391,7 +391,7 @@ Returns the map's up direction.
 
 .. _class_NavigationServer_method_map_is_active:
 
-- :ref:`bool<class_bool>` **map_is_active** **(** :ref:`RID<class_RID>` nap **)** |const|
+- :ref:`bool<class_bool>` **map_is_active** **(** :ref:`RID<class_RID>` map **)** |const|
 
 Returns ``true`` if the map is active.
 

classes/class_networkedmultiplayercustom.rst

@@ -64,6 +64,8 @@ When your script receives a packet from other peers over the network (originatin
 
 Initialize the peer with the given ``peer_id`` (must be between 1 and 2147483647).
 
+Can only be called if the connection status is :ref:`NetworkedMultiplayerPeer.CONNECTION_CONNECTING<class_NetworkedMultiplayerPeer_constant_CONNECTION_CONNECTING>`. See :ref:`set_connection_status<class_NetworkedMultiplayerCustom_method_set_connection_status>`.
+
 ----
 
 .. _class_NetworkedMultiplayerCustom_method_set_connection_status:
@@ -72,6 +74,10 @@ Initialize the peer with the given ``peer_id`` (must be between 1 and 2147483647
 
 Set the state of the connection. See :ref:`ConnectionStatus<enum_NetworkedMultiplayerPeer_ConnectionStatus>`.
 
+This will emit the :ref:`NetworkedMultiplayerPeer.connection_succeeded<class_NetworkedMultiplayerPeer_signal_connection_succeeded>`, :ref:`NetworkedMultiplayerPeer.connection_failed<class_NetworkedMultiplayerPeer_signal_connection_failed>` or :ref:`NetworkedMultiplayerPeer.server_disconnected<class_NetworkedMultiplayerPeer_signal_server_disconnected>` signals depending on the status and if the peer has the unique network id of ``1``.
+
+You can only change to :ref:`NetworkedMultiplayerPeer.CONNECTION_CONNECTING<class_NetworkedMultiplayerPeer_constant_CONNECTION_CONNECTING>` from :ref:`NetworkedMultiplayerPeer.CONNECTION_DISCONNECTED<class_NetworkedMultiplayerPeer_constant_CONNECTION_DISCONNECTED>` and to :ref:`NetworkedMultiplayerPeer.CONNECTION_CONNECTED<class_NetworkedMultiplayerPeer_constant_CONNECTION_CONNECTED>` from :ref:`NetworkedMultiplayerPeer.CONNECTION_CONNECTING<class_NetworkedMultiplayerPeer_constant_CONNECTION_CONNECTING>`.
+
 ----
 
 .. _class_NetworkedMultiplayerCustom_method_set_max_packet_size:

classes/class_os.rst

@@ -1665,6 +1665,8 @@ Returns the current UNIX epoch timestamp in seconds.
 
 \ **Important:** This is the system clock that the user can manually set. **Never use** this method for precise time calculation since its results are also subject to automatic adjustments by the operating system. **Always use** :ref:`get_ticks_usec<class_OS_method_get_ticks_usec>` or :ref:`get_ticks_msec<class_OS_method_get_ticks_msec>` for precise time calculation instead, since they are guaranteed to be monotonic (i.e. never decrease).
 
+\ **Note:** To get a floating point timestamp with sub-second precision, use :ref:`Time.get_unix_time_from_system<class_Time_method_get_unix_time_from_system>`.
+
 ----
 
 .. _class_OS_method_get_unix_time_from_datetime:

classes/class_popupmenu.rst

@@ -639,6 +639,8 @@ Removes the item at index ``idx`` from the menu.
 
 Sets the currently focused item as the given ``index``.
 
+Passing ``-1`` as the index makes so that no item is focused.
+
 ----
 
 .. _class_PopupMenu_method_set_hide_on_window_lose_focus:

classes/class_popuppanel.rst

@@ -19,6 +19,8 @@ Description
 
 Class for displaying popups with a panel background. In some cases it might be simpler to use than :ref:`Popup<class_Popup>`, since it provides a configurable background. If you are making windows, better check :ref:`WindowDialog<class_WindowDialog>`.
 
+If any :ref:`Control<class_Control>` node is added as a child of this ``PopupPanel``, it will be stretched to fit the panel's size (similar to how :ref:`PanelContainer<class_PanelContainer>` works).
+
 Theme Properties
 ----------------
 

classes/class_projectsettings.rst

@@ -1468,6 +1468,8 @@ Specifies the audio driver to use. This setting is platform-dependent as each pl
 
 If ``true``, microphone input will be allowed. This requires appropriate permissions to be set when exporting to Android or iOS.
 
+\ **Note:** If the operating system blocks access to audio input devices (due to the user's privacy settings), audio capture will only return silence. On Windows 10 and later, make sure that apps are allowed to access the microphone in the OS' privacy settings.
+
 ----
 
 .. _class_ProjectSettings_property_audio/mix_rate:
@@ -6676,7 +6678,11 @@ If ``true``, allows falling back to the GLES2 driver if the GLES3 driver is not
 | *Default* | ``4`` |
 +-----------+-------+
 
-Maximum anisotropic filter level used for textures with anisotropy enabled. Higher values will result in sharper textures when viewed from oblique angles, at the cost of performance. Only power-of-two values are valid (2, 4, 8, 16).
+Maximum anisotropic filter level used for textures with anisotropy enabled. Higher values will result in sharper textures when viewed from oblique angles, at the cost of performance. With the exception of ``1``, only power-of-two values are valid (``2``, ``4``, ``8``, ``16``). A value of ``1`` forcibly disables anisotropic filtering, even on textures where it is enabled.
+
+\ **Note:** For performance reasons, anisotropic filtering *is not enabled by default* on textures. For this setting to have an effect, anisotropic texture filtering can be enabled by selecting a texture in the FileSystem dock, going to the Import dock, checking the **Anisotropic** checkbox then clicking **Reimport**. However, anisotropic filtering is rarely useful in 2D, so only enable it for textures in 2D if it makes a meaningful visual difference.
+
+\ **Note:** This property is only read when the project starts. There is currently no way to change this setting at run-time.
 
 ----
 

classes/class_scenetree.rst

@@ -357,6 +357,8 @@ The current scene.
 
 If ``true``, collision shapes will be visible when running the game from the editor for debugging purposes.
 
+\ **Note:** This property is not designed to be changed at run-time. Changing the value of :ref:`debug_collisions_hint<class_SceneTree_property_debug_collisions_hint>` while the project is running will not have the desired effect.
+
 ----
 
 .. _class_SceneTree_property_debug_navigation_hint:
@@ -373,6 +375,8 @@ If ``true``, collision shapes will be visible when running the game from the edi
 
 If ``true``, navigation polygons will be visible when running the game from the editor for debugging purposes.
 
+\ **Note:** This property is not designed to be changed at run-time. Changing the value of :ref:`debug_navigation_hint<class_SceneTree_property_debug_navigation_hint>` while the project is running will not have the desired effect.
+
 ----
 
 .. _class_SceneTree_property_edited_scene_root:
@@ -591,6 +595,8 @@ Returns :ref:`@GlobalScope.OK<class_@GlobalScope_constant_OK>` on success or :re
 
 \ **Note:** The scene change is deferred, which means that the new scene node is added on the next idle frame. You won't be able to access it immediately after the :ref:`change_scene_to<class_SceneTree_method_change_scene_to>` call.
 
+\ **Note:** Passing a value of ``null`` into the method will unload the current scene without loading a new one.
+
 ----
 
 .. _class_SceneTree_method_create_timer:

classes/class_shape2d.rst

@@ -63,7 +63,9 @@ Property Descriptions
 | *Getter*  | get_custom_solver_bias()      |
 +-----------+-------------------------------+
 
-The shape's custom solver bias.
+The shape's custom solver bias. Defines how much bodies react to enforce contact separation when this shape is involved.
+
+When set to ``0.0``, the default value of ``0.3`` is used.
 
 Method Descriptions
 -------------------

classes/class_spatialmaterial.rst

@@ -768,7 +768,7 @@ If ``true``, anisotropy is enabled. Anisotropy changes the shape of the specular
 
 \ **Note:** Mesh tangents are needed for anisotropy to work. If the mesh does not contain tangents, the anisotropy effect will appear broken.
 
-\ **Note:** Material anisotropy should not to be confused with anisotropic texture filtering. Anisotropic texture filtering can be enabled by selecting a texture in the FileSystem dock, going to the Import dock, checking the **Anisotropic** checkbox then clicking **Reimport**.
+\ **Note:** Material anisotropy should not to be confused with anisotropic texture filtering. Anisotropic texture filtering can be enabled by selecting a texture in the FileSystem dock, going to the Import dock, checking the **Anisotropic** checkbox then clicking **Reimport**. The anisotropic filtering level can be changed by adjusting :ref:`ProjectSettings.rendering/quality/filters/anisotropic_filter_level<class_ProjectSettings_property_rendering/quality/filters/anisotropic_filter_level>`.
 
 ----
 

classes/class_sprite3d.rst

@@ -140,7 +140,7 @@ The region of the atlas texture to display. :ref:`region_enabled<class_Sprite3D_
 | *Getter* | get_texture()      |
 +----------+--------------------+
 
-:ref:`Texture<class_Texture>` object to draw. If :ref:`GeometryInstance.material_override<class_GeometryInstance_property_material_override>` is used, this will be overridden.
+:ref:`Texture<class_Texture>` object to draw. If :ref:`GeometryInstance.material_override<class_GeometryInstance_property_material_override>` is used, this will be overridden. The size information is still used.
 
 ----
 

classes/class_string.rst

@@ -1029,6 +1029,8 @@ Splits the string by a ``delimiter`` string and returns an array of the substrin
 
 The splits in the returned array are sorted in the same order as the original string, from left to right.
 
+If ``allow_empty`` is ``true``, and there are two adjacent delimiters in the string, it will add an empty string to the array of substrings at this position.
+
 If ``maxsplit`` is specified, it defines the number of splits to do from the right up to ``maxsplit``. The default value of 0 means that all items are split, thus giving the same result as :ref:`split<class_String_method_split>`.
 
 Example:
@@ -1114,6 +1116,8 @@ Returns a simplified canonical path.
 
 Splits the string by a ``delimiter`` string and returns an array of the substrings. The ``delimiter`` can be of any length.
 
+If ``allow_empty`` is ``true``, and there are two adjacent delimiters in the string, it will add an empty string to the array of substrings at this position.
+
 If ``maxsplit`` is specified, it defines the number of splits to do from the left up to ``maxsplit``. The default value of ``0`` means that all items are split.
 
 If you need only one element from the array at a specific index, :ref:`get_slice<class_String_method_get_slice>` is a more performant option.
@@ -1140,6 +1144,8 @@ Splits the string in floats by using a delimiter string and returns an array of
 
 For example, ``"1,2.5,3"`` will return ``[1,2.5,3]`` if split by ``","``.
 
+If ``allow_empty`` is ``true``, and there are two adjacent delimiters in the string, it will add an empty string to the array of substrings at this position.
+
 ----
 
 .. _class_String_method_strip_edges:

classes/class_tabs.rst

@@ -37,45 +37,49 @@ Properties
 Methods
 -------
 
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| void                          | :ref:`add_tab<class_Tabs_method_add_tab>` **(** :ref:`String<class_String>` title="", :ref:`Texture<class_Texture>` icon=null **)**     |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| void                          | :ref:`ensure_tab_visible<class_Tabs_method_ensure_tab_visible>` **(** :ref:`int<class_int>` idx **)**                                   |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`bool<class_bool>`       | :ref:`get_offset_buttons_visible<class_Tabs_method_get_offset_buttons_visible>` **(** **)** |const|                                     |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`int<class_int>`         | :ref:`get_previous_tab<class_Tabs_method_get_previous_tab>` **(** **)** |const|                                                         |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`bool<class_bool>`       | :ref:`get_select_with_rmb<class_Tabs_method_get_select_with_rmb>` **(** **)** |const|                                                   |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`int<class_int>`         | :ref:`get_tab_count<class_Tabs_method_get_tab_count>` **(** **)** |const|                                                               |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`bool<class_bool>`       | :ref:`get_tab_disabled<class_Tabs_method_get_tab_disabled>` **(** :ref:`int<class_int>` tab_idx **)** |const|                           |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`Texture<class_Texture>` | :ref:`get_tab_icon<class_Tabs_method_get_tab_icon>` **(** :ref:`int<class_int>` tab_idx **)** |const|                                   |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`int<class_int>`         | :ref:`get_tab_offset<class_Tabs_method_get_tab_offset>` **(** **)** |const|                                                             |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`Rect2<class_Rect2>`     | :ref:`get_tab_rect<class_Tabs_method_get_tab_rect>` **(** :ref:`int<class_int>` tab_idx **)** |const|                                   |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`String<class_String>`   | :ref:`get_tab_title<class_Tabs_method_get_tab_title>` **(** :ref:`int<class_int>` tab_idx **)** |const|                                 |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| :ref:`int<class_int>`         | :ref:`get_tabs_rearrange_group<class_Tabs_method_get_tabs_rearrange_group>` **(** **)** |const|                                         |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| void                          | :ref:`move_tab<class_Tabs_method_move_tab>` **(** :ref:`int<class_int>` from, :ref:`int<class_int>` to **)**                            |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| void                          | :ref:`remove_tab<class_Tabs_method_remove_tab>` **(** :ref:`int<class_int>` tab_idx **)**                                               |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| void                          | :ref:`set_select_with_rmb<class_Tabs_method_set_select_with_rmb>` **(** :ref:`bool<class_bool>` enabled **)**                           |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| void                          | :ref:`set_tab_disabled<class_Tabs_method_set_tab_disabled>` **(** :ref:`int<class_int>` tab_idx, :ref:`bool<class_bool>` disabled **)** |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| void                          | :ref:`set_tab_icon<class_Tabs_method_set_tab_icon>` **(** :ref:`int<class_int>` tab_idx, :ref:`Texture<class_Texture>` icon **)**       |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| void                          | :ref:`set_tab_title<class_Tabs_method_set_tab_title>` **(** :ref:`int<class_int>` tab_idx, :ref:`String<class_String>` title **)**      |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| void                          | :ref:`set_tabs_rearrange_group<class_Tabs_method_set_tabs_rearrange_group>` **(** :ref:`int<class_int>` group_id **)**                  |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
++-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
+| void                          | :ref:`add_tab<class_Tabs_method_add_tab>` **(** :ref:`String<class_String>` title="", :ref:`Texture<class_Texture>` icon=null **)**             |
++-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
+| void                          | :ref:`ensure_tab_visible<class_Tabs_method_ensure_tab_visible>` **(** :ref:`int<class_int>` idx **)**                                           |
++-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`bool<class_bool>`       | :ref:`get_offset_buttons_visible<class_Tabs_method_get_offset_buttons_visible>` **(** **)** |const|                                             |
++-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`int<class_int>`         | :ref:`get_previous_tab<class_Tabs_method_get_previous_tab>` **(** **)** |const|                                                                 |
++-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`bool<class_bool>`       | :ref:`get_select_with_rmb<class_Tabs_method_get_select_with_rmb>` **(** **)** |const|                                                           |
++-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`Texture<class_Texture>` | :ref:`get_tab_button_icon<class_Tabs_method_get_tab_button_icon>` **(** :ref:`int<class_int>` tab_idx **)** |const|                             |
++-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`int<class_int>`         | :ref:`get_tab_count<class_Tabs_method_get_tab_count>` **(** **)** |const|                                                                       |
++-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`bool<class_bool>`       | :ref:`get_tab_disabled<class_Tabs_method_get_tab_disabled>` **(** :ref:`int<class_int>` tab_idx **)** |const|                                   |
++-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`Texture<class_Texture>` | :ref:`get_tab_icon<class_Tabs_method_get_tab_icon>` **(** :ref:`int<class_int>` tab_idx **)** |const|                                           |
++-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`int<class_int>`         | :ref:`get_tab_offset<class_Tabs_method_get_tab_offset>` **(** **)** |const|                                                                     |
++-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`Rect2<class_Rect2>`     | :ref:`get_tab_rect<class_Tabs_method_get_tab_rect>` **(** :ref:`int<class_int>` tab_idx **)** |const|                                           |
++-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`String<class_String>`   | :ref:`get_tab_title<class_Tabs_method_get_tab_title>` **(** :ref:`int<class_int>` tab_idx **)** |const|                                         |
++-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
+| :ref:`int<class_int>`         | :ref:`get_tabs_rearrange_group<class_Tabs_method_get_tabs_rearrange_group>` **(** **)** |const|                                                 |
++-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
+| void                          | :ref:`move_tab<class_Tabs_method_move_tab>` **(** :ref:`int<class_int>` from, :ref:`int<class_int>` to **)**                                    |
++-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
+| void                          | :ref:`remove_tab<class_Tabs_method_remove_tab>` **(** :ref:`int<class_int>` tab_idx **)**                                                       |
++-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
+| void                          | :ref:`set_select_with_rmb<class_Tabs_method_set_select_with_rmb>` **(** :ref:`bool<class_bool>` enabled **)**                                   |
++-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
+| void                          | :ref:`set_tab_button_icon<class_Tabs_method_set_tab_button_icon>` **(** :ref:`int<class_int>` tab_idx, :ref:`Texture<class_Texture>` icon **)** |
++-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
+| void                          | :ref:`set_tab_disabled<class_Tabs_method_set_tab_disabled>` **(** :ref:`int<class_int>` tab_idx, :ref:`bool<class_bool>` disabled **)**         |
++-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
+| void                          | :ref:`set_tab_icon<class_Tabs_method_set_tab_icon>` **(** :ref:`int<class_int>` tab_idx, :ref:`Texture<class_Texture>` icon **)**               |
++-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
+| void                          | :ref:`set_tab_title<class_Tabs_method_set_tab_title>` **(** :ref:`int<class_int>` tab_idx, :ref:`String<class_String>` title **)**              |
++-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
+| void                          | :ref:`set_tabs_rearrange_group<class_Tabs_method_set_tabs_rearrange_group>` **(** :ref:`int<class_int>` group_id **)**                          |
++-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
 
 Theme Properties
 ----------------
@@ -133,7 +137,7 @@ Emitted when the active tab is rearranged via mouse drag. See :ref:`drag_to_rear
 
 - **right_button_pressed** **(** :ref:`int<class_int>` tab **)**
 
-Emitted when a tab is right-clicked.
+Emitted when a tab's right button is pressed. See :ref:`set_tab_button_icon<class_Tabs_method_set_tab_button_icon>`.
 
 ----
 
@@ -336,6 +340,14 @@ Returns ``true`` if select with right mouse button is enabled.
 
 ----
 
+.. _class_Tabs_method_get_tab_button_icon:
+
+- :ref:`Texture<class_Texture>` **get_tab_button_icon** **(** :ref:`int<class_int>` tab_idx **)** |const|
+
+Returns the button icon from the tab at index ``tab_idx``.
+
+----
+
 .. _class_Tabs_method_get_tab_count:
 
 - :ref:`int<class_int>` **get_tab_count** **(** **)** |const|
@@ -416,6 +428,14 @@ If ``true``, enables selecting a tab with the right mouse button.
 
 ----
 
+.. _class_Tabs_method_set_tab_button_icon:
+
+- void **set_tab_button_icon** **(** :ref:`int<class_int>` tab_idx, :ref:`Texture<class_Texture>` icon **)**
+
+Sets the button icon from the tab at index ``tab_idx``.
+
+----
+
 .. _class_Tabs_method_set_tab_disabled:
 
 - void **set_tab_disabled** **(** :ref:`int<class_int>` tab_idx, :ref:`bool<class_bool>` disabled **)**

classes/class_upnp.rst

@@ -12,21 +12,20 @@ UPNP
 
 **Inherits:** :ref:`Reference<class_Reference>` **<** :ref:`Object<class_Object>`
 
-UPNP network functions.
+Universal Plug and Play (UPnP) functions for network device discovery, querying and port forwarding.
 
 Description
 -----------
 
-Provides UPNP functionality to discover :ref:`UPNPDevice<class_UPNPDevice>`\ s on the local network and execute commands on them, like managing port mappings (port forwarding) and querying the local and remote network IP address. Note that methods on this class are synchronous and block the calling thread.
+This class can be used to discover compatible :ref:`UPNPDevice<class_UPNPDevice>`\ s on the local network and execute commands on them, like managing port mappings (for port forwarding/NAT traversal) and querying the local and remote network IP address. Note that methods on this class are synchronous and block the calling thread.
 
-To forward a specific port:
+To forward a specific port (here ``7777``, note both :ref:`discover<class_UPNP_method_discover>` and :ref:`add_port_mapping<class_UPNP_method_add_port_mapping>` can return errors that should be checked):
 
 ::
 
-    const PORT = 7777
     var upnp = UPNP.new()
-    upnp.discover(2000, 2, "InternetGatewayDevice")
-    upnp.add_port_mapping(port)
+    upnp.discover()
+    upnp.add_port_mapping(7777)
 
 To close a specific port (e.g. after you have finished using it):
 
@@ -41,7 +40,7 @@ To close a specific port (e.g. after you have finished using it):
     # Emitted when UPnP port mapping setup is completed (regardless of success or failure).
     signal upnp_completed(error)
     
-    # Replace this with your own server port number between 1025 and 65535.
+    # Replace this with your own server port number between 1024 and 65535.
     const SERVER_PORT = 3928
     var thread = null
     
@@ -68,6 +67,22 @@ To close a specific port (e.g. after you have finished using it):
         # Wait for thread finish here to handle game exit while the thread is running.
         thread.wait_to_finish()
 
+\ **Terminology:** In the context of UPnP networking, "gateway" (or "internet gateway device", short IGD) refers to network devices that allow computers in the local network to access the internet ("wide area network", WAN). These gateways are often also called "routers".
+
+\ **Pitfalls:**\ 
+
+- As explained above, these calls are blocking and shouldn't be run on the main thread, especially as they can block for multiple seconds at a time. Use threading!
+
+- Networking is physical and messy. Packets get lost in transit or get filtered, addresses, free ports and assigned mappings change, and devices may leave or join the network at any time. Be mindful of this, be diligent when checking and handling errors, and handle these gracefully if you can: add clear error UI, timeouts and re-try handling.
+
+- Port mappings may change (and be removed) at any time, and the remote/external IP address of the gateway can change likewise. You should consider re-querying the external IP and try to update/refresh the port mapping periodically (for example, every 5 minutes and on networking failures).
+
+- Not all devices support UPnP, and some users disable UPnP support. You need to handle this (e.g. documenting and requiring the user to manually forward ports, or adding alternative methods of NAT traversal, like a relay/mirror server, or NAT hole punching, STUN/TURN, etc.).
+
+- Consider what happens on mapping conflicts. Maybe multiple users on the same network would like to play your game at the same time, or maybe another application uses the same port. Make the port configurable, and optimally choose a port automatically (re-trying with a different port on failure).
+
+\ **Further reading:** If you want to know more about UPnP (and the Internet Gateway Device (IGD) and Port Control Protocol (PCP) specifically), `Wikipedia <https://en.wikipedia.org/wiki/Universal_Plug_and_Play>`__ is a good first stop, the specification can be found at the `Open Connectivity Foundation <https://openconnectivity.org/developer/specifications/upnp-resources/upnp/>`__ and Godot's implementation is based on the `MiniUPnP client <https://github.com/miniupnp/miniupnp>`__.
+
 Properties
 ----------
 
@@ -293,11 +308,15 @@ Adds the given :ref:`UPNPDevice<class_UPNPDevice>` to the list of discovered dev
 
 - :ref:`int<class_int>` **add_port_mapping** **(** :ref:`int<class_int>` port, :ref:`int<class_int>` port_internal=0, :ref:`String<class_String>` desc="", :ref:`String<class_String>` proto="UDP", :ref:`int<class_int>` duration=0 **)** |const|
 
-Adds a mapping to forward the external ``port`` (between 1 and 65535) on the default gateway (see :ref:`get_gateway<class_UPNP_method_get_gateway>`) to the ``internal_port`` on the local machine for the given protocol ``proto`` (either ``TCP`` or ``UDP``, with UDP being the default). If a port mapping for the given port and protocol combination already exists on that gateway device, this method tries to overwrite it. If that is not desired, you can retrieve the gateway manually with :ref:`get_gateway<class_UPNP_method_get_gateway>` and call :ref:`add_port_mapping<class_UPNP_method_add_port_mapping>` on it, if any.
+Adds a mapping to forward the external ``port`` (between 1 and 65535, although recommended to use port 1024 or above) on the default gateway (see :ref:`get_gateway<class_UPNP_method_get_gateway>`) to the ``internal_port`` on the local machine for the given protocol ``proto`` (either ``TCP`` or ``UDP``, with UDP being the default). If a port mapping for the given port and protocol combination already exists on that gateway device, this method tries to overwrite it. If that is not desired, you can retrieve the gateway manually with :ref:`get_gateway<class_UPNP_method_get_gateway>` and call :ref:`add_port_mapping<class_UPNP_method_add_port_mapping>` on it, if any. Note that forwarding a well-known port (below 1024) with UPnP may fail depending on the device.
+
+Depending on the gateway device, if a mapping for that port already exists, it will either be updated or it will refuse this command due to that conflict, especially if the existing mapping for that port wasn't created via UPnP or points to a different network address (or device) than this one.
 
 If ``internal_port`` is ``0`` (the default), the same port number is used for both the external and the internal port (the ``port`` value).
 
-The description (``desc``) is shown in some router UIs and can be used to point out which application added the mapping. The mapping's lease duration can be limited by specifying a ``duration`` (in seconds). However, some routers are incompatible with one or both of these, so use with caution and add fallback logic in case of errors to retry without them if in doubt.
+The description (``desc``) is shown in some routers management UIs and can be used to point out which application added the mapping.
+
+The mapping's lease ``duration`` can be limited by specifying a duration in seconds. The default of ``0`` means no duration, i.e. a permanent lease and notably some devices only support these permanent leases. Note that whether permanent or not, this is only a request and the gateway may still decide at any point to remove the mapping (which usually happens on a reboot of the gateway, when its external IP address changes, or on some models when it detects a port mapping has become inactive, i.e. had no traffic for multiple minutes). If not ``0`` (permanent), the allowed range according to spec is between ``120`` (2 minutes) and ``86400`` seconds (24 hours).
 
 See :ref:`UPNPResult<enum_UPNP_UPNPResult>` for possible return values.
 
@@ -315,7 +334,7 @@ Clears the list of discovered devices.
 
 - :ref:`int<class_int>` **delete_port_mapping** **(** :ref:`int<class_int>` port, :ref:`String<class_String>` proto="UDP" **)** |const|
 
-Deletes the port mapping for the given port and protocol combination on the default gateway (see :ref:`get_gateway<class_UPNP_method_get_gateway>`) if one exists. ``port`` must be a valid port between 1 and 65535, ``proto`` can be either ``TCP`` or ``UDP``. See :ref:`UPNPResult<enum_UPNP_UPNPResult>` for possible return values.
+Deletes the port mapping for the given port and protocol combination on the default gateway (see :ref:`get_gateway<class_UPNP_method_get_gateway>`) if one exists. ``port`` must be a valid port between 1 and 65535, ``proto`` can be either ``TCP`` or ``UDP``. May be refused for mappings pointing to addresses other than this one, for well-known ports (below 1024), or for mappings not added via UPnP. See :ref:`UPNPResult<enum_UPNP_UPNPResult>` for possible return values.
 
 ----
 

classes/class_upnpdevice.rst

@@ -12,12 +12,12 @@ UPNPDevice
 
 **Inherits:** :ref:`Reference<class_Reference>` **<** :ref:`Object<class_Object>`
 
-UPNP device.
+Universal Plug and Play (UPnP) device.
 
 Description
 -----------
 
-UPNP device. See :ref:`UPNP<class_UPNP>` for UPNP discovery and utility functions. Provides low-level access to UPNP control commands. Allows to manage port mappings (port forwarding) and to query network information of the device (like local and external IP address and status). Note that methods on this class are synchronous and block the calling thread.
+Universal Plug and Play (UPnP) device. See :ref:`UPNP<class_UPNP>` for UPnP discovery and utility functions. Provides low-level access to UPNP control commands. Allows to manage port mappings (port forwarding) and to query network information of the device (like local and external IP address and status). Note that methods on this class are synchronous and block the calling thread.
 
 Properties
 ----------

classes/class_weakref.rst

@@ -33,7 +33,7 @@ Method Descriptions
 
 - :ref:`Variant<class_Variant>` **get_ref** **(** **)** |const|
 
-Returns the :ref:`Object<class_Object>` this weakref is referring to.
+Returns the :ref:`Object<class_Object>` this weakref is referring to. Returns ``null`` if that object no longer exists.
 
 .. |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.)`