classref: Sync with current 3.3 branch

classes/class_animationnodetimeseek.rst

@@ -16,7 +16,19 @@ A time-seeking animation node to be used with :ref:`AnimationTree<class_Animatio
 Description
 -----------
 
-This node can be used to cause a seek command to happen to any sub-children of the graph. After setting the time, this value returns to -1.
+This node can be used to cause a seek command to happen to any sub-children of the animation graph. Use this node type to play an :ref:`Animation<class_Animation>` from the start or a certain playback position inside the :ref:`AnimationNodeBlendTree<class_AnimationNodeBlendTree>`. After setting the time and changing the animation playback, the seek node automatically goes into sleep mode on the next process frame by setting its ``seek_position`` value to ``-1.0``.
+
+::
+
+    # Play child animation from the start.
+    animation_tree.set("parameters/Seek/seek_position", 0.0)
+    # Alternative syntax (same result as above).
+    animation_tree["parameters/Seek/seek_position"] = 0.0
+    
+    # Play child animation from 12 second timestamp.
+    animation_tree.set("parameters/Seek/seek_position", 12.0)
+    # Alternative syntax (same result as above).
+    animation_tree["parameters/Seek/seek_position"] = 12.0
 
 Tutorials
 ---------

classes/class_astar.rst

@@ -275,6 +275,8 @@ Returns the number of points currently in the points pool.
 
 Returns an array with the points that are in the path found by AStar between the given points. The array is ordered from the starting point to the ending point of the path.
 
+**Note:** This method is not thread-safe. If called from a :ref:`Thread<class_Thread>`, it will return an empty :ref:`PoolVector3Array<class_PoolVector3Array>` and will print an error message.
+
 ----
 
 .. _class_AStar_method_get_point_position:

classes/class_astar2d.rst

@@ -256,6 +256,8 @@ Returns the number of points currently in the points pool.
 
 Returns an array with the points that are in the path found by AStar2D between the given points. The array is ordered from the starting point to the ending point of the path.
 
+**Note:** This method is not thread-safe. If called from a :ref:`Thread<class_Thread>`, it will return an empty :ref:`PoolVector2Array<class_PoolVector2Array>` and will print an error message.
+
 ----
 
 .. _class_AStar2D_method_get_point_position:

classes/class_capsulemesh.rst

@@ -46,7 +46,9 @@ Property Descriptions
 | *Getter*  | get_mid_height()      |
 +-----------+-----------------------+
 
-Height of the capsule mesh from the center point.
+Height of the middle cylindrical part of the capsule (without the hemispherical ends).
+
+**Note:** The capsule's total height is equal to :ref:`mid_height<class_CapsuleMesh_property_mid_height>` + 2 \* :ref:`radius<class_CapsuleMesh_property_radius>`.
 
 ----
 

classes/class_editorinterface.rst

@@ -30,6 +30,8 @@ Properties
 Methods
 -------
 
++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| void                                                      | :ref:`edit_node<class_EditorInterface_method_edit_node>` **(** :ref:`Node<class_Node>` node **)**                                                                                                            |
 +-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | void                                                      | :ref:`edit_resource<class_EditorInterface_method_edit_resource>` **(** :ref:`Resource<class_Resource>` resource **)**                                                                                        |
 +-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -112,6 +114,14 @@ If ``true``, enables distraction-free mode which hides side docks to increase th
 Method Descriptions
 -------------------
 
+.. _class_EditorInterface_method_edit_node:
+
+- void **edit_node** **(** :ref:`Node<class_Node>` node **)**
+
+Edits the given :ref:`Node<class_Node>`. The node will be also selected if it's inside the scene tree.
+
+----
+
 .. _class_EditorInterface_method_edit_resource:
 
 - void **edit_resource** **(** :ref:`Resource<class_Resource>` resource **)**

classes/class_editorplugin.rst

@@ -433,7 +433,7 @@ Called by the engine when the 2D editor's viewport is updated. Use the ``overlay
 
     func forward_canvas_draw_over_viewport(overlay):
         # Draw a circle at cursor position.
-        overlay.draw_circle(overlay.get_local_mouse_position(), 64)
+        overlay.draw_circle(overlay.get_local_mouse_position(), 64, Color.white)
     
     func forward_canvas_gui_input(event):
         if event is InputEventMouseMotion:

classes/class_editorselection.rst

@@ -53,6 +53,8 @@ Method Descriptions
 
 Adds a node to the selection.
 
+**Note:** The newly selected node will not be automatically edited in the inspector. If you want to edit a node, use :ref:`EditorInterface.edit_node<class_EditorInterface_method_edit_node>`.
+
 ----
 
 .. _class_EditorSelection_method_clear:

classes/class_engine.rst

@@ -83,7 +83,18 @@ Property Descriptions
 | *Getter*  | is_editor_hint()       |
 +-----------+------------------------+
 
-If ``true``, it is running inside the editor. Useful for tool scripts.
+If ``true``, the script is currently running inside the editor. This is useful for ``tool`` scripts to conditionally draw editor helpers, or prevent accidentally running "game" code that would affect the scene state while in the editor:
+
+::
+
+    if Engine.editor_hint:
+        draw_gizmos()
+    else:
+        simulate_physics()
+
+See `Running code in the editor <https://docs.godotengine.org/en/stable/tutorials/misc/running_code_in_the_editor.html>`_ in the documentation for more information.
+
+**Note:** To detect whether the script is run from an editor *build* (e.g. when pressing ``F5``), use :ref:`OS.has_feature<class_OS_method_has_feature>` with the ``"editor"`` argument instead. ``OS.has_feature("editor")`` will evaluate to ``true`` both when the code is running in the editor and when running the project from the editor, but it will evaluate to ``false`` when the code is run from an exported project.
 
 ----
 

classes/class_geometry.rst

@@ -353,7 +353,7 @@ Given an array of :ref:`Vector2<class_Vector2>`\ s representing tiles, builds an
 
 Merges (combines) ``polygon_a`` and ``polygon_b`` and returns an array of merged polygons. This performs :ref:`OPERATION_UNION<class_Geometry_constant_OPERATION_UNION>` between polygons.
 
-The operation may result in an outer polygon (boundary) and inner polygon (hole) produced which could be distinguished by calling :ref:`is_polygon_clockwise<class_Geometry_method_is_polygon_clockwise>`.
+The operation may result in an outer polygon (boundary) and multiple inner polygons (holes) produced which could be distinguished by calling :ref:`is_polygon_clockwise<class_Geometry_method_is_polygon_clockwise>`.
 
 ----
 

classes/class_node.rst

@@ -1166,6 +1166,8 @@ Notifies the current node and all its children recursively by calling :ref:`Obje
 
 Queues a node for deletion at the end of the current frame. When deleted, all of its child nodes will be deleted as well. This method ensures it's safe to delete the node, contrary to :ref:`Object.free<class_Object_method_free>`. Use :ref:`Object.is_queued_for_deletion<class_Object_method_is_queued_for_deletion>` to check whether a node will be deleted at the end of the frame.
 
+**Important:** If you have a variable pointing to a node, it will *not* be assigned to ``null`` once the node is freed. Instead, it will point to a *previously freed instance* and you should validate it with :ref:`@GDScript.is_instance_valid<class_@GDScript_method_is_instance_valid>` before attempting to call its methods or access its properties.
+
 ----
 
 .. _class_Node_method_raise:

classes/class_object.rst

@@ -364,7 +364,9 @@ Emits the given ``signal``. The signal must exist, so it should be a built-in si
 
 - void **free** **(** **)**
 
-Deletes the object from memory. Any pre-existing reference to the freed object will become invalid, e.g. ``is_instance_valid(object)`` will return ``false``.
+Deletes the object from memory immediately. For :ref:`Node<class_Node>`\ s, you may want to use :ref:`Node.queue_free<class_Node_method_queue_free>` to queue the node for safe deletion at the end of the current frame.
+
+**Important:** If you have a variable pointing to an object, it will *not* be assigned to ``null`` once the object is freed. Instead, it will point to a *previously freed instance* and you should validate it with :ref:`@GDScript.is_instance_valid<class_@GDScript_method_is_instance_valid>` before attempting to call its methods or access its properties.
 
 ----
 

classes/class_projectsettings.rst

@@ -20,7 +20,7 @@ Contains global variables accessible from everywhere. Use :ref:`get_setting<clas
 
 When naming a Project Settings property, use the full path to the setting including the category. For example, ``"application/config/name"`` for the project name. Category and property names can be viewed in the Project Settings dialog.
 
-**Overriding:** Any project setting can be overridden by creating a file named ``override.cfg`` in the project's root directory. This can also be used in exported projects by placing this file in the same directory as the project binary.
+**Overriding:** Any project setting can be overridden by creating a file named ``override.cfg`` in the project's root directory. This can also be used in exported projects by placing this file in the same directory as the project binary. Overriding will still take the base project settings' `feature tags <https://docs.godotengine.org/en/latest/tutorials/export/feature_tags.html>`_ in account. Therefore, make sure to *also* override the setting with the desired feature tags if you want them to override base project settings on all platforms and configurations.
 
 Tutorials
 ---------
@@ -551,6 +551,14 @@ Properties
 +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+
 | :ref:`float<class_float>`                     | :ref:`physics/common/physics_jitter_fix<class_ProjectSettings_property_physics/common/physics_jitter_fix>`                                                           | ``0.5``                                                                                         |
 +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+
+| :ref:`int<class_int>`                         | :ref:`rendering/2d/opengl/batching_send_null<class_ProjectSettings_property_rendering/2d/opengl/batching_send_null>`                                                 | ``0``                                                                                           |
++-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+
+| :ref:`int<class_int>`                         | :ref:`rendering/2d/opengl/batching_stream<class_ProjectSettings_property_rendering/2d/opengl/batching_stream>`                                                       | ``0``                                                                                           |
++-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+
+| :ref:`int<class_int>`                         | :ref:`rendering/2d/opengl/legacy_orphan_buffers<class_ProjectSettings_property_rendering/2d/opengl/legacy_orphan_buffers>`                                           | ``0``                                                                                           |
++-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+
+| :ref:`int<class_int>`                         | :ref:`rendering/2d/opengl/legacy_stream<class_ProjectSettings_property_rendering/2d/opengl/legacy_stream>`                                                           | ``0``                                                                                           |
++-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+
 | :ref:`int<class_int>`                         | :ref:`rendering/2d/options/ninepatch_mode<class_ProjectSettings_property_rendering/2d/options/ninepatch_mode>`                                                       | ``1``                                                                                           |
 +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+
 | :ref:`bool<class_bool>`                       | :ref:`rendering/2d/options/use_nvidia_rect_flicker_workaround<class_ProjectSettings_property_rendering/2d/options/use_nvidia_rect_flicker_workaround>`               | ``false``                                                                                       |
@@ -679,6 +687,8 @@ Properties
 +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+
 | :ref:`bool<class_bool>`                       | :ref:`rendering/quality/shading/force_vertex_shading.mobile<class_ProjectSettings_property_rendering/quality/shading/force_vertex_shading.mobile>`                   | ``true``                                                                                        |
 +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+
+| :ref:`int<class_int>`                         | :ref:`rendering/quality/shadow_atlas/cubemap_size<class_ProjectSettings_property_rendering/quality/shadow_atlas/cubemap_size>`                                       | ``512``                                                                                         |
++-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+
 | :ref:`int<class_int>`                         | :ref:`rendering/quality/shadow_atlas/quadrant_0_subdiv<class_ProjectSettings_property_rendering/quality/shadow_atlas/quadrant_0_subdiv>`                             | ``1``                                                                                           |
 +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+
 | :ref:`int<class_int>`                         | :ref:`rendering/quality/shadow_atlas/quadrant_1_subdiv<class_ProjectSettings_property_rendering/quality/shadow_atlas/quadrant_1_subdiv>`                             | ``2``                                                                                           |
@@ -900,9 +910,9 @@ The project's name. It is used both by the Project Manager and by exporters. The
 | *Default* | ``""`` |
 +-----------+--------+
 
-Specifies a file to override project settings. For example: ``user://custom_settings.cfg``.
+Specifies a file to override project settings. For example: ``user://custom_settings.cfg``. See "Overriding" in the ``ProjectSettings`` class description at the top for more information.
 
-**Note:** Regardless of this setting's value, ``res://override.cfg`` will still be read to override the project settings (see this class' description at the top).
+**Note:** Regardless of this setting's value, ``res://override.cfg`` will still be read to override the project settings.
 
 ----
 
@@ -3918,6 +3928,62 @@ Fix to improve physics jitter, specially on monitors where refresh rate is diffe
 
 ----
 
+.. _class_ProjectSettings_property_rendering/2d/opengl/batching_send_null:
+
+- :ref:`int<class_int>` **rendering/2d/opengl/batching_send_null**
+
++-----------+-------+
+| *Default* | ``0`` |
++-----------+-------+
+
+**Experimental** Calls ``glBufferData`` with NULL data prior to uploading batching data. This may not be necessary but can be used for safety.
+
+**Note:** Use with care. You are advised to leave this as default for exports. A non-default setting that works better on your machine may adversely affect performance for end users.
+
+----
+
+.. _class_ProjectSettings_property_rendering/2d/opengl/batching_stream:
+
+- :ref:`int<class_int>` **rendering/2d/opengl/batching_stream**
+
++-----------+-------+
+| *Default* | ``0`` |
++-----------+-------+
+
+**Experimental** If set to on, uses the ``GL_STREAM_DRAW`` flag for batching buffer uploads. If off, uses the ``GL_DYNAMIC_DRAW`` flag.
+
+**Note:** Use with care. You are advised to leave this as default for exports. A non-default setting that works better on your machine may adversely affect performance for end users.
+
+----
+
+.. _class_ProjectSettings_property_rendering/2d/opengl/legacy_orphan_buffers:
+
+- :ref:`int<class_int>` **rendering/2d/opengl/legacy_orphan_buffers**
+
++-----------+-------+
+| *Default* | ``0`` |
++-----------+-------+
+
+**Experimental** If set to on, this applies buffer orphaning - ``glBufferData`` is called with NULL data and the full buffer size prior to uploading new data. This can be important to avoid stalling on some hardware.
+
+**Note:** Use with care. You are advised to leave this as default for exports. A non-default setting that works better on your machine may adversely affect performance for end users.
+
+----
+
+.. _class_ProjectSettings_property_rendering/2d/opengl/legacy_stream:
+
+- :ref:`int<class_int>` **rendering/2d/opengl/legacy_stream**
+
++-----------+-------+
+| *Default* | ``0`` |
++-----------+-------+
+
+**Experimental** If set to on, uses the ``GL_STREAM_DRAW`` flag for legacy buffer uploads. If off, uses the ``GL_DYNAMIC_DRAW`` flag.
+
+**Note:** Use with care. You are advised to leave this as default for exports. A non-default setting that works better on your machine may adversely affect performance for end users.
+
+----
+
 .. _class_ProjectSettings_property_rendering/2d/options/ninepatch_mode:
 
 - :ref:`int<class_int>` **rendering/2d/options/ninepatch_mode**
@@ -4718,6 +4784,18 @@ Lower-end override for :ref:`rendering/quality/shading/force_vertex_shading<clas
 
 ----
 
+.. _class_ProjectSettings_property_rendering/quality/shadow_atlas/cubemap_size:
+
+- :ref:`int<class_int>` **rendering/quality/shadow_atlas/cubemap_size**
+
++-----------+---------+
+| *Default* | ``512`` |
++-----------+---------+
+
+Size for cubemap into which the shadow is rendered before being copied into the shadow atlas. A higher number can result in higher resolution shadows when used with a higher :ref:`rendering/quality/shadow_atlas/size<class_ProjectSettings_property_rendering/quality/shadow_atlas/size>`. Setting higher than a quarter of the :ref:`rendering/quality/shadow_atlas/size<class_ProjectSettings_property_rendering/quality/shadow_atlas/size>` will not result in a perceptible increase in visual quality.
+
+----
+
 .. _class_ProjectSettings_property_rendering/quality/shadow_atlas/quadrant_0_subdiv:
 
 - :ref:`int<class_int>` **rendering/quality/shadow_atlas/quadrant_0_subdiv**

classes/class_streampeertcp.rst

@@ -115,9 +115,9 @@ Returns ``true`` if this peer is currently connected or is connecting to a host,
 
 - void **set_no_delay** **(** :ref:`bool<class_bool>` enabled **)**
 
-Disables Nagle's algorithm to improve latency for small packets.
+If ``enabled`` is ``true``, packets will be sent immediately. If ``enabled`` is ``false`` (the default), packet transfers will be delayed and combined using `Nagle's algorithm <https://en.wikipedia.org/wiki/Nagle%27s_algorithm>`_.
 
-**Note:** For applications that send large packets or need to transfer a lot of data, this can decrease the total available bandwidth.
+**Note:** It's recommended to leave this disabled for applications that send large packets or need to transfer a lot of data, as enabling this can decrease the total available bandwidth.
 
 .. |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_texturearray.rst

@@ -16,7 +16,22 @@ Array of textures stored in a single primitive.
 Description
 -----------
 
-``TextureArray``\ s store an array of images in a single :ref:`Texture<class_Texture>` primitive. Each layer of the texture array has its own mipmap chain. This makes it is a good alternative to texture atlases.
+``TextureArray``\ s store an array of :ref:`Image<class_Image>`\ s in a single :ref:`Texture<class_Texture>` primitive. Each layer of the texture array has its own mipmap chain. This makes it is a good alternative to texture atlases.
+
+``TextureArray``\ s must be displayed using shaders. After importing your file as a ``TextureArray`` and setting the appropriate Horizontal and Vertical Slices, display it by setting it as a uniform to a shader, for example:
+
+::
+
+    shader_type canvas_item;
+    
+    uniform sampler2DArray tex;
+    uniform int index;
+    
+    void fragment() {
+        COLOR = texture(tex, vec3(UV.x, UV.y, float(index)));
+    }
+
+Set the integer uniform "index" to show a particular part of the texture as defined by the Horizontal and Vertical Slices in the importer.
 
 .. |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_videoplayer.rst

@@ -198,6 +198,8 @@ The assigned video stream. See description for supported formats.
 
 The current position of the stream, in seconds.
 
+**Note:** Changing this value won't have any effect as seeking is not implemented yet, except in video formats implemented by a GDNative add-on.
+
 ----
 
 .. _class_VideoPlayer_property_volume:

classes/class_websocketclient.rst

@@ -137,6 +137,8 @@ If ``false`` is passed instead (default), you must call :ref:`PacketPeer<class_P
 
 You can optionally pass a list of ``custom_headers`` to be added to the handshake HTTP request.
 
+**Note:** To avoid mixed content warnings or errors in HTML5, you may have to use a ``url`` that starts with ``wss://`` (secure) instead of ``ws://``. When doing so, make sure to use the fully qualified domain name that matches the one defined in the server's SSL certificate. Do not connect directly via the IP address for ``wss://`` connections, as it won't match with the SSL certificate.
+
 **Note:** Specifying ``custom_headers`` is not supported in HTML5 exports due to browsers restrictions.
 
 ----