From 81e075818ef8d961c65732d59e2b28c39f366806 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9mi=20Verschelde?= Date: Sun, 19 Jun 2022 14:17:53 +0200 Subject: [PATCH] classref: Sync with current 3.4 branch (716e4e0c2) --- classes/class_@gdscript.rst | 4 +++- classes/class_audioeffectcapture.rst | 2 +- classes/class_bakedlightmap.rst | 2 +- classes/class_camera.rst | 4 ++-- classes/class_canvasitem.rst | 2 +- classes/class_curvetexture.rst | 4 ++-- classes/class_dictionary.rst | 2 +- classes/class_geometry.rst | 4 ++-- classes/class_gradienttexture.rst | 2 +- classes/class_inputeventjoypadbutton.rst | 2 +- classes/class_node.rst | 8 ++++---- classes/class_os.rst | 4 ++++ classes/class_proximitygroup.rst | 1 - classes/class_rigidbody.rst | 4 ++-- classes/class_rigidbody2d.rst | 4 ++-- classes/class_shape2d.rst | 12 ++++++++++-- classes/class_visualserver.rst | 2 +- 17 files changed, 38 insertions(+), 25 deletions(-) diff --git a/classes/class_@gdscript.rst b/classes/class_@gdscript.rst index 9f09e3eef..7ee3e597f 100644 --- a/classes/class_@gdscript.rst +++ b/classes/class_@gdscript.rst @@ -1158,12 +1158,14 @@ Converts an angle expressed in radians to degrees. - :ref:`float` **rand_range** **(** :ref:`float` from, :ref:`float` to **)** -Random range, any floating point value between ``from`` and ``to``. +Returns a random floating point value between ``from`` and ``to`` (both endpoints inclusive). :: prints(rand_range(0, 1), rand_range(0, 1)) # Prints e.g. 0.135591 0.405263 +**Note:** This is equivalent to ``randf() * (to - from) + from``. + ---- .. _class_@GDScript_method_rand_seed: diff --git a/classes/class_audioeffectcapture.rst b/classes/class_audioeffectcapture.rst index 0385fd0eb..2544741d1 100644 --- a/classes/class_audioeffectcapture.rst +++ b/classes/class_audioeffectcapture.rst @@ -18,7 +18,7 @@ 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` and process it as needed, for example to capture data from a microphone, implement application defined effects, or to transmit audio over the network. +Application code should consume these audio frames from this ring buffer using :ref:`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. Properties ---------- diff --git a/classes/class_bakedlightmap.rst b/classes/class_bakedlightmap.rst index 2ed7766cd..0fc1a2a44 100644 --- a/classes/class_bakedlightmap.rst +++ b/classes/class_bakedlightmap.rst @@ -481,7 +481,7 @@ The calculated light data. | *Getter* | get_bake_quality() | +-----------+-------------------------+ -Determines the amount of samples per texel used in indrect light baking. The amount of samples for each quality level can be configured in the project settings. +Determines the amount of samples per texel used in indirect light baking. The amount of samples for each quality level can be configured in the project settings. ---- diff --git a/classes/class_camera.rst b/classes/class_camera.rst index 124bcec56..0a1f39562 100644 --- a/classes/class_camera.rst +++ b/classes/class_camera.rst @@ -444,7 +444,7 @@ Returns the 3D point in world space that maps to the given 2D coordinate in the - :ref:`Vector3` **project_ray_normal** **(** :ref:`Vector2` screen_point **)** |const| -Returns a normal vector in world space, that is the result of projecting a point on the :ref:`Viewport` rectangle by the camera projection. This is useful for casting rays in the form of (origin, normal) for object intersection or picking. +Returns a normal vector in world space, that is the result of projecting a point on the :ref:`Viewport` rectangle by the inverse camera projection. This is useful for casting rays in the form of (origin, normal) for object intersection or picking. ---- @@ -452,7 +452,7 @@ Returns a normal vector in world space, that is the result of projecting a point - :ref:`Vector3` **project_ray_origin** **(** :ref:`Vector2` screen_point **)** |const| -Returns a 3D position in world space, that is the result of projecting a point on the :ref:`Viewport` rectangle by the camera projection. This is useful for casting rays in the form of (origin, normal) for object intersection or picking. +Returns a 3D position in world space, that is the result of projecting a point on the :ref:`Viewport` rectangle by the inverse camera projection. This is useful for casting rays in the form of (origin, normal) for object intersection or picking. ---- diff --git a/classes/class_canvasitem.rst b/classes/class_canvasitem.rst index 594e17ea4..c85c71bda 100644 --- a/classes/class_canvasitem.rst +++ b/classes/class_canvasitem.rst @@ -400,7 +400,7 @@ Draws a string character using a custom font. Returns the advance, depending on - void **draw_circle** **(** :ref:`Vector2` position, :ref:`float` radius, :ref:`Color` color **)** -Draws a colored, unfilled circle. See also :ref:`draw_arc`, :ref:`draw_polyline` and :ref:`draw_polygon`. +Draws a colored, filled circle. See also :ref:`draw_arc`, :ref:`draw_polyline` and :ref:`draw_polygon`. **Note:** Built-in antialiasing is not provided for :ref:`draw_circle`. As a workaround, install the `Antialiased Line2D `__ add-on then create an AntialiasedRegularPolygon2D node. That node relies on a texture with custom mipmaps to perform antialiasing. diff --git a/classes/class_curvetexture.rst b/classes/class_curvetexture.rst index 88ccab02a..8a510b76e 100644 --- a/classes/class_curvetexture.rst +++ b/classes/class_curvetexture.rst @@ -40,7 +40,7 @@ Property Descriptions | *Getter* | get_curve() | +----------+------------------+ -The ``curve`` rendered onto the texture. +The :ref:`Curve` that is rendered onto the texture. ---- @@ -56,7 +56,7 @@ The ``curve`` rendered onto the texture. | *Getter* | get_width() | +-----------+------------------+ -The width of the texture. +The width of the texture (in pixels). Higher values make it possible to represent high-frequency data better (such as sudden direction changes), at the cost of increased generation time and memory usage. .. |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.)` diff --git a/classes/class_dictionary.rst b/classes/class_dictionary.rst index 1d013099c..f2c71f55a 100644 --- a/classes/class_dictionary.rst +++ b/classes/class_dictionary.rst @@ -49,7 +49,7 @@ You can access a dictionary's values by referencing the appropriate key. In the :: - export(string, "White", "Yellow", "Orange") var my_color + export(String, "White", "Yellow", "Orange") var my_color var points_dict = {"White": 50, "Yellow": 75, "Orange": 100} func _ready(): # We can't use dot syntax here as `my_color` is a variable. diff --git a/classes/class_geometry.rst b/classes/class_geometry.rst index 407cc8f5c..cd0aa2ba1 100644 --- a/classes/class_geometry.rst +++ b/classes/class_geometry.rst @@ -333,7 +333,7 @@ Returns ``true`` if ``polygon``'s vertices are ordered in clockwise order, other - :ref:`Variant` **line_intersects_line_2d** **(** :ref:`Vector2` from_a, :ref:`Vector2` dir_a, :ref:`Vector2` from_b, :ref:`Vector2` dir_b **)** -Checks if the two lines (``from_a``, ``dir_a``) and (``from_b``, ``dir_b``) intersect. If yes, return the point of intersection as :ref:`Vector2`. If no intersection takes place, returns an empty :ref:`Variant`. +Checks if the two lines (``from_a``, ``dir_a``) and (``from_b``, ``dir_b``) intersect. If yes, return the point of intersection as :ref:`Vector2`. If no intersection takes place, returns ``null``. **Note:** The lines are specified using direction vectors, not end points. @@ -436,7 +436,7 @@ Checks if the segment (``from``, ``to``) intersects the cylinder with height ``h - :ref:`Variant` **segment_intersects_segment_2d** **(** :ref:`Vector2` from_a, :ref:`Vector2` to_a, :ref:`Vector2` from_b, :ref:`Vector2` to_b **)** -Checks if the two segments (``from_a``, ``to_a``) and (``from_b``, ``to_b``) intersect. If yes, return the point of intersection as :ref:`Vector2`. If no intersection takes place, returns an empty :ref:`Variant`. +Checks if the two segments (``from_a``, ``to_a``) and (``from_b``, ``to_b``) intersect. If yes, return the point of intersection as :ref:`Vector2`. If no intersection takes place, returns ``null``. ---- diff --git a/classes/class_gradienttexture.rst b/classes/class_gradienttexture.rst index 849ae2c1f..8963523d4 100644 --- a/classes/class_gradienttexture.rst +++ b/classes/class_gradienttexture.rst @@ -16,7 +16,7 @@ Gradient-filled texture. Description ----------- -GradientTexture uses a :ref:`Gradient` to fill the texture data. The gradient will be filled from left to right using colors obtained from the gradient. This means the texture does not necessarily represent an exact copy of the gradient, but instead an interpolation of samples obtained from the gradient at fixed steps (see :ref:`width`). +GradientTexture uses a :ref:`Gradient` to fill the texture data. The gradient will be filled from left to right using colors obtained from the gradient. This means the texture does not necessarily represent an exact copy of the gradient, but instead an interpolation of samples obtained from the gradient at fixed steps (see :ref:`width`). See also :ref:`CurveTexture`. Properties ---------- diff --git a/classes/class_inputeventjoypadbutton.rst b/classes/class_inputeventjoypadbutton.rst index 315a0de87..4d5cfdafc 100644 --- a/classes/class_inputeventjoypadbutton.rst +++ b/classes/class_inputeventjoypadbutton.rst @@ -81,7 +81,7 @@ If ``true``, the button's state is pressed. If ``false``, the button's state is | *Getter* | get_pressure() | +-----------+---------------------+ -Represents the pressure the user puts on the button with his finger, if the controller supports it. Ranges from ``0`` to ``1``. +Represents the pressure the user puts on the button with their finger, if the controller supports it. Ranges from ``0`` to ``1``. .. |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.)` diff --git a/classes/class_node.rst b/classes/class_node.rst index 24b47a85d..4e624e7b5 100644 --- a/classes/class_node.rst +++ b/classes/class_node.rst @@ -1242,7 +1242,7 @@ Requests that ``_ready`` be called again. Note that the method won't be called i - :ref:`Variant` **rpc** **(** :ref:`String` method, ... **)** |vararg| -Sends a remote procedure call request for the given ``method`` to peers on the network (and locally), optionally sending all additional arguments as arguments to the method called by the RPC. The call request will only be received by nodes with the same :ref:`NodePath`, including the exact same node name. Behaviour depends on the RPC configuration for the given method, see :ref:`rpc_config`. Methods are not exposed to RPCs by default. See also :ref:`rset` and :ref:`rset_config` for properties. Returns an empty :ref:`Variant`. +Sends a remote procedure call request for the given ``method`` to peers on the network (and locally), optionally sending all additional arguments as arguments to the method called by the RPC. The call request will only be received by nodes with the same :ref:`NodePath`, including the exact same node name. Behaviour depends on the RPC configuration for the given method, see :ref:`rpc_config`. Methods are not exposed to RPCs by default. See also :ref:`rset` and :ref:`rset_config` for properties. Returns ``null``. **Note:** You can only safely use RPCs on clients after you received the ``connected_to_server`` signal from the :ref:`SceneTree`. You also need to keep track of the connection state, either by the :ref:`SceneTree` signals like ``server_disconnected`` or by checking ``SceneTree.network_peer.get_connection_status() == CONNECTION_CONNECTED``. @@ -1260,7 +1260,7 @@ Changes the RPC mode for the given ``method`` to the given ``mode``. See :ref:`R - :ref:`Variant` **rpc_id** **(** :ref:`int` peer_id, :ref:`String` method, ... **)** |vararg| -Sends a :ref:`rpc` to a specific peer identified by ``peer_id`` (see :ref:`NetworkedMultiplayerPeer.set_target_peer`). Returns an empty :ref:`Variant`. +Sends a :ref:`rpc` to a specific peer identified by ``peer_id`` (see :ref:`NetworkedMultiplayerPeer.set_target_peer`). Returns ``null``. ---- @@ -1268,7 +1268,7 @@ Sends a :ref:`rpc` to a specific peer identified by ``pee - :ref:`Variant` **rpc_unreliable** **(** :ref:`String` method, ... **)** |vararg| -Sends a :ref:`rpc` using an unreliable protocol. Returns an empty :ref:`Variant`. +Sends a :ref:`rpc` using an unreliable protocol. Returns ``null``. ---- @@ -1276,7 +1276,7 @@ Sends a :ref:`rpc` using an unreliable protocol. Returns - :ref:`Variant` **rpc_unreliable_id** **(** :ref:`int` peer_id, :ref:`String` method, ... **)** |vararg| -Sends a :ref:`rpc` to a specific peer identified by ``peer_id`` using an unreliable protocol (see :ref:`NetworkedMultiplayerPeer.set_target_peer`). Returns an empty :ref:`Variant`. +Sends a :ref:`rpc` to a specific peer identified by ``peer_id`` using an unreliable protocol (see :ref:`NetworkedMultiplayerPeer.set_target_peer`). Returns ``null``. ---- diff --git a/classes/class_os.rst b/classes/class_os.rst index 60bebf031..cb20d1e21 100644 --- a/classes/class_os.rst +++ b/classes/class_os.rst @@ -1104,6 +1104,10 @@ Here's a minimal example on how to parse command-line arguments into a dictionar if argument.find("=") > -1: var key_value = argument.split("=") arguments[key_value[0].lstrip("--")] = key_value[1] + else: + # Options without an argument will be present in the dictionary, + # with the value set to an empty string. + arguments[argument.lstrip("--")] = "" ---- diff --git a/classes/class_proximitygroup.rst b/classes/class_proximitygroup.rst index 9afe126ee..e2ade41bc 100644 --- a/classes/class_proximitygroup.rst +++ b/classes/class_proximitygroup.rst @@ -49,7 +49,6 @@ There are 3 caveats to keep in mind when using ``ProximityGroup``: - If your :ref:`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` functionality. For most use cases, :ref:`Vector3.distance_to` or :ref:`Vector3.distance_squared_to` are fast enough too, especially if you call them less often using a :ref:`Timer` node. Properties diff --git a/classes/class_rigidbody.rst b/classes/class_rigidbody.rst index 640906c9f..4f22bbea2 100644 --- a/classes/class_rigidbody.rst +++ b/classes/class_rigidbody.rst @@ -222,7 +222,7 @@ Property Descriptions | *Getter* | get_angular_damp() | +-----------+-------------------------+ -Damps RigidBody's rotational forces. +Damps RigidBody's rotational forces. If this value is different from -1.0 it will be added to any linear damp derived from the world or areas. See :ref:`ProjectSettings.physics/3d/default_angular_damp` for more details about damping. @@ -486,7 +486,7 @@ This is multiplied by the global 3D gravity setting found in **Project > Project | *Getter* | get_linear_damp() | +-----------+------------------------+ -The body's linear damp. Cannot be less than -1.0. If this value is different from -1.0, any linear damp derived from the world or areas will be overridden. +The body's linear damp. Cannot be less than -1.0. If this value is different from -1.0 it will be added to any linear damp derived from the world or areas. See :ref:`ProjectSettings.physics/3d/default_linear_damp` for more details about damping. diff --git a/classes/class_rigidbody2d.rst b/classes/class_rigidbody2d.rst index 9b90fbfaa..02dfc55ff 100644 --- a/classes/class_rigidbody2d.rst +++ b/classes/class_rigidbody2d.rst @@ -224,7 +224,7 @@ Property Descriptions | *Getter* | get_angular_damp() | +-----------+-------------------------+ -Damps the body's :ref:`angular_velocity`. If ``-1``, the body will use the **Default Angular Damp** defined in **Project > Project Settings > Physics > 2d**. +Damps the body's :ref:`angular_velocity`. If ``-1``, the body will use the **Default Angular Damp** defined in **Project > Project Settings > Physics > 2d**. If greater than ``-1`` it will be added to the default project value. See :ref:`ProjectSettings.physics/2d/default_angular_damp` for more details about damping. @@ -438,7 +438,7 @@ The body's moment of inertia. This is like mass, but for rotation: it determines | *Getter* | get_linear_damp() | +-----------+------------------------+ -Damps the body's :ref:`linear_velocity`. If ``-1``, the body will use the **Default Linear Damp** in **Project > Project Settings > Physics > 2d**. +Damps the body's :ref:`linear_velocity`. If ``-1``, the body will use the **Default Linear Damp** in **Project > Project Settings > Physics > 2d**. If greater than ``-1`` it will be added to the default project value. See :ref:`ProjectSettings.physics/2d/default_linear_damp` for more details about damping. diff --git a/classes/class_shape2d.rst b/classes/class_shape2d.rst index a238ea14b..6abf587af 100644 --- a/classes/class_shape2d.rst +++ b/classes/class_shape2d.rst @@ -81,7 +81,11 @@ This method needs the transformation matrix for this shape (``local_xform``), th - :ref:`Array` **collide_and_get_contacts** **(** :ref:`Transform2D` local_xform, :ref:`Shape2D` with_shape, :ref:`Transform2D` shape_xform **)** -Returns a list of the points where this shape touches another. If there are no collisions the list is empty. +Returns a list of contact point pairs where this shape touches another. + +If there are no collisions, the returned list is empty. Otherwise, the returned list contains contact points arranged in pairs, with entries alternating between points on the boundary of this shape and points on the boundary of ``with_shape``. + +A collision pair A, B can be used to calculate the collision normal with ``(B - A).normalized()``, and the collision depth with ``(B - A).length()``. This information is typically used to separate shapes, particularly in collision solvers. This method needs the transformation matrix for this shape (``local_xform``), the shape to check collisions with (``with_shape``), and the transformation matrix of that shape (``shape_xform``). @@ -101,7 +105,11 @@ This method needs the transformation matrix for this shape (``local_xform``), th - :ref:`Array` **collide_with_motion_and_get_contacts** **(** :ref:`Transform2D` local_xform, :ref:`Vector2` local_motion, :ref:`Shape2D` with_shape, :ref:`Transform2D` shape_xform, :ref:`Vector2` shape_motion **)** -Returns a list of the points where this shape would touch another, if a given movement was applied. If there are no collisions the list is empty. +Returns a list of contact point pairs where this shape would touch another, if a given movement was applied. + +If there would be no collisions, the returned list is empty. Otherwise, the returned list contains contact points arranged in pairs, with entries alternating between points on the boundary of this shape and points on the boundary of ``with_shape``. + +A collision pair A, B can be used to calculate the collision normal with ``(B - A).normalized()``, and the collision depth with ``(B - A).length()``. This information is typically used to separate shapes, particularly in collision solvers. This method needs the transformation matrix for this shape (``local_xform``), the movement to test on this shape (``local_motion``), the shape to check collisions with (``with_shape``), the transformation matrix of that shape (``shape_xform``), and the movement to test onto the other object (``shape_motion``). diff --git a/classes/class_visualserver.rst b/classes/class_visualserver.rst index 2869f86bd..3dc7c941a 100644 --- a/classes/class_visualserver.rst +++ b/classes/class_visualserver.rst @@ -3678,7 +3678,7 @@ Returns the value of a certain material's parameter. - :ref:`Variant` **material_get_param_default** **(** :ref:`RID` material, :ref:`String` parameter **)** |const| -Returns the default value for the param if available. Otherwise returns an empty :ref:`Variant`. +Returns the default value for the param if available. Returns ``null`` otherwise. ----