classref: Sync with current 3.4 branch (c02325ffd)

classes/class_canvasitem.rst

@@ -382,6 +382,10 @@ Overridable function called by the engine (if defined) to draw the canvas item.
 
 Draws a unfilled arc between the given angles. The larger the value of ``point_count``, the smoother the curve. See also :ref:`draw_circle<class_CanvasItem_method_draw_circle>`.
 
+**Note:** Line drawing is not accelerated by batching if ``antialiased`` is ``true``.
+
+**Note:** Due to how it works, built-in antialiasing will not look correct for translucent lines and may not work on certain platforms. As a workaround, install the `Antialiased Line2D <https://github.com/godot-extended-libraries/godot-antialiased-line2d>`__ add-on then create an AntialiasedRegularPolygon2D node. That node relies on a texture with custom mipmaps to perform antialiasing. 2D batching is also still supported with those antialiased lines.
+
 ----
 
 .. _class_CanvasItem_method_draw_char:
@@ -398,6 +402,8 @@ Draws a string character using a custom font. Returns the advance, depending on
 
 Draws a colored, unfilled circle. See also :ref:`draw_arc<class_CanvasItem_method_draw_arc>`, :ref:`draw_polyline<class_CanvasItem_method_draw_polyline>` and :ref:`draw_polygon<class_CanvasItem_method_draw_polygon>`.
 
+**Note:** Built-in antialiasing is not provided for :ref:`draw_circle<class_CanvasItem_method_draw_circle>`. As a workaround, install the `Antialiased Line2D <https://github.com/godot-extended-libraries/godot-antialiased-line2d>`__ add-on then create an AntialiasedRegularPolygon2D node. That node relies on a texture with custom mipmaps to perform antialiasing.
+
 ----
 
 .. _class_CanvasItem_method_draw_colored_polygon:
@@ -406,6 +412,8 @@ Draws a colored, unfilled circle. See also :ref:`draw_arc<class_CanvasItem_metho
 
 Draws a colored polygon of any amount of points, convex or concave. Unlike :ref:`draw_polygon<class_CanvasItem_method_draw_polygon>`, a single color must be specified for the whole polygon.
 
+**Note:** Due to how it works, built-in antialiasing will not look correct for translucent polygons and may not work on certain platforms. As a workaround, install the `Antialiased Line2D <https://github.com/godot-extended-libraries/godot-antialiased-line2d>`__ add-on then create an AntialiasedPolygon2D node. That node relies on a texture with custom mipmaps to perform antialiasing.
+
 ----
 
 .. _class_CanvasItem_method_draw_line:
@@ -414,6 +422,10 @@ Draws a colored polygon of any amount of points, convex or concave. Unlike :ref:
 
 Draws a line from a 2D point to another, with a given color and width. It can be optionally antialiased. See also :ref:`draw_multiline<class_CanvasItem_method_draw_multiline>` and :ref:`draw_polyline<class_CanvasItem_method_draw_polyline>`.
 
+**Note:** Line drawing is not accelerated by batching if ``antialiased`` is ``true``.
+
+**Note:** Due to how it works, built-in antialiasing will not look correct for translucent lines and may not work on certain platforms. As a workaround, install the `Antialiased Line2D <https://github.com/godot-extended-libraries/godot-antialiased-line2d>`__ add-on then create an AntialiasedLine2D node. That node relies on a texture with custom mipmaps to perform antialiasing. 2D batching is also still supported with those antialiased lines.
+
 ----
 
 .. _class_CanvasItem_method_draw_mesh:
@@ -430,7 +442,7 @@ Draws a :ref:`Mesh<class_Mesh>` in 2D, using the provided texture. See :ref:`Mes
 
 Draws multiple disconnected lines with a uniform ``color``. When drawing large amounts of lines, this is faster than using individual :ref:`draw_line<class_CanvasItem_method_draw_line>` calls. To draw interconnected lines, use :ref:`draw_polyline<class_CanvasItem_method_draw_polyline>` instead.
 
-**Note:** ``width`` and ``antialiased`` are currently not implemented and have no effect.
+**Note:** ``width`` and ``antialiased`` are currently not implemented and have no effect. As a workaround, install the `Antialiased Line2D <https://github.com/godot-extended-libraries/godot-antialiased-line2d>`__ add-on then create an AntialiasedLine2D node. That node relies on a texture with custom mipmaps to perform antialiasing. 2D batching is also still supported with those antialiased lines.
 
 ----
 
@@ -440,7 +452,7 @@ Draws multiple disconnected lines with a uniform ``color``. When drawing large a
 
 Draws multiple disconnected lines with a uniform ``width`` and segment-by-segment coloring. Colors assigned to line segments match by index between ``points`` and ``colors``. When drawing large amounts of lines, this is faster than using individual :ref:`draw_line<class_CanvasItem_method_draw_line>` calls. To draw interconnected lines, use :ref:`draw_polyline_colors<class_CanvasItem_method_draw_polyline_colors>` instead.
 
-**Note:** ``width`` and ``antialiased`` are currently not implemented and have no effect.
+**Note:** ``width`` and ``antialiased`` are currently not implemented and have no effect. As a workaround, install the `Antialiased Line2D <https://github.com/godot-extended-libraries/godot-antialiased-line2d>`__ add-on then create an AntialiasedLine2D node. That node relies on a texture with custom mipmaps to perform antialiasing. 2D batching is also still supported with those antialiased lines.
 
 ----
 
@@ -458,6 +470,8 @@ Draws a :ref:`MultiMesh<class_MultiMesh>` in 2D with the provided texture. See :
 
 Draws a solid polygon of any amount of points, convex or concave. Unlike :ref:`draw_colored_polygon<class_CanvasItem_method_draw_colored_polygon>`, each point's color can be changed individually. See also :ref:`draw_polyline<class_CanvasItem_method_draw_polyline>` and :ref:`draw_polyline_colors<class_CanvasItem_method_draw_polyline_colors>`.
 
+**Note:** Due to how it works, built-in antialiasing will not look correct for translucent polygons and may not work on certain platforms. As a workaround, install the `Antialiased Line2D <https://github.com/godot-extended-libraries/godot-antialiased-line2d>`__ add-on then create an AntialiasedPolygon2D node. That node relies on a texture with custom mipmaps to perform antialiasing.
+
 ----
 
 .. _class_CanvasItem_method_draw_polyline:
@@ -466,6 +480,8 @@ Draws a solid polygon of any amount of points, convex or concave. Unlike :ref:`d
 
 Draws interconnected line segments with a uniform ``color`` and ``width`` and optional antialiasing. When drawing large amounts of lines, this is faster than using individual :ref:`draw_line<class_CanvasItem_method_draw_line>` calls. To draw disconnected lines, use :ref:`draw_multiline<class_CanvasItem_method_draw_multiline>` instead. See also :ref:`draw_polygon<class_CanvasItem_method_draw_polygon>`.
 
+**Note:** Due to how it works, built-in antialiasing will not look correct for translucent polygons and may not work on certain platforms. As a workaround, install the `Antialiased Line2D <https://github.com/godot-extended-libraries/godot-antialiased-line2d>`__ add-on then create an AntialiasedPolygon2D node. That node relies on a texture with custom mipmaps to perform antialiasing.
+
 ----
 
 .. _class_CanvasItem_method_draw_polyline_colors:
@@ -474,6 +490,8 @@ Draws interconnected line segments with a uniform ``color`` and ``width`` and op
 
 Draws interconnected line segments with a uniform ``width`` and segment-by-segment coloring, and optional antialiasing. Colors assigned to line segments match by index between ``points`` and ``colors``. When drawing large amounts of lines, this is faster than using individual :ref:`draw_line<class_CanvasItem_method_draw_line>` calls. To draw disconnected lines, use :ref:`draw_multiline_colors<class_CanvasItem_method_draw_multiline_colors>` instead. See also :ref:`draw_polygon<class_CanvasItem_method_draw_polygon>`.
 
+**Note:** Due to how it works, built-in antialiasing will not look correct for translucent polygons and may not work on certain platforms. As a workaround, install the `Antialiased Line2D <https://github.com/godot-extended-libraries/godot-antialiased-line2d>`__ add-on then create an AntialiasedPolygon2D node. That node relies on a texture with custom mipmaps to perform antialiasing.
+
 ----
 
 .. _class_CanvasItem_method_draw_primitive:
@@ -488,10 +506,12 @@ Draws a custom primitive. 1 point for a point, 2 points for a line, 3 points for
 
 - void **draw_rect** **(** :ref:`Rect2<class_Rect2>` rect, :ref:`Color<class_Color>` color, :ref:`bool<class_bool>` filled=true, :ref:`float<class_float>` width=1.0, :ref:`bool<class_bool>` antialiased=false **)**
 
-Draws a rectangle. If ``filled`` is ``true``, the rectangle will be filled with the ``color`` specified. If ``filled`` is ``false``, the rectangle will be drawn as a stroke with the ``color`` and ``width`` specified. If ``antialiased`` is ``true``, the lines will be antialiased.
+Draws a rectangle. If ``filled`` is ``true``, the rectangle will be filled with the ``color`` specified. If ``filled`` is ``false``, the rectangle will be drawn as a stroke with the ``color`` and ``width`` specified. If ``antialiased`` is ``true``, the lines will attempt to perform antialiasing using OpenGL line smoothing.
 
 **Note:** ``width`` and ``antialiased`` are only effective if ``filled`` is ``false``.
 
+**Note:** Due to how it works, built-in antialiasing will not look correct for translucent polygons and may not work on certain platforms. As a workaround, install the `Antialiased Line2D <https://github.com/godot-extended-libraries/godot-antialiased-line2d>`__ add-on then create an AntialiasedPolygon2D node. That node relies on a texture with custom mipmaps to perform antialiasing.
+
 ----
 
 .. _class_CanvasItem_method_draw_set_transform:

classes/class_editorsceneimportergltf.rst

@@ -13,6 +13,11 @@ EditorSceneImporterGLTF
 
 
 
+Description
+-----------
+
+**Note:** This class is only compiled in editor builds. Run-time glTF loading and saving is *not* available in exported projects. References to ``EditorSceneImporterGLTF`` within a script will cause an error in an exported project.
+
 .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
 .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
 .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`

classes/class_environment.rst

@@ -312,15 +312,17 @@ enum **GlowBlendMode**:
 
 enum **ToneMapper**:
 
-- **TONE_MAPPER_LINEAR** = **0** --- Linear tonemapper operator. Reads the linear data and passes it on unmodified.
+- **TONE_MAPPER_LINEAR** = **0** --- Linear tonemapper operator. Reads the linear data and passes it on unmodified. This can cause bright lighting to look blown out, with noticeable clipping in the output colors.
 
-- **TONE_MAPPER_REINHARDT** = **1** --- Reinhardt tonemapper operator. Performs a variation on rendered pixels' colors by this formula: ``color = color / (1 + color)``.
+- **TONE_MAPPER_REINHARDT** = **1** --- Reinhardt tonemapper operator. Performs a variation on rendered pixels' colors by this formula: ``color = color / (1 + color)``. This avoids clipping bright highlights, but the resulting image can look a bit dull.
 
-- **TONE_MAPPER_FILMIC** = **2** --- Filmic tonemapper operator.
+- **TONE_MAPPER_FILMIC** = **2** --- Filmic tonemapper operator. This avoids clipping bright highlights, with a resulting image that usually looks more vivid than :ref:`TONE_MAPPER_REINHARDT<class_Environment_constant_TONE_MAPPER_REINHARDT>`.
 
-- **TONE_MAPPER_ACES** = **3** --- Academy Color Encoding System tonemapper operator. Performs an approximation of the ACES tonemapping curve.
+- **TONE_MAPPER_ACES** = **3** --- Use the legacy Godot version of the Academy Color Encoding System tonemapper. Unlike :ref:`TONE_MAPPER_ACES_FITTED<class_Environment_constant_TONE_MAPPER_ACES_FITTED>`, this version of ACES does not handle bright lighting in a physically accurate way. ACES typically has a more contrasted output compared to :ref:`TONE_MAPPER_REINHARDT<class_Environment_constant_TONE_MAPPER_REINHARDT>` and :ref:`TONE_MAPPER_FILMIC<class_Environment_constant_TONE_MAPPER_FILMIC>`.
 
-- **TONE_MAPPER_ACES_FITTED** = **4** --- High quality Academy Color Encoding System tonemapper operator that matches the industry standard. Performs a more physically accurate curve fit which better simulates how light works in the real world. The color of lights and emissive materials will become lighter as the emissive energy increases, and will eventually become white if the light is bright enough to saturate the camera sensor.
+**Note:** This tonemapping operator will be removed in Godot 4.0 in favor of the more accurate :ref:`TONE_MAPPER_ACES_FITTED<class_Environment_constant_TONE_MAPPER_ACES_FITTED>`.
+
+- **TONE_MAPPER_ACES_FITTED** = **4** --- Use the Academy Color Encoding System tonemapper. ACES is slightly more expensive than other options, but it handles bright lighting in a more realistic fashion by desaturating it as it becomes brighter. ACES typically has a more contrasted output compared to :ref:`TONE_MAPPER_REINHARDT<class_Environment_constant_TONE_MAPPER_REINHARDT>` and :ref:`TONE_MAPPER_FILMIC<class_Environment_constant_TONE_MAPPER_FILMIC>`.
 
 ----
 

classes/class_gltfaccessor.rst

@@ -13,6 +13,11 @@ GLTFAccessor
 
 
 
+Description
+-----------
+
+**Note:** This class is only compiled in editor builds. Run-time glTF loading and saving is *not* available in exported projects. References to ``GLTFAccessor`` within a script will cause an error in an exported project.
+
 Properties
 ----------
 

classes/class_gltfanimation.rst

@@ -13,6 +13,11 @@ GLTFAnimation
 
 
 
+Description
+-----------
+
+**Note:** This class is only compiled in editor builds. Run-time glTF loading and saving is *not* available in exported projects. References to ``GLTFAnimation`` within a script will cause an error in an exported project.
+
 Properties
 ----------
 

classes/class_gltfbufferview.rst

@@ -13,6 +13,11 @@ GLTFBufferView
 
 
 
+Description
+-----------
+
+**Note:** This class is only compiled in editor builds. Run-time glTF loading and saving is *not* available in exported projects. References to ``GLTFBufferView`` within a script will cause an error in an exported project.
+
 Properties
 ----------
 

classes/class_gltfcamera.rst

@@ -13,6 +13,11 @@ GLTFCamera
 
 
 
+Description
+-----------
+
+**Note:** This class is only compiled in editor builds. Run-time glTF loading and saving is *not* available in exported projects. References to ``GLTFCamera`` within a script will cause an error in an exported project.
+
 Properties
 ----------
 

classes/class_gltfdocument.rst

@@ -13,6 +13,11 @@ GLTFDocument
 
 
 
+Description
+-----------
+
+**Note:** This class is only compiled in editor builds. Run-time glTF loading and saving is *not* available in exported projects. References to ``GLTFDocument`` within a script will cause an error in an exported project.
+
 .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
 .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
 .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`

classes/class_gltflight.rst

@@ -13,6 +13,11 @@ GLTFLight
 
 
 
+Description
+-----------
+
+**Note:** This class is only compiled in editor builds. Run-time glTF loading and saving is *not* available in exported projects. References to ``GLTFLight`` within a script will cause an error in an exported project.
+
 Properties
 ----------
 

classes/class_gltfmesh.rst

@@ -13,6 +13,11 @@ GLTFMesh
 
 
 
+Description
+-----------
+
+**Note:** This class is only compiled in editor builds. Run-time glTF loading and saving is *not* available in exported projects. References to ``GLTFMesh`` within a script will cause an error in an exported project.
+
 Properties
 ----------
 

classes/class_gltfnode.rst

@@ -13,6 +13,11 @@ GLTFNode
 
 
 
+Description
+-----------
+
+**Note:** This class is only compiled in editor builds. Run-time glTF loading and saving is *not* available in exported projects. References to ``GLTFNode`` within a script will cause an error in an exported project.
+
 Properties
 ----------
 

classes/class_gltfskeleton.rst

@@ -13,6 +13,11 @@ GLTFSkeleton
 
 
 
+Description
+-----------
+
+**Note:** This class is only compiled in editor builds. Run-time glTF loading and saving is *not* available in exported projects. References to ``GLTFSkeleton`` within a script will cause an error in an exported project.
+
 Properties
 ----------
 

classes/class_gltfspecgloss.rst

@@ -13,6 +13,11 @@ GLTFSpecGloss
 
 
 
+Description
+-----------
+
+**Note:** This class is only compiled in editor builds. Run-time glTF loading and saving is *not* available in exported projects. References to ``GLTFSpecGloss`` within a script will cause an error in an exported project.
+
 Properties
 ----------
 

classes/class_gltfstate.rst

@@ -13,6 +13,11 @@ GLTFState
 
 
 
+Description
+-----------
+
+**Note:** This class is only compiled in editor builds. Run-time glTF loading and saving is *not* available in exported projects. References to ``GLTFState`` within a script will cause an error in an exported project.
+
 Properties
 ----------
 

classes/class_gltftexture.rst

@@ -13,6 +13,11 @@ GLTFTexture
 
 
 
+Description
+-----------
+
+**Note:** This class is only compiled in editor builds. Run-time glTF loading and saving is *not* available in exported projects. References to ``GLTFTexture`` within a script will cause an error in an exported project.
+
 Properties
 ----------
 

classes/class_inputmap.rst

@@ -139,6 +139,8 @@ If ``exact_match`` is ``false``, it ignores the input modifiers for :ref:`InputE
 
 Returns an array of :ref:`InputEvent<class_InputEvent>`\ s associated with a given action.
 
+**Note:** When used in the editor (e.g. a tool script or :ref:`EditorPlugin<class_EditorPlugin>`), this method will return events for the editor action. If you want to access your project's input binds from the editor, read the ``input/*`` settings from :ref:`ProjectSettings<class_ProjectSettings>`.
+
 ----
 
 .. _class_InputMap_method_get_actions:

classes/class_line2d.rst

@@ -16,7 +16,7 @@ A 2D line.
 Description
 -----------
 
-A line through several points in 2D space.
+A line through several points in 2D space. Supports varying width and color over the line's length, texturing, and several cap/joint types.
 
 **Note:** By default, Godot can only draw up to 4,096 polygon points at a time. To increase this limit, open the Project Settings and increase :ref:`ProjectSettings.rendering/limits/buffers/canvas_polygon_buffer_size_kb<class_ProjectSettings_property_rendering/limits/buffers/canvas_polygon_buffer_size_kb>` and :ref:`ProjectSettings.rendering/limits/buffers/canvas_polygon_index_buffer_size_kb<class_ProjectSettings_property_rendering/limits/buffers/canvas_polygon_index_buffer_size_kb>`.
 
@@ -145,9 +145,11 @@ Property Descriptions
 | *Getter*  | get_antialiased()      |
 +-----------+------------------------+
 
-If ``true``, the line's border will be anti-aliased.
+If ``true``, the line's border will attempt to perform antialiasing by drawing thin OpenGL smooth lines on the line's edges.
 
-**Note:** Line2D is not accelerated by batching when being anti-aliased.
+**Note:** Line2D is not accelerated by batching if :ref:`antialiased<class_Line2D_property_antialiased>` is ``true``.
+
+**Note:** Due to how it works, built-in antialiasing will not look correct for translucent lines and may not work on certain platforms. As a workaround, install the `Antialiased Line2D <https://github.com/godot-extended-libraries/godot-antialiased-line2d>`__ add-on then create an AntialiasedLine2D node. That node relies on a texture with custom mipmaps to perform antialiasing. 2D batching is also still supported with those antialiased lines.
 
 ----
 

classes/class_object.rst

@@ -316,7 +316,7 @@ Returns ``true`` if the object can translate strings. See :ref:`set_message_tran
 
 Connects a ``signal`` to a ``method`` on a ``target`` object. Pass optional ``binds`` to the call as an :ref:`Array<class_Array>` of parameters. These parameters will be passed to the method after any parameter used in the call to :ref:`emit_signal<class_Object_method_emit_signal>`. Use ``flags`` to set deferred or one-shot connections. See :ref:`ConnectFlags<enum_Object_ConnectFlags>` constants.
 
-A ``signal`` can only be connected once to a ``method``. It will throw an error if already connected, unless the signal was connected with :ref:`CONNECT_REFERENCE_COUNTED<class_Object_constant_CONNECT_REFERENCE_COUNTED>`. To avoid this, first, use :ref:`is_connected<class_Object_method_is_connected>` to check for existing connections.
+A ``signal`` can only be connected once to a ``method``. It will print an error if already connected, unless the signal was connected with :ref:`CONNECT_REFERENCE_COUNTED<class_Object_constant_CONNECT_REFERENCE_COUNTED>`. To avoid this, first, use :ref:`is_connected<class_Object_method_is_connected>` to check for existing connections.
 
 If the ``target`` is destroyed in the game's lifecycle, the connection will be lost.
 
@@ -345,7 +345,7 @@ An example of the relationship between ``binds`` passed to :ref:`connect<class_O
 
 Disconnects a ``signal`` from a ``method`` on the given ``target``.
 
-If you try to disconnect a connection that does not exist, the method will throw an error. Use :ref:`is_connected<class_Object_method_is_connected>` to ensure that the connection exists.
+If you try to disconnect a connection that does not exist, the method will print an error. Use :ref:`is_connected<class_Object_method_is_connected>` to ensure that the connection exists.
 
 ----
 

classes/class_packedscenegltf.rst

@@ -13,6 +13,11 @@ PackedSceneGLTF
 
 
 
+Description
+-----------
+
+**Note:** This class is only compiled in editor builds. Run-time glTF loading and saving is *not* available in exported projects. References to ``PackedSceneGLTF`` within a script will cause an error in an exported project.
+
 Properties
 ----------
 

classes/class_polygon2d.rst

@@ -95,7 +95,9 @@ Property Descriptions
 | *Getter*  | get_antialiased()      |
 +-----------+------------------------+
 
-If ``true``, polygon edges will be anti-aliased.
+If ``true``, attempts to perform antialiasing for polygon edges by drawing a thin OpenGL smooth line on the edges.
+
+**Note:** Due to how it works, built-in antialiasing will not look correct for translucent polygons and may not work on certain platforms. As a workaround, install the `Antialiased Line2D <https://github.com/godot-extended-libraries/godot-antialiased-line2d>`__ add-on then create an AntialiasedPolygon2D node. That node relies on a texture with custom mipmaps to perform antialiasing.
 
 ----
 

classes/class_proximitygroup.rst

@@ -11,12 +11,46 @@ ProximityGroup
 
 **Inherits:** :ref:`Spatial<class_Spatial>` **<** :ref:`Node<class_Node>` **<** :ref:`Object<class_Object>`
 
-General-purpose proximity detection node.
+General-purpose 3D proximity detection node.
 
 Description
 -----------
 
-General-purpose proximity detection node.
+General-purpose proximity detection node. ``ProximityGroup`` can be used for *approximate* distance checks, which are faster than exact distance checks using :ref:`Vector3.distance_to<class_Vector3_method_distance_to>` or :ref:`Vector3.distance_squared_to<class_Vector3_method_distance_squared_to>`.
+
+``ProximityGroup`` nodes are automatically grouped together, as long as they share the same :ref:`group_name<class_ProximityGroup_property_group_name>` and intersect with each other. By calling the :ref:`broadcast<class_ProximityGroup_method_broadcast>`, you can invoke a specified method with various parameters to all intersecting members.
+
+``ProximityGroup`` is cuboid-shaped and consists of a cluster of :ref:`Vector3<class_Vector3>` coordinates. The coordinates are automatically calculated by calling :ref:`grid_radius<class_ProximityGroup_property_grid_radius>`. To allow ``ProximityGroup`` to find its peers (and perform automatic grouping), you need to define its :ref:`group_name<class_ProximityGroup_property_group_name>` to a non-empty :ref:`String<class_String>`. As soon as this object's shape intersects with another ``ProximityGroup`` object' shape, and both share the same :ref:`group_name<class_ProximityGroup_property_group_name>`, they will belong together for as long as they intersect.
+
+Since ``ProximityGroup`` doesn't rely the physics engine, you don't need to add any other node as a child (unlike :ref:`PhysicsBody<class_PhysicsBody>`).
+
+The ``ProximityGroup`` uses the :ref:`SceneTree<class_SceneTree>` groups in the background by calling the method :ref:`Node.add_to_group<class_Node_method_add_to_group>` internally. The :ref:`SceneTree<class_SceneTree>` group names are constructed by combining the :ref:`group_name<class_ProximityGroup_property_group_name>` with its coordinates, which are calculated using the :ref:`grid_radius<class_ProximityGroup_property_grid_radius>` you defined beforehand.
+
+**Example:** A ``ProximityGroup`` node named ``"PlanetEarth"`` at position ``Vector3(6, 6, 6)`` with a :ref:`group_name<class_ProximityGroup_property_group_name>` set to ``"planets"`` and a :ref:`grid_radius<class_ProximityGroup_property_grid_radius>` of ``Vector3(1, 2, 3)`` will create the following :ref:`SceneTree<class_SceneTree>` group names:
+
+::
+
+    - "planets|5|4|3"
+    - "planets|5|4|4"
+    - "planets|5|4|5"
+    - "planets|5|4|6"
+    - "planets|5|4|7"
+    - "planets|5|4|8"
+    - "planets|5|4|9"
+    - ...
+
+If there is another ``ProximityGroup`` named ``"PlanetMars"`` with group name ``"planets"``, and one of its coordinates is ``Vector3(5, 4, 7)``, it would normally create the :ref:`SceneTree<class_SceneTree>` group called ``"planets|5|4|7"``. However, since this group name already exists, this ``ProximityGroup`` object will be *added* to the existing one. ``"PlanetEarth"`` is already in this group. As long as both nodes don't change their transform and stop intersecting (or exit the scene tree), they are grouped together. As long as this intersection exists, any call to :ref:`broadcast<class_ProximityGroup_method_broadcast>` will affect *both* ``ProximityGroup`` nodes.
+
+There are 3 caveats to keep in mind when using ``ProximityGroup``:
+
+- The larger the grid radius, the more coordinates and the more :ref:`SceneTree<class_SceneTree>` groups are created. This can have a performance impact if too many groups are created.
+
+- If the ``ProximityGroup`` node is transformed in any way (or is removed from the scene tree), the groupings will have to be recalculated. This can also have a performance impact.
+
+- If your :ref:`grid_radius<class_ProximityGroup_property_grid_radius>` is smaller than ``Vector3(1, 1, 1)``, it will be rounded up to ``Vector3(1, 1, 1)``. Therefore, small grid radius values may lead to unwanted groupings.
+
+
+**Note:** ``ProximityGroup`` will be removed in Godot 4.0 in favor of more effective and faster :ref:`VisibilityNotifier<class_VisibilityNotifier>` functionality. For most use cases, :ref:`Vector3.distance_to<class_Vector3_method_distance_to>` or :ref:`Vector3.distance_squared_to<class_Vector3_method_distance_squared_to>` are fast enough too, especially if you call them less often using a :ref:`Timer<class_Timer>` node.
 
 Properties
 ----------
@@ -43,6 +77,12 @@ Signals
 
 - **broadcast** **(** :ref:`String<class_String>` method, :ref:`Array<class_Array>` parameters **)**
 
+Emitted when the user calls the :ref:`broadcast<class_ProximityGroup_method_broadcast>` method and has set :ref:`dispatch_mode<class_ProximityGroup_property_dispatch_mode>` to :ref:`MODE_SIGNAL<class_ProximityGroup_constant_MODE_SIGNAL>`.
+
+The given method and its parameters are passed on to the listeners who connected to this signal of this object, as well as any ``ProximityGroup`` node this node is grouped together with.
+
+**Note:** This signal is *not* emitted by default, as the default :ref:`dispatch_mode<class_ProximityGroup_property_dispatch_mode>` is :ref:`MODE_PROXY<class_ProximityGroup_constant_MODE_PROXY>`.
+
 Enumerations
 ------------
 
@@ -54,9 +94,9 @@ Enumerations
 
 enum **DispatchMode**:
 
-- **MODE_PROXY** = **0**
+- **MODE_PROXY** = **0** --- This ``ProximityGroup``'s parent will be target of :ref:`broadcast<class_ProximityGroup_method_broadcast>`.
 
-- **MODE_SIGNAL** = **1**
+- **MODE_SIGNAL** = **1** --- This ``ProximityGroup`` will emit the :ref:`broadcast<class_ProximityGroup_signal_broadcast>` *signal* when calling the :ref:`broadcast<class_ProximityGroup_method_broadcast>` *method*.
 
 Property Descriptions
 ---------------------
@@ -73,6 +113,8 @@ Property Descriptions
 | *Getter*  | get_dispatch_mode()      |
 +-----------+--------------------------+
 
+Specifies which node gets contacted on a call of method :ref:`broadcast<class_ProximityGroup_method_broadcast>`.
+
 ----
 
 .. _class_ProximityGroup_property_grid_radius:
@@ -87,6 +129,8 @@ Property Descriptions
 | *Getter*  | get_grid_radius()      |
 +-----------+------------------------+
 
+The size of the space in 3D units. This also sets the amount of coordinates required to calculate whether two ``ProximityGroup`` nodes are intersecting or not. Smaller :ref:`grid_radius<class_ProximityGroup_property_grid_radius>` values can be used for more precise proximity checks at the cost of performance, since more groups will be created.
+
 ----
 
 .. _class_ProximityGroup_property_group_name:
@@ -101,6 +145,10 @@ Property Descriptions
 | *Getter*  | get_group_name()      |
 +-----------+-----------------------+
 
+Specify the common group name, to let other ``ProximityGroup`` nodes know, if they should be auto-grouped with this node in case they intersect with each other.
+
+For example, if you have a ``ProximityGroup`` node named ``"Earth"`` and another called ``"Mars"``, with both nodes having ``"planet"`` as their :ref:`group_name<class_ProximityGroup_property_group_name>`. Give both planets a significantly larger :ref:`grid_radius<class_ProximityGroup_property_grid_radius>` than their actual radius, position them close enough and they'll be automatically grouped.
+
 Method Descriptions
 -------------------
 
@@ -108,6 +156,10 @@ Method Descriptions
 
 - void **broadcast** **(** :ref:`String<class_String>` method, :ref:`Variant<class_Variant>` parameters **)**
 
+Calls on all intersecting ``ProximityGroup`` the given method and parameters.
+
+If the :ref:`dispatch_mode<class_ProximityGroup_property_dispatch_mode>` is set to :ref:`MODE_PROXY<class_ProximityGroup_constant_MODE_PROXY>` (the default), all calls are delegated to their respective parent :ref:`Node<class_Node>`.
+
 .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
 .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
 .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`

classes/class_tree.rst

@@ -585,7 +585,7 @@ Returns the currently edited item. Can be used with :ref:`item_edited<class_Tree
 ::
 
     func _ready():
-        $Tree.item_edited.connect(on_Tree_item_edited)
+        $Tree.connect("item_edited", self, "on_Tree_item_edited")
     
     func on_Tree_item_edited():
         print($Tree.get_edited()) # This item just got edited (e.g. checked).

classes/class_vector2.rst

@@ -228,7 +228,7 @@ Returns the angle to the given vector, in radians.
 
 Returns the angle between the line connecting the two points and the X axis, in radians.
 
-`Illustration of the returned angle. <https://raw.githubusercontent.com/godotengine/godot-docs/master/img/vector2_angle_to_point.png>`__
+`Illustration of the returned angle. <https://raw.githubusercontent.com/godotengine/godot-docs/3.4/img/vector2_angle_to_point.png>`__
 
 ----
 

classes/class_visualserver.rst

@@ -1891,15 +1891,17 @@ enum **EnvironmentGlowBlendMode**:
 
 enum **EnvironmentToneMapper**:
 
-- **ENV_TONE_MAPPER_LINEAR** = **0** --- Output color as they came in.
+- **ENV_TONE_MAPPER_LINEAR** = **0** --- Output color as they came in. This can cause bright lighting to look blown out, with noticeable clipping in the output colors.
 
-- **ENV_TONE_MAPPER_REINHARD** = **1** --- Use the Reinhard tonemapper.
+- **ENV_TONE_MAPPER_REINHARD** = **1** --- Use the Reinhard tonemapper. Performs a variation on rendered pixels' colors by this formula: ``color = color / (1 + color)``. This avoids clipping bright highlights, but the resulting image can look a bit dull.
 
-- **ENV_TONE_MAPPER_FILMIC** = **2** --- Use the filmic tonemapper.
+- **ENV_TONE_MAPPER_FILMIC** = **2** --- Use the filmic tonemapper. This avoids clipping bright highlights, with a resulting image that usually looks more vivid than :ref:`ENV_TONE_MAPPER_REINHARD<class_VisualServer_constant_ENV_TONE_MAPPER_REINHARD>`.
 
-- **ENV_TONE_MAPPER_ACES** = **3** --- Use the ACES tonemapper.
+- **ENV_TONE_MAPPER_ACES** = **3** --- Use the legacy Godot version of the Academy Color Encoding System tonemapper. Unlike :ref:`ENV_TONE_MAPPER_ACES_FITTED<class_VisualServer_constant_ENV_TONE_MAPPER_ACES_FITTED>`, this version of ACES does not handle bright lighting in a physically accurate way. ACES typically has a more contrasted output compared to :ref:`ENV_TONE_MAPPER_REINHARD<class_VisualServer_constant_ENV_TONE_MAPPER_REINHARD>` and :ref:`ENV_TONE_MAPPER_FILMIC<class_VisualServer_constant_ENV_TONE_MAPPER_FILMIC>`.
 
-- **ENV_TONE_MAPPER_ACES_FITTED** = **4** --- Use the ACES Fitted tonemapper.
+**Note:** This tonemapping operator will be removed in Godot 4.0 in favor of the more accurate :ref:`ENV_TONE_MAPPER_ACES_FITTED<class_VisualServer_constant_ENV_TONE_MAPPER_ACES_FITTED>`.
+
+- **ENV_TONE_MAPPER_ACES_FITTED** = **4** --- Use the Academy Color Encoding System tonemapper. ACES is slightly more expensive than other options, but it handles bright lighting in a more realistic fashion by desaturating it as it becomes brighter. ACES typically has a more contrasted output compared to :ref:`ENV_TONE_MAPPER_REINHARD<class_VisualServer_constant_ENV_TONE_MAPPER_REINHARD>` and :ref:`ENV_TONE_MAPPER_FILMIC<class_VisualServer_constant_ENV_TONE_MAPPER_FILMIC>`.
 
 ----