From 89907d4f5951dd67da29874954821e8bda7580f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9mi=20Verschelde?= Date: Tue, 14 Feb 2023 19:48:22 +0100 Subject: [PATCH] classref: Sync with current master branch (8c7b98d45) --- classes/class_@gdscript.rst | 74 ++-- classes/class_@globalscope.rst | 25 +- classes/class_animationnodeanimation.rst | 4 +- classes/class_animationnodeoneshot.rst | 59 ++- ...lass_animationnodestatemachineplayback.rst | 6 +- ...ss_animationnodestatemachinetransition.rst | 11 +- classes/class_animationnodesync.rst | 4 +- classes/class_animationnodetimeseek.rst | 16 +- classes/class_animationnodetransition.rst | 37 ++ classes/class_animationrootnode.rst | 4 +- classes/class_animationtree.rst | 134 +++++- classes/class_area2d.rst | 2 +- classes/class_area3d.rst | 2 +- classes/class_basematerial3d.rst | 46 +- classes/class_camera2d.rst | 2 + classes/class_cameraattributesphysical.rst | 2 + classes/class_cameraattributespractical.rst | 4 + classes/class_canvasitem.rst | 2 + classes/class_canvaslayer.rst | 2 +- classes/class_characterbody2d.rst | 4 +- classes/class_codeedit.rst | 2 +- classes/class_color.rst | 16 +- classes/class_control.rst | 6 +- classes/class_cpuparticles3d.rst | 2 +- classes/class_decal.rst | 6 +- classes/class_directionallight2d.rst | 2 + classes/class_displayserver.rst | 12 +- classes/class_engine.rst | 32 +- classes/class_environment.rst | 20 +- classes/class_fileaccess.rst | 4 + classes/class_font.rst | 4 +- classes/class_fontvariation.rst | 2 +- classes/class_graphedit.rst | 2 + classes/class_graphnode.rst | 2 + classes/class_httprequest.rst | 3 +- classes/class_image.rst | 12 +- classes/class_light2d.rst | 6 +- classes/class_light3d.rst | 10 +- classes/class_marshalls.rst | 4 + classes/class_navigationserver2d.rst | 2 +- classes/class_navigationserver3d.rst | 2 +- classes/class_ninepatchrect.rst | 4 - classes/class_object.rst | 2 +- classes/class_omnilight3d.rst | 2 + classes/class_packetpeer.rst | 4 + classes/class_physicsdirectspacestate3d.rst | 4 +- classes/class_physicsserver2d.rst | 416 ++++++++++-------- classes/class_pointlight2d.rst | 2 +- classes/class_projectsettings.rst | 60 +-- classes/class_reflectionprobe.rst | 2 + classes/class_renderingdevice.rst | 10 +- classes/class_rigidbody2d.rst | 28 ++ classes/class_rigidbody3d.rst | 28 ++ classes/class_skeleton3d.rst | 2 +- classes/class_spotlight3d.rst | 2 + classes/class_streampeer.rst | 4 + classes/class_string.rst | 20 +- classes/class_stringname.rst | 24 +- classes/class_textedit.rst | 6 +- classes/class_texturelayered.rst | 2 +- classes/class_tilemap.rst | 40 +- classes/class_visibleonscreennotifier2d.rst | 2 + classes/class_visibleonscreennotifier3d.rst | 2 +- classes/class_voxelgi.rst | 2 + classes/class_websocketmultiplayerpeer.rst | 2 +- classes/class_window.rst | 4 + 66 files changed, 847 insertions(+), 418 deletions(-) diff --git a/classes/class_@gdscript.rst b/classes/class_@gdscript.rst index 5eb5ae93e..219db3556 100644 --- a/classes/class_@gdscript.rst +++ b/classes/class_@gdscript.rst @@ -17,7 +17,7 @@ Built-in GDScript functions. Description ----------- -A list of GDScript-specific utility functions accessed in any script. +A list of GDScript-specific utility functions and annotations accessible from any script. For the list of the global functions and constants see :ref:`@GlobalScope`. @@ -124,12 +124,14 @@ Annotations **@export** **(** **)** -Mark the following property as exported (editable in the Inspector dock and saved to disk). To control the type of the exported property use the type hint notation. +Mark the following property as exported (editable in the Inspector dock and saved to disk). To control the type of the exported property, use the type hint notation. :: + @export var string = "" @export var int_number = 5 @export var float_number: float = 5 + @export var image : Image .. rst-class:: classref-item-separator @@ -147,11 +149,11 @@ See also :ref:`@GlobalScope.PROPERTY_USAGE_CATEGORY` and :ref:`@export_subgroup` instead. +\ **Note:** Categories in the Inspector dock's list usually divide properties coming from different classes (Node, Node2D, Sprite, etc.). For better clarity, it's recommended to use :ref:`@export_group` and :ref:`@export_subgroup`, instead. .. rst-class:: classref-item-separator @@ -163,13 +165,13 @@ See also :ref:`@GlobalScope.PROPERTY_USAGE_CATEGORY` property without transparency (its alpha fixed as ``1.0``). +Export a :ref:`Color` property without allowing its transparency (:ref:`Color.a`) to be edited. See also :ref:`@GlobalScope.PROPERTY_HINT_COLOR_NO_ALPHA`. :: - @export_color_no_alpha var modulate_color: Color + @export_color_no_alpha var dye_color : Color .. rst-class:: classref-item-separator @@ -187,7 +189,7 @@ See also :ref:`@GlobalScope.PROPERTY_HINT_DIR` property as a path to a directory. The path can be picked from the entire filesystem. See :ref:`@export_dir` to limit it to the project folder and its subfolders. +Export a :ref:`String` property as an absolute path to a directory. The path can be picked from the entire filesystem. See :ref:`@export_dir` to limit it to the project folder and its subfolders. See also :ref:`@GlobalScope.PROPERTY_HINT_GLOBAL_DIR`. :: - @export_global_dir var sprite_folder: String + @export_global_dir var sprite_folder_path: String .. rst-class:: classref-item-separator @@ -438,7 +440,7 @@ See also :ref:`@GlobalScope.PROPERTY_HINT_GLOBAL_DIR` filter="", ... **)** |vararg| -Export a :ref:`String` property as a path to a file. The path can be picked from the entire filesystem. See :ref:`@export_file` to limit it to the project folder and its subfolders. +Export a :ref:`String` property as an absolute path to a file. The path can be picked from the entire filesystem. See :ref:`@export_file` to limit it to the project folder and its subfolders. If ``filter`` is provided, only matching files will be available for picking. @@ -446,8 +448,8 @@ See also :ref:`@GlobalScope.PROPERTY_HINT_GLOBAL_FILE`'s ready state change. Values for these properties are not assigned immediately upon the node's creation, and instead are computed and stored right before :ref:`Node._ready`. +Mark the following property as assigned when the :ref:`Node` is ready. Values for these properties are not assigned immediately when the node is initialized (:ref:`Object._init`), and instead are computed and stored right before :ref:`Node._ready`. :: @@ -712,7 +714,7 @@ Returns a :ref:`Color` constructed from red (``r8``), green (``g8`` :: - var red = Color8(255, 0, 0) # Same as Color(1, 0, 0) + var red = Color8(255, 0, 0) # Same as Color(1, 0, 0). var dark_blue = Color8(0, 0, 51) # Same as Color(0, 0, 0.2). var my_color = Color8(306, 255, 0, 102) # Same as Color(1.2, 1, 0, 0.4). @@ -736,10 +738,10 @@ An optional ``message`` can be shown in addition to the generic "Assertion faile # Imagine we always want speed to be between 0 and 20. var speed = -10 - assert(speed < 20) # True, the program will continue - assert(speed >= 0) # False, the program will stop - assert(speed >= 0 and speed < 20) # You can also combine the two conditional statements in one check - assert(speed < 20, "the speed limit is 20") # Show a message + assert(speed < 20) # True, the program will continue. + assert(speed >= 0) # False, the program will stop. + assert(speed >= 0 and speed < 20) # You can also combine the two conditional statements in one check. + assert(speed < 20, "the speed limit is 20") # Show a message. .. rst-class:: classref-item-separator @@ -886,7 +888,7 @@ Returns the length of the given Variant ``var``. The length can be the character Returns a :ref:`Resource` from the filesystem located at the absolute ``path``. Unless it's already referenced elsewhere (such as in another script or in the scene), the resource is loaded from disk on function call, which might cause a slight delay, especially when loading large scenes. To avoid unnecessary delays when loading something multiple times, either store the resource in a variable or use :ref:`preload`. -\ **Note:** Resource paths can be obtained by right-clicking on a resource in the FileSystem dock and choosing "Copy Path" or by dragging the file from the FileSystem dock into the script. +\ **Note:** Resource paths can be obtained by right-clicking on a resource in the FileSystem dock and choosing "Copy Path", or by dragging the file from the FileSystem dock into the current script. :: @@ -911,7 +913,7 @@ This function is a simplified version of :ref:`ResourceLoader.load` from the filesystem located at ``path``. During run-time, the resource is loaded when the script is being parsed. This function effectively acts as a reference to that resource. Note that this function requires ``path`` to be a constant :ref:`String`. If you want to load a resource from a dynamic/variable path, use :ref:`load`. -\ **Note:** Resource paths can be obtained by right clicking on a resource in the Assets Panel and choosing "Copy Path" or by dragging the file from the FileSystem dock into the script. +\ **Note:** Resource paths can be obtained by right-clicking on a resource in the Assets Panel and choosing "Copy Path", or by dragging the file from the FileSystem dock into the current script. :: diff --git a/classes/class_@globalscope.rst b/classes/class_@globalscope.rst index cbb09cdba..641533149 100644 --- a/classes/class_@globalscope.rst +++ b/classes/class_@globalscope.rst @@ -2351,7 +2351,7 @@ Command (on macOS) or Meta/Windows key mask. :ref:`KeyModifierMask` **KEY_MASK_CTRL** = ``268435456`` -Ctrl key mask. +Control key mask. .. _class_@GlobalScope_constant_KEY_MASK_KPAD: @@ -2417,7 +2417,7 @@ Middle mouse button. :ref:`MouseButton` **MOUSE_BUTTON_WHEEL_UP** = ``4`` -Mouse wheel up. +Mouse wheel scrolling up. .. _class_@GlobalScope_constant_MOUSE_BUTTON_WHEEL_DOWN: @@ -2425,7 +2425,7 @@ Mouse wheel up. :ref:`MouseButton` **MOUSE_BUTTON_WHEEL_DOWN** = ``5`` -Mouse wheel down. +Mouse wheel scrolling down. .. _class_@GlobalScope_constant_MOUSE_BUTTON_WHEEL_LEFT: @@ -3716,7 +3716,7 @@ Hints that a string property is a password, and every character is replaced with :ref:`PropertyHint` **PROPERTY_HINT_MAX** = ``37`` - +Represents the size of the :ref:`PropertyHint` enum. .. rst-class:: classref-item-separator @@ -3902,7 +3902,7 @@ When duplicating a resource with :ref:`Resource.duplicate` **PROPERTY_USAGE_HIGH_END_GFX** = ``2097152`` -The property is only shown in the editor if modern renderers are supported (GLES3 is excluded). +The property is only shown in the editor if modern renderers are supported (the Compatibility rendering method is excluded). .. _class_@GlobalScope_constant_PROPERTY_USAGE_NODE_PATH_FROM_SCENE_ROOT: @@ -6166,7 +6166,8 @@ In GDScript, this is the equivalent of the ``**`` operator. :: - pow(2, 5) # Returns 32 + pow(2, 5) # Returns 32.0 + pow(4, 1.5) # Returns 8.0 .. rst-class:: classref-item-separator @@ -6954,15 +6955,15 @@ Converts a formatted ``string`` that was returned by :ref:`var_to_str` **PLAY_MODE_FORWARD** = ``0`` - +Plays animation in forward direction. .. _class_AnimationNodeAnimation_constant_PLAY_MODE_BACKWARD: @@ -75,7 +75,7 @@ enum **PlayMode**: :ref:`PlayMode` **PLAY_MODE_BACKWARD** = ``1`` - +Plays animation in backward direction. .. rst-class:: classref-section-separator diff --git a/classes/class_animationnodeoneshot.rst b/classes/class_animationnodeoneshot.rst index ff915627c..8808ba8f1 100644 --- a/classes/class_animationnodeoneshot.rst +++ b/classes/class_animationnodeoneshot.rst @@ -21,6 +21,41 @@ Description A resource to add to an :ref:`AnimationNodeBlendTree`. This node will execute a sub-animation and return once it finishes. Blend times for fading in and out can be customized, as well as filters. +After setting the request and changing the animation playback, the one-shot node automatically clears the request on the next process frame by setting its ``request`` value to :ref:`ONE_SHOT_REQUEST_NONE`. + + +.. tabs:: + + .. code-tab:: gdscript + + # Play child animation connected to "shot" port. + animation_tree.set("parameters/OneShot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE) + # Alternative syntax (same result as above). + animation_tree["parameters/OneShot/request"] = AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE + + # Abort child animation connected to "shot" port. + animation_tree.set("parameters/OneShot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_ABORT) + # Alternative syntax (same result as above). + animation_tree["parameters/OneShot/request"] = AnimationNodeOneShot.ONE_SHOT_REQUEST_ABORT + + # Get current state (read-only). + animation_tree.get("parameters/OneShot/active")) + # Alternative syntax (same result as above). + animation_tree["parameters/OneShot/active"] + + .. code-tab:: csharp + + // Play child animation connected to "shot" port. + animationTree.Set("parameters/OneShot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE); + + // Abort child animation connected to "shot" port. + animationTree.Set("parameters/OneShot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_ABORT); + + // Get current state (read-only). + animationTree.Get("parameters/OneShot/active"); + + + .. rst-class:: classref-introduction-group Tutorials @@ -73,7 +108,7 @@ enum **OneShotRequest**: :ref:`OneShotRequest` **ONE_SHOT_REQUEST_NONE** = ``0`` - +The default state of the request. Nothing is done. .. _class_AnimationNodeOneShot_constant_ONE_SHOT_REQUEST_FIRE: @@ -81,7 +116,7 @@ enum **OneShotRequest**: :ref:`OneShotRequest` **ONE_SHOT_REQUEST_FIRE** = ``1`` - +The request to play the animation connected to "shot" port. .. _class_AnimationNodeOneShot_constant_ONE_SHOT_REQUEST_ABORT: @@ -89,7 +124,7 @@ enum **OneShotRequest**: :ref:`OneShotRequest` **ONE_SHOT_REQUEST_ABORT** = ``2`` - +The request to stop the animation connected to "shot" port. .. rst-class:: classref-item-separator @@ -107,7 +142,7 @@ enum **MixMode**: :ref:`MixMode` **MIX_MODE_BLEND** = ``0`` - +Blends two animations. See also :ref:`AnimationNodeBlend2`. .. _class_AnimationNodeOneShot_constant_MIX_MODE_ADD: @@ -115,7 +150,7 @@ enum **MixMode**: :ref:`MixMode` **MIX_MODE_ADD** = ``1`` - +Blends two animations additively. See also :ref:`AnimationNodeAdd2`. .. rst-class:: classref-section-separator @@ -139,6 +174,8 @@ Property Descriptions If ``true``, the sub-animation will restart automatically after finishing. +In other words, to start auto restarting, the animation must be played once with the :ref:`ONE_SHOT_REQUEST_FIRE` request. The :ref:`ONE_SHOT_REQUEST_ABORT` request stops the auto restarting, but it does not disable the :ref:`autorestart` itself. So, the :ref:`ONE_SHOT_REQUEST_FIRE` request will start auto restarting again. + .. rst-class:: classref-item-separator ---- @@ -188,9 +225,7 @@ If :ref:`autorestart` is ``true - void **set_fadein_time** **(** :ref:`float` value **)** - :ref:`float` **get_fadein_time** **(** **)** -.. container:: contribute - - There is currently no description for this property. Please help us by :ref:`contributing one `! +The fade-in duration. For example, setting this to ``1.0`` for a 5 second length animation will produce a crossfade that starts at 0 second and ends at 1 second during the animation. .. rst-class:: classref-item-separator @@ -207,9 +242,7 @@ If :ref:`autorestart` is ``true - void **set_fadeout_time** **(** :ref:`float` value **)** - :ref:`float` **get_fadeout_time** **(** **)** -.. container:: contribute - - There is currently no description for this property. Please help us by :ref:`contributing one `! +The fade-out duration. For example, setting this to ``1.0`` for a 5 second length animation will produce a crossfade that starts at 4 second and ends at 5 second during the animation. .. rst-class:: classref-item-separator @@ -226,9 +259,7 @@ If :ref:`autorestart` is ``true - void **set_mix_mode** **(** :ref:`MixMode` value **)** - :ref:`MixMode` **get_mix_mode** **(** **)** -.. container:: contribute - - There is currently no description for this property. Please help us by :ref:`contributing one `! +The blend type. .. |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_animationnodestatemachineplayback.rst b/classes/class_animationnodestatemachineplayback.rst index 85c1c9c49..7d07a380f 100644 --- a/classes/class_animationnodestatemachineplayback.rst +++ b/classes/class_animationnodestatemachineplayback.rst @@ -102,9 +102,9 @@ Method Descriptions :ref:`float` **get_current_length** **(** **)** |const| -.. container:: contribute +Returns the current state length. - There is currently no description for this method. Please help us by :ref:`contributing one `! +\ **Note:** It is possible that any :ref:`AnimationRootNode` can be nodes as well as animations. This means that there can be multiple animations within a single state. Which animation length has priority depends on the nodes connected inside it. Also, if a transition does not reset, the remaining length at that point will be returned. .. rst-class:: classref-item-separator @@ -118,6 +118,8 @@ Method Descriptions Returns the currently playing animation state. +\ **Note:** When using a cross-fade, the current state changes to the next state immediately after the cross-fade begins. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_animationnodestatemachinetransition.rst b/classes/class_animationnodestatemachinetransition.rst index 4799eda8e..d7fdca2eb 100644 --- a/classes/class_animationnodestatemachinetransition.rst +++ b/classes/class_animationnodestatemachinetransition.rst @@ -12,9 +12,16 @@ AnimationNodeStateMachineTransition **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -.. container:: contribute +A resource to connect each node to make a path for :ref:`AnimationNodeStateMachine`. - There is currently no description for this class. Please help us by :ref:`contributing one `! +.. rst-class:: classref-introduction-group + +Description +----------- + +The path generated when using :ref:`AnimationNodeStateMachinePlayback.travel` is limited to the nodes connected by **AnimationNodeStateMachineTransition**. + +You can set the timing and conditions of the transition in detail. .. rst-class:: classref-introduction-group diff --git a/classes/class_animationnodesync.rst b/classes/class_animationnodesync.rst index c7234cdc1..44eb8feb1 100644 --- a/classes/class_animationnodesync.rst +++ b/classes/class_animationnodesync.rst @@ -14,9 +14,7 @@ AnimationNodeSync **Inherited By:** :ref:`AnimationNodeAdd2`, :ref:`AnimationNodeAdd3`, :ref:`AnimationNodeBlend2`, :ref:`AnimationNodeBlend3`, :ref:`AnimationNodeOneShot`, :ref:`AnimationNodeTransition` -.. container:: contribute - - There is currently no description for this class. Please help us by :ref:`contributing one `! +The base class for :ref:`AnimationNode` which has more than two input ports and needs to synchronize them. .. rst-class:: classref-reftable-group diff --git a/classes/class_animationnodetimeseek.rst b/classes/class_animationnodetimeseek.rst index 6395035e2..698447494 100644 --- a/classes/class_animationnodetimeseek.rst +++ b/classes/class_animationnodetimeseek.rst @@ -19,7 +19,9 @@ A time-seeking animation node to be used with :ref:`AnimationTree` from the start or a certain playback position inside the :ref:`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``. +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` from the start or a certain playback position inside the :ref:`AnimationNodeBlendTree`. + +After setting the time and changing the animation playback, the time seek node automatically goes into sleep mode on the next process frame by setting its ``seek_request`` value to ``-1.0``. .. tabs:: @@ -27,22 +29,22 @@ This node can be used to cause a seek command to happen to any sub-children of t .. code-tab:: gdscript # Play child animation from the start. - animation_tree.set("parameters/Seek/seek_position", 0.0) + animation_tree.set("parameters/TimeSeek/seek_request", 0.0) # Alternative syntax (same result as above). - animation_tree["parameters/Seek/seek_position"] = 0.0 + animation_tree["parameters/TimeSeek/seek_request"] = 0.0 # Play child animation from 12 second timestamp. - animation_tree.set("parameters/Seek/seek_position", 12.0) + animation_tree.set("parameters/TimeSeek/seek_request", 12.0) # Alternative syntax (same result as above). - animation_tree["parameters/Seek/seek_position"] = 12.0 + animation_tree["parameters/TimeSeek/seek_request"] = 12.0 .. code-tab:: csharp // Play child animation from the start. - animationTree.Set("parameters/Seek/seek_position", 0.0); + animationTree.Set("parameters/TimeSeek/seek_request", 0.0); // Play child animation from 12 second timestamp. - animationTree.Set("parameters/Seek/seek_position", 12.0); + animationTree.Set("parameters/TimeSeek/seek_request", 12.0); diff --git a/classes/class_animationnodetransition.rst b/classes/class_animationnodetransition.rst index 1ddd011f2..23f44adcd 100644 --- a/classes/class_animationnodetransition.rst +++ b/classes/class_animationnodetransition.rst @@ -21,6 +21,43 @@ Description Simple state machine for cases which don't require a more advanced :ref:`AnimationNodeStateMachine`. Animations can be connected to the inputs and transition times can be specified. +After setting the request and changing the animation playback, the transition node automatically clears the request on the next process frame by setting its ``transition_request`` value to empty. + +\ **Note:** When using a cross-fade, ``current_state`` and ``current_index`` change to the next state immediately after the cross-fade begins. + + +.. tabs:: + + .. code-tab:: gdscript + + # Play child animation connected to "state_2" port. + animation_tree.set("parameters/Transition/transition_request", "state_2") + # Alternative syntax (same result as above). + animation_tree["parameters/Transition/transition_request"] = "state_2" + + # Get current state name (read-only). + animation_tree.get("parameters/Transition/current_state") + # Alternative syntax (same result as above). + animation_tree["parameters/Transition/current_state"] + + # Get current state index (read-only). + animation_tree.get("parameters/Transition/current_index")) + # Alternative syntax (same result as above). + animation_tree["parameters/Transition/current_index"] + + .. code-tab:: csharp + + // Play child animation connected to "state_2" port. + animationTree.Set("parameters/Transition/transition_request", "state_2"); + + // Get current state name (read-only). + animationTree.Get("parameters/Transition/current_state"); + + // Get current state index (read-only). + animationTree.Get("parameters/Transition/current_index"); + + + .. rst-class:: classref-introduction-group Tutorials diff --git a/classes/class_animationrootnode.rst b/classes/class_animationrootnode.rst index c85d0ec19..a38b11b19 100644 --- a/classes/class_animationrootnode.rst +++ b/classes/class_animationrootnode.rst @@ -14,9 +14,7 @@ AnimationRootNode **Inherited By:** :ref:`AnimationNodeAnimation`, :ref:`AnimationNodeBlendSpace1D`, :ref:`AnimationNodeBlendSpace2D`, :ref:`AnimationNodeBlendTree`, :ref:`AnimationNodeStateMachine` -.. container:: contribute - - There is currently no description for this class. Please help us by :ref:`contributing one `! +The :ref:`AnimationNode` which can be set as the root of an :ref:`AnimationTree`. .. |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_animationtree.rst b/classes/class_animationtree.rst index 9d1d40f16..c819fb865 100644 --- a/classes/class_animationtree.rst +++ b/classes/class_animationtree.rst @@ -71,10 +71,16 @@ Methods +-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector3` | :ref:`get_root_motion_position` **(** **)** |const| | +-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`get_root_motion_position_accumulator` **(** **)** |const| | + +-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Quaternion` | :ref:`get_root_motion_rotation` **(** **)** |const| | +-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Quaternion` | :ref:`get_root_motion_rotation_accumulator` **(** **)** |const| | + +-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector3` | :ref:`get_root_motion_scale` **(** **)** |const| | +-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`get_root_motion_scale_accumulator` **(** **)** |const| | + +-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -327,7 +333,7 @@ Manually advance the animations by the specified time (in seconds). :ref:`Vector3` **get_root_motion_position** **(** **)** |const| -Retrieve the motion of position with the :ref:`root_motion_track` as a :ref:`Vector3` that can be used elsewhere. +Retrieve the motion delta of position with the :ref:`root_motion_track` as a :ref:`Vector3` that can be used elsewhere. If :ref:`root_motion_track` is not a path to a track of type :ref:`Animation.TYPE_POSITION_3D`, returns ``Vector3(0, 0, 0)``. @@ -352,6 +358,58 @@ The most basic example is applying position to :ref:`CharacterBody3D`, you can apply the root motion position more correctly to account for the rotation of the node. + + +.. tabs:: + + .. code-tab:: gdscript + + func _process(delta): + if Input.is_action_just_pressed("animate"): + state_machine.travel("Animate") + set_quaternion(get_quaternion() * animation_tree.get_root_motion_rotation()) + var velocity: Vector3 = (animation_tree.get_root_motion_rotation_accumulator().inverse() * get_quaternion()) * animation_tree.get_root_motion_position() / delta + set_velocity(velocity) + move_and_slide() + + + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationTree_method_get_root_motion_position_accumulator: + +.. rst-class:: classref-method + +:ref:`Vector3` **get_root_motion_position_accumulator** **(** **)** |const| + +Retrieve the blended value of the position tracks with the :ref:`root_motion_track` as a :ref:`Vector3` that can be used elsewhere. + +This is useful in cases where you want to respect the initial key values of the animation. + +For example, if an animation with only one key ``Vector3(0, 0, 0)`` is played in the previous frame and then an animation with only one key ``Vector3(1, 0, 1)`` is played in the next frame, the difference can be calculated as follows: + + +.. tabs:: + + .. code-tab:: gdscript + + var prev_root_motion_position_accumulator: Vector3 + + func _process(delta): + if Input.is_action_just_pressed("animate"): + state_machine.travel("Animate") + var current_root_motion_position_accumulator: Vector3 = animation_tree.get_root_motion_position_accumulator() + var difference: Vector3 = current_root_motion_position_accumulator - prev_root_motion_position_accumulator + prev_root_motion_position_accumulator = current_root_motion_position_accumulator + transform.origin += difference + + + +However, if the animation loops, an unintended discrete change may occur, so this is only useful for some simple use cases. + .. rst-class:: classref-item-separator ---- @@ -362,7 +420,7 @@ The most basic example is applying position to :ref:`CharacterBody3D` **get_root_motion_rotation** **(** **)** |const| -Retrieve the motion of rotation with the :ref:`root_motion_track` as a :ref:`Quaternion` that can be used elsewhere. +Retrieve the motion delta of rotation with the :ref:`root_motion_track` as a :ref:`Quaternion` that can be used elsewhere. If :ref:`root_motion_track` is not a path to a track of type :ref:`Animation.TYPE_ROTATION_3D`, returns ``Quaternion(0, 0, 0, 1)``. @@ -382,6 +440,43 @@ The most basic example is applying rotation to :ref:`CharacterBody3D` **get_root_motion_rotation_accumulator** **(** **)** |const| + +Retrieve the blended value of the rotation tracks with the :ref:`root_motion_track` as a :ref:`Quaternion` that can be used elsewhere. + +This is necessary to apply the root motion position correctly, taking rotation into account. See also :ref:`get_root_motion_position`. + +Also, this is useful in cases where you want to respect the initial key values of the animation. + +For example, if an animation with only one key ``Quaternion(0, 0, 0, 1)`` is played in the previous frame and then an animation with only one key ``Quaternion(0, 0.707, 0, 0.707)`` is played in the next frame, the difference can be calculated as follows: + + +.. tabs:: + + .. code-tab:: gdscript + + var prev_root_motion_rotation_accumulator: Quaternion + + func _process(delta): + if Input.is_action_just_pressed("animate"): + state_machine.travel("Animate") + var current_root_motion_rotation_accumulator: Quaternion = animation_tree.get_root_motion_Quaternion_accumulator() + var difference: Quaternion = prev_root_motion_rotation_accumulator.inverse() * current_root_motion_rotation_accumulator + prev_root_motion_rotation_accumulator = current_root_motion_rotation_accumulator + transform.basis *= difference + + + +However, if the animation loops, an unintended discrete change may occur, so this is only useful for some simple use cases. + .. rst-class:: classref-item-separator ---- @@ -392,7 +487,7 @@ The most basic example is applying rotation to :ref:`CharacterBody3D` **get_root_motion_scale** **(** **)** |const| -Retrieve the motion of scale with the :ref:`root_motion_track` as a :ref:`Vector3` that can be used elsewhere. +Retrieve the motion delta of scale with the :ref:`root_motion_track` as a :ref:`Vector3` that can be used elsewhere. If :ref:`root_motion_track` is not a path to a track of type :ref:`Animation.TYPE_SCALE_3D`, returns ``Vector3(0, 0, 0)``. @@ -418,6 +513,39 @@ The most basic example is applying scale to :ref:`CharacterBody3D` **get_root_motion_scale_accumulator** **(** **)** |const| + +Retrieve the blended value of the scale tracks with the :ref:`root_motion_track` as a :ref:`Vector3` that can be used elsewhere. + +For example, if an animation with only one key ``Vector3(1, 1, 1)`` is played in the previous frame and then an animation with only one key ``Vector3(2, 2, 2)`` is played in the next frame, the difference can be calculated as follows: + + +.. tabs:: + + .. code-tab:: gdscript + + var prev_root_motion_scale_accumulator: Vector3 + + func _process(delta): + if Input.is_action_just_pressed("animate"): + state_machine.travel("Animate") + var current_root_motion_scale_accumulator: Vector3 = animation_tree.get_root_motion_scale_accumulator() + var difference: Vector3 = current_root_motion_scale_accumulator - prev_root_motion_scale_accumulator + prev_root_motion_scale_accumulator = current_root_motion_scale_accumulator + transform.basis = transform.basis.scaled(difference) + + + +However, if the animation loops, an unintended discrete change may occur, so this is only useful for some simple use cases. + .. |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.)` diff --git a/classes/class_area2d.rst b/classes/class_area2d.rst index db9682540..c5408cd6e 100644 --- a/classes/class_area2d.rst +++ b/classes/class_area2d.rst @@ -12,7 +12,7 @@ Area2D **Inherits:** :ref:`CollisionObject2D` **<** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -2D area for detection and physics and audio influence. +2D area for detection, as well as physics and audio influence. .. rst-class:: classref-introduction-group diff --git a/classes/class_area3d.rst b/classes/class_area3d.rst index dcb4d1082..346dba0d9 100644 --- a/classes/class_area3d.rst +++ b/classes/class_area3d.rst @@ -12,7 +12,7 @@ Area3D **Inherits:** :ref:`CollisionObject3D` **<** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` -3D area for detection and physics and audio influence. +3D area for detection, as well as physics and audio influence. .. rst-class:: classref-introduction-group diff --git a/classes/class_basematerial3d.rst b/classes/class_basematerial3d.rst index 2b3acfb5a..77e498fc6 100644 --- a/classes/class_basematerial3d.rst +++ b/classes/class_basematerial3d.rst @@ -569,7 +569,7 @@ enum **Transparency**: :ref:`Transparency` **TRANSPARENCY_DISABLED** = ``0`` -The material will not use transparency. +The material will not use transparency. This is the fastest to render. .. _class_BaseMaterial3D_constant_TRANSPARENCY_ALPHA: @@ -577,7 +577,7 @@ The material will not use transparency. :ref:`Transparency` **TRANSPARENCY_ALPHA** = ``1`` -The material will use the texture's alpha values for transparency. +The material will use the texture's alpha values for transparency. This is the slowest to render, and disables shadow casting. .. _class_BaseMaterial3D_constant_TRANSPARENCY_ALPHA_SCISSOR: @@ -585,7 +585,7 @@ The material will use the texture's alpha values for transparency. :ref:`Transparency` **TRANSPARENCY_ALPHA_SCISSOR** = ``2`` -The material will cut off all values below a threshold, the rest will remain opaque. The opaque portions will be rendered in the depth prepass. +The material will cut off all values below a threshold, the rest will remain opaque. The opaque portions will be rendered in the depth prepass. This is faster to render than alpha blending, but slower than opaque rendering. This also supports casting shadows. .. _class_BaseMaterial3D_constant_TRANSPARENCY_ALPHA_HASH: @@ -593,7 +593,7 @@ The material will cut off all values below a threshold, the rest will remain opa :ref:`Transparency` **TRANSPARENCY_ALPHA_HASH** = ``3`` -The material will cut off all values below a spatially-deterministic threshold, the rest will remain opaque. +The material will cut off all values below a spatially-deterministic threshold, the rest will remain opaque. This is faster to render than alpha blending, but slower than opaque rendering. This also supports casting shadows. Alpha hashing is suited for hair rendering. .. _class_BaseMaterial3D_constant_TRANSPARENCY_ALPHA_DEPTH_PRE_PASS: @@ -601,7 +601,7 @@ The material will cut off all values below a spatially-deterministic threshold, :ref:`Transparency` **TRANSPARENCY_ALPHA_DEPTH_PRE_PASS** = ``4`` -The material will use the texture's alpha value for transparency, but will discard fragments with an alpha of less than 0.99 during the depth prepass and fragments with an alpha less than 0.1 during the shadow pass. +The material will use the texture's alpha value for transparency, but will discard fragments with an alpha of less than 0.99 during the depth prepass and fragments with an alpha less than 0.1 during the shadow pass. This also supports casting shadows. .. _class_BaseMaterial3D_constant_TRANSPARENCY_MAX: @@ -627,7 +627,7 @@ enum **ShadingMode**: :ref:`ShadingMode` **SHADING_MODE_UNSHADED** = ``0`` -The object will not receive shadows. +The object will not receive shadows. This is the fastest to render, but it disables all interactions with lights. .. _class_BaseMaterial3D_constant_SHADING_MODE_PER_PIXEL: @@ -635,7 +635,7 @@ The object will not receive shadows. :ref:`ShadingMode` **SHADING_MODE_PER_PIXEL** = ``1`` -The object will be shaded per pixel. Useful for realistic shading effect. +The object will be shaded per pixel. Useful for realistic shading effects. .. _class_BaseMaterial3D_constant_SHADING_MODE_PER_VERTEX: @@ -643,7 +643,7 @@ The object will be shaded per pixel. Useful for realistic shading effect. :ref:`ShadingMode` **SHADING_MODE_PER_VERTEX** = ``2`` -The object will be shaded per vertex. Useful when you want cheaper shaders and do not care about visual quality. +The object will be shaded per vertex. Useful when you want cheaper shaders and do not care about visual quality. Not implemented yet (this mode will act like :ref:`SHADING_MODE_PER_PIXEL`). .. _class_BaseMaterial3D_constant_SHADING_MODE_MAX: @@ -895,7 +895,7 @@ enum **CullMode**: :ref:`CullMode` **CULL_BACK** = ``0`` -Default cull mode. The back of the object is culled when not visible. Back face triangles will be culled when facing the camera. This results in only the front side of triangles being drawn. For closed-surface meshes this means that only the exterior of the mesh will be visible. +Default cull mode. The back of the object is culled when not visible. Back face triangles will be culled when facing the camera. This results in only the front side of triangles being drawn. For closed-surface meshes, this means that only the exterior of the mesh will be visible. .. _class_BaseMaterial3D_constant_CULL_FRONT: @@ -903,7 +903,7 @@ Default cull mode. The back of the object is culled when not visible. Back face :ref:`CullMode` **CULL_FRONT** = ``1`` -Front face triangles will be culled when facing the camera. This results in only the back side of triangles being drawn. For closed-surface meshes this means that the interior of the mesh will be drawn instead of the exterior. +Front face triangles will be culled when facing the camera. This results in only the back side of triangles being drawn. For closed-surface meshes, this means that the interior of the mesh will be drawn instead of the exterior. .. _class_BaseMaterial3D_constant_CULL_DISABLED: @@ -911,7 +911,7 @@ Front face triangles will be culled when facing the camera. This results in only :ref:`CullMode` **CULL_DISABLED** = ``2`` -No culling is performed. +No face culling is performed; both the front face and back face will be visible. .. rst-class:: classref-item-separator @@ -947,7 +947,7 @@ Set ``ALBEDO`` to the per-vertex color specified in the mesh. Vertex colors are considered to be stored in sRGB color space and are converted to linear color space during rendering. See also :ref:`vertex_color_is_srgb`. -\ **Note:** Only effective when using the Vulkan Clustered or Vulkan Mobile backends. +\ **Note:** Only effective when using the Forward+ and Mobile rendering methods. .. _class_BaseMaterial3D_constant_FLAG_USE_POINT_SIZE: @@ -1175,7 +1175,7 @@ Toon blob which changes size based on roughness. :ref:`SpecularMode` **SPECULAR_DISABLED** = ``2`` -No specular blob. +No specular blob. This is slightly faster to render than other specular modes. .. rst-class:: classref-item-separator @@ -1329,7 +1329,7 @@ Smoothly fades the object out based on each pixel's distance from the camera usi :ref:`DistanceFadeMode` **DISTANCE_FADE_PIXEL_DITHER** = ``2`` -Smoothly fades the object out based on each pixel's distance from the camera using a dither approach. Dithering discards pixels based on a set pattern to smoothly fade without enabling transparency. On certain hardware this can be faster than :ref:`DISTANCE_FADE_PIXEL_ALPHA`. +Smoothly fades the object out based on each pixel's distance from the camera using a dithering approach. Dithering discards pixels based on a set pattern to smoothly fade without enabling transparency. On certain hardware, this can be faster than :ref:`DISTANCE_FADE_PIXEL_ALPHA`. .. _class_BaseMaterial3D_constant_DISTANCE_FADE_OBJECT_DITHER: @@ -1337,7 +1337,7 @@ Smoothly fades the object out based on each pixel's distance from the camera usi :ref:`DistanceFadeMode` **DISTANCE_FADE_OBJECT_DITHER** = ``3`` -Smoothly fades the object out based on the object's distance from the camera using a dither approach. Dithering discards pixels based on a set pattern to smoothly fade without enabling transparency. On certain hardware this can be faster than :ref:`DISTANCE_FADE_PIXEL_ALPHA`. +Smoothly fades the object out based on the object's distance from the camera using a dithering approach. Dithering discards pixels based on a set pattern to smoothly fade without enabling transparency. On certain hardware, this can be faster than :ref:`DISTANCE_FADE_PIXEL_ALPHA` and :ref:`DISTANCE_FADE_PIXEL_DITHER`. .. rst-class:: classref-section-separator @@ -2201,7 +2201,9 @@ If ``true``, the object is rendered at the same size regardless of distance. - void **set_grow_enabled** **(** :ref:`bool` value **)** - :ref:`bool` **is_grow_enabled** **(** **)** -If ``true``, enables the vertex grow setting. See :ref:`grow_amount`. +If ``true``, enables the vertex grow setting. This can be used to create mesh-based outlines using a second material pass and its :ref:`cull_mode` set to :ref:`CULL_FRONT`. See also :ref:`grow_amount`. + +\ **Note:** Vertex growth cannot create new vertices, which means that visible gaps may occur in sharp corners. This can be alleviated by designing the mesh to use smooth normals exclusively using `face weighted normals `__ in the 3D authoring software. In this case, grow will be able to join every outline together, just like in the original mesh. .. rst-class:: classref-item-separator @@ -2218,7 +2220,7 @@ If ``true``, enables the vertex grow setting. See :ref:`grow_amount` value **)** - :ref:`float` **get_grow** **(** **)** -Grows object vertices in the direction of their normals. +Grows object vertices in the direction of their normals. Only effective if :ref:`grow` is ``true``. .. rst-class:: classref-item-separator @@ -2523,7 +2525,7 @@ If ``true``, depth testing is disabled and the object will be drawn in render or - void **set_feature** **(** :ref:`Feature` feature, :ref:`bool` enable **)** - :ref:`bool` **get_feature** **(** :ref:`Feature` feature **)** |const| -If ``true``, normal mapping is enabled. +If ``true``, normal mapping is enabled. This has a slight performance cost, especially on mobile GPUs. .. rst-class:: classref-item-separator @@ -2888,7 +2890,9 @@ Specifies the channel of the :ref:`roughness_texture` value **)** - :ref:`ShadingMode` **get_shading_mode** **(** **)** -Sets whether the shading takes place per-pixel or per-vertex. Per-vertex lighting is faster, making it the best choice for mobile applications, however it looks considerably worse than per-pixel. +Sets whether the shading takes place, per-pixel, per-vertex or unshaded. Per-vertex lighting is faster, making it the best choice for mobile applications, however it looks considerably worse than per-pixel. Unshaded rendering is the fastest, but disables all interactions with lights. + +\ **Note:** Setting the shading mode vertex shading currently has no effect, as vertex shading is not implemented yet. .. rst-class:: classref-item-separator @@ -3130,7 +3134,7 @@ Repeat flags for the texture. See :ref:`TextureFilter` value **)** - :ref:`Transparency` **get_transparency** **(** **)** -If ``true``, transparency is enabled on the body. See also :ref:`blend_mode`. +If ``true``, transparency is enabled on the body. Some transparency modes will disable shadow casting. Any transparency mode other than Disabled has a greater performance impact compared to opaque rendering. See also :ref:`blend_mode`. .. rst-class:: classref-item-separator @@ -3359,7 +3363,7 @@ If ``true``, triplanar mapping for ``UV2`` is calculated in world space rather t If ``true``, vertex colors are considered to be stored in sRGB color space and are converted to linear color space during rendering. If ``false``, vertex colors are considered to be stored in linear color space and are rendered as-is. See also :ref:`albedo_texture_force_srgb`. -\ **Note:** Only effective when using the Vulkan Clustered or Vulkan Mobile backends. +\ **Note:** Only effective when using the Forward+ and Mobile rendering methods, not Compatibility. .. rst-class:: classref-item-separator diff --git a/classes/class_camera2d.rst b/classes/class_camera2d.rst index 86260087f..52fee602f 100644 --- a/classes/class_camera2d.rst +++ b/classes/class_camera2d.rst @@ -667,6 +667,8 @@ The angular, asymptotic speed of the camera's rotation smoothing effect when :re The camera's zoom. A zoom of ``Vector(2, 2)`` doubles the size seen in the viewport. A zoom of ``Vector(0.5, 0.5)`` halves the size seen in the viewport. +\ **Note:** :ref:`FontFile.oversampling` does *not* take **Camera2D** zoom into account. This means that zooming in/out will cause bitmap fonts and rasterized (non-MSDF) dynamic fonts to appear blurry or pixelated unless the font is part of a :ref:`CanvasLayer` that makes it ignore camera zoom. To ensure text remains crisp regardless of zoom, you can enable MSDF font rendering by enabling :ref:`ProjectSettings.gui/theme/default_font_multichannel_signed_distance_field` (applies to the default project font only), or enabling **Multichannel Signed Distance Field** in the import options of a DynamicFont for custom fonts. On system fonts, :ref:`SystemFont.multichannel_signed_distance_field` can be enabled in the inspector. + .. rst-class:: classref-section-separator ---- diff --git a/classes/class_cameraattributesphysical.rst b/classes/class_cameraattributesphysical.rst index e75664258..a6f12a782 100644 --- a/classes/class_cameraattributesphysical.rst +++ b/classes/class_cameraattributesphysical.rst @@ -25,6 +25,8 @@ When used in a :ref:`WorldEnvironment` it provides defau The default settings are intended for use in an outdoor environment, tips for settings for use in an indoor environment can be found in each setting's documentation. +\ **Note:** Depth of field blur is only supported in the Forward+ and Mobile rendering methods, not Compatibility. + .. rst-class:: classref-reftable-group Properties diff --git a/classes/class_cameraattributespractical.rst b/classes/class_cameraattributespractical.rst index 25b0f2827..7ec62ac8d 100644 --- a/classes/class_cameraattributespractical.rst +++ b/classes/class_cameraattributespractical.rst @@ -141,6 +141,8 @@ Objects further from the :ref:`Camera3D` by this amount will be Enables depth of field blur for objects further than :ref:`dof_blur_far_distance`. Strength of blur is controlled by :ref:`dof_blur_amount` and modulated by :ref:`dof_blur_far_transition`. +\ **Note:** Depth of field blur is only supported in the Forward+ and Mobile rendering methods, not Compatibility. + .. rst-class:: classref-item-separator ---- @@ -192,6 +194,8 @@ Objects closer from the :ref:`Camera3D` by this amount will be b Enables depth of field blur for objects closer than :ref:`dof_blur_near_distance`. Strength of blur is controlled by :ref:`dof_blur_amount` and modulated by :ref:`dof_blur_near_transition`. +\ **Note:** Depth of field blur is only supported in the Forward+ and Mobile rendering methods, not Compatibility. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_canvasitem.rst b/classes/class_canvasitem.rst index 5af94b9d7..1b1e75c68 100644 --- a/classes/class_canvasitem.rst +++ b/classes/class_canvasitem.rst @@ -1091,6 +1091,8 @@ void **draw_set_transform** **(** :ref:`Vector2` position, :ref:` Sets a custom transform for drawing via components. Anything drawn afterwards will be transformed by this. +\ **Note:** :ref:`FontFile.oversampling` does *not* take ``scale`` into account. This means that scaling up/down will cause bitmap fonts and rasterized (non-MSDF) dynamic fonts to appear blurry or pixelated. To ensure text remains crisp regardless of scale, you can enable MSDF font rendering by enabling :ref:`ProjectSettings.gui/theme/default_font_multichannel_signed_distance_field` (applies to the default project font only), or enabling **Multichannel Signed Distance Field** in the import options of a DynamicFont for custom fonts. On system fonts, :ref:`SystemFont.multichannel_signed_distance_field` can be enabled in the inspector. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_canvaslayer.rst b/classes/class_canvaslayer.rst index e32004afd..dacd4239e 100644 --- a/classes/class_canvaslayer.rst +++ b/classes/class_canvaslayer.rst @@ -172,7 +172,7 @@ Scales the layer when using :ref:`follow_viewport_enabled` value **)** - :ref:`int` **get_layer** **(** **)** -Layer index for draw order. Lower values are drawn first. +Layer index for draw order. Lower values are drawn behind higher values. .. rst-class:: classref-item-separator diff --git a/classes/class_characterbody2d.rst b/classes/class_characterbody2d.rst index 37105409f..95552413f 100644 --- a/classes/class_characterbody2d.rst +++ b/classes/class_characterbody2d.rst @@ -573,10 +573,10 @@ Returns a :ref:`KinematicCollision2D`, which contain .. code-tab:: csharp - for (int i = 0; i < GetSlideCount(); i++) + for (int i = 0; i < GetSlideCollisionCount(); i++) { KinematicCollision2D collision = GetSlideCollision(i); - GD.Print("Collided with: ", (collision.Collider as Node).Name); + GD.Print("Collided with: ", (collision.GetCollider() as Node).Name); } diff --git a/classes/class_codeedit.rst b/classes/class_codeedit.rst index e20950c2a..3c872cdd2 100644 --- a/classes/class_codeedit.rst +++ b/classes/class_codeedit.rst @@ -777,7 +777,7 @@ Sets whether line folding is allowed. - void **set_line_length_guidelines** **(** :ref:`int[]` value **)** - :ref:`int[]` **get_line_length_guidelines** **(** **)** -Draws vertical lines at the provided columns. The first entry is considered a main hard guideline and is draw more prominently +Draws vertical lines at the provided columns. The first entry is considered a main hard guideline and is draw more prominently. .. rst-class:: classref-item-separator diff --git a/classes/class_color.rst b/classes/class_color.rst index f22e3cf51..b67e7d2e6 100644 --- a/classes/class_color.rst +++ b/classes/class_color.rst @@ -1791,7 +1791,7 @@ Returns the light intensity of the color, as a value between 0.0 and 1.0 (inclus :ref:`Color` **hex** **(** :ref:`int` hex **)** |static| -Returns the **Color** associated with the provided ``hex`` integer in 32-bit ARGB format (8 bits per channel, alpha channel first). +Returns the **Color** associated with the provided ``hex`` integer in 32-bit RGBA format (8 bits per channel, alpha channel first). In GDScript and C#, the :ref:`int` is best visualized with hexadecimal notation (``"0x"`` prefix). @@ -1800,15 +1800,15 @@ In GDScript and C#, the :ref:`int` is best visualized with hexadecima .. code-tab:: gdscript - var red = Color.hex(0xffff0000) - var dark_cyan = Color.hex(0xff008b8b) - var my_color = Color.hex(0xa4bbefd2) + var red = Color.hex(0xff0000ff) + var dark_cyan = Color.hex(0x008b8bff) + var my_color = Color.hex(0xbbefd2a4) .. code-tab:: csharp - var red = new Color(0xffff0000); - var dark_cyan = new Color(0xff008b8b); - var my_color = new Color(0xa4bbefd2); + var red = new Color(0xff0000ff); + var dark_cyan = new Color(0x008b8bff); + var my_color = new Color(0xbbefd2a4); @@ -1822,7 +1822,7 @@ In GDScript and C#, the :ref:`int` is best visualized with hexadecima :ref:`Color` **hex64** **(** :ref:`int` hex **)** |static| -Returns the **Color** associated with the provided ``hex`` integer in 64-bit ARGB format (16 bits per channel, alpha channel first). +Returns the **Color** associated with the provided ``hex`` integer in 64-bit RGBA format (16 bits per channel, alpha channel first). In GDScript and C#, the :ref:`int` is best visualized with hexadecimal notation (``"0x"`` prefix). diff --git a/classes/class_control.rst b/classes/class_control.rst index fa5729a3a..57dd8fb85 100644 --- a/classes/class_control.rst +++ b/classes/class_control.rst @@ -1685,7 +1685,9 @@ Helper property to access :ref:`rotation` in de The node's scale, relative to its :ref:`size`. Change this property to scale the node around its :ref:`pivot_offset`. The Control's :ref:`tooltip_text` will also scale according to this value. -\ **Note:** This property is mainly intended to be used for animation purposes. Text inside the Control will look pixelated or blurry when the Control is scaled. To support multiple resolutions in your project, use an appropriate viewport stretch mode as described in the :doc:`documentation <../tutorials/rendering/multiple_resolutions>` instead of scaling Controls individually. +\ **Note:** This property is mainly intended to be used for animation purposes. To support multiple resolutions in your project, use an appropriate viewport stretch mode as described in the :doc:`documentation <../tutorials/rendering/multiple_resolutions>` instead of scaling Controls individually. + +\ **Note:** :ref:`FontFile.oversampling` does *not* take **Control** :ref:`scale` into account. This means that scaling up/down will cause bitmap fonts and rasterized (non-MSDF) dynamic fonts to appear blurry or pixelated. To ensure text remains crisp regardless of scale, you can enable MSDF font rendering by enabling :ref:`ProjectSettings.gui/theme/default_font_multichannel_signed_distance_field` (applies to the default project font only), or enabling **Multichannel Signed Distance Field** in the import options of a DynamicFont for custom fonts. On system fonts, :ref:`SystemFont.multichannel_signed_distance_field` can be enabled in the inspector. \ **Note:** If the Control node is a child of a :ref:`Container` node, the scale will be reset to ``Vector2(1, 1)`` when the scene is instantiated. To set the Control's scale when it's instantiated, wait for one frame using ``await get_tree().process_frame`` then set its :ref:`scale` property. @@ -2726,7 +2728,7 @@ void **grab_focus** **(** **)** Steal the focus from another control and become the focused control (see :ref:`focus_mode`). -\ **Note**: Using this method together with :ref:`Callable.call_deferred` makes it more reliable, especially when called inside :ref:`Node._ready`. +\ **Note:** Using this method together with :ref:`Callable.call_deferred` makes it more reliable, especially when called inside :ref:`Node._ready`. .. rst-class:: classref-item-separator diff --git a/classes/class_cpuparticles3d.rst b/classes/class_cpuparticles3d.rst index ab0b33cb6..f81a8d11d 100644 --- a/classes/class_cpuparticles3d.rst +++ b/classes/class_cpuparticles3d.rst @@ -810,7 +810,7 @@ Maximum damping. - void **set_param_min** **(** :ref:`Parameter` param, :ref:`float` value **)** - :ref:`float` **get_param_min** **(** :ref:`Parameter` param **)** |const| -Minimum damping +Minimum damping. .. rst-class:: classref-item-separator diff --git a/classes/class_decal.rst b/classes/class_decal.rst index aaedc46db..c352d20e3 100644 --- a/classes/class_decal.rst +++ b/classes/class_decal.rst @@ -27,6 +27,8 @@ The :ref:`Texture2D`\ s associated with the Decal are automatic \ **Note:** Decals cannot affect an underlying material's transparency, regardless of its transparency mode (alpha blend, alpha scissor, alpha hash, opaque pre-pass). This means translucent or transparent areas of a material will remain translucent or transparent even if an opaque decal is applied on them. +\ **Note:** Decals are only supported in the Forward+ and Mobile rendering methods, not Compatibility. When using the Mobile rendering method, only 8 decals can be displayed on each mesh resource. Attempting to display more than 8 decals on a single mesh resource will result in decals flickering in and out as the camera moves. + \ **Note:** When using the Mobile rendering method, decals will only correctly affect meshes whose visibility AABB intersects with the decal's AABB. If using a shader to deform the mesh in a way that makes it go outside its AABB, :ref:`GeometryInstance3D.extra_cull_margin` must be increased on the mesh. Otherwise, the decal may not be visible on the mesh. .. rst-class:: classref-reftable-group @@ -313,7 +315,9 @@ Fades the Decal if the angle between the Decal's :ref:`AABB` and the - void **set_size** **(** :ref:`Vector3` value **)** - :ref:`Vector3` **get_size** **(** **)** -Sets the size of the :ref:`AABB` used by the decal. The AABB goes from ``-size/2`` to ``size/2``. +Sets the size of the :ref:`AABB` used by the decal. All dimensions must be set to a value greater than zero (they will be clamped to ``0.001`` if this is not the case). The AABB goes from ``-size/2`` to ``size/2``. + +\ **Note:** To improve culling efficiency of "hard surface" decals, set their :ref:`upper_fade` and :ref:`lower_fade` to ``0.0`` and set the Y component of the :ref:`size` as low as possible. This will reduce the decals' AABB size without affecting their appearance. .. rst-class:: classref-item-separator diff --git a/classes/class_directionallight2d.rst b/classes/class_directionallight2d.rst index 3909342d9..44ac10052 100644 --- a/classes/class_directionallight2d.rst +++ b/classes/class_directionallight2d.rst @@ -21,6 +21,8 @@ Description A directional light is a type of :ref:`Light2D` node that models an infinite number of parallel rays covering the entire scene. It is used for lights with strong intensity that are located far away from the scene (for example: to model sunlight or moonlight). +\ **Note:** **DirectionalLight2D** does not support light cull masks (but it supports shadow cull masks). It will always light up 2D nodes, regardless of the 2D node's :ref:`CanvasItem.light_mask`. + .. rst-class:: classref-introduction-group Tutorials diff --git a/classes/class_displayserver.rst b/classes/class_displayserver.rst index 6579ddbb1..938c0b02a 100644 --- a/classes/class_displayserver.rst +++ b/classes/class_displayserver.rst @@ -744,7 +744,7 @@ I-beam cursor shape. This is used by default when hovering a control that accept :ref:`CursorShape` **CURSOR_POINTING_HAND** = ``2`` -Pointing hand cursor shape. This is used by default when hovering a :ref:`LinkButton` or an URL tag in a :ref:`RichTextLabel`.⋅ +Pointing hand cursor shape. This is used by default when hovering a :ref:`LinkButton` or an URL tag in a :ref:`RichTextLabel`. .. _class_DisplayServer_constant_CURSOR_CROSS: @@ -1118,7 +1118,7 @@ enum **VSyncMode**: :ref:`VSyncMode` **VSYNC_DISABLED** = ``0`` -No vertical synchronization, which means the engine will display frames as fast as possible (tearing may be visible). Framerate is unlimited (nonwithstanding :ref:`Engine.max_fps`). +No vertical synchronization, which means the engine will display frames as fast as possible (tearing may be visible). Framerate is unlimited (nonwithstanding :ref:`Engine.max_fps`). Not supported when using the Compatibility rendering method. .. _class_DisplayServer_constant_VSYNC_ENABLED: @@ -1134,7 +1134,7 @@ Default vertical synchronization mode, the image is displayed only on vertical b :ref:`VSyncMode` **VSYNC_ADAPTIVE** = ``2`` -Behaves like :ref:`VSYNC_DISABLED` when the framerate drops below the screen's refresh rate to reduce stuttering (tearing may be visible). Otherwise, vertical synchronization is enabled to avoid tearing. Framerate is limited by the monitor refresh rate (nonwithstanding :ref:`Engine.max_fps`). +Behaves like :ref:`VSYNC_DISABLED` when the framerate drops below the screen's refresh rate to reduce stuttering (tearing may be visible). Otherwise, vertical synchronization is enabled to avoid tearing. Framerate is limited by the monitor refresh rate (nonwithstanding :ref:`Engine.max_fps`). Not supported when using the Compatibility rendering method. .. _class_DisplayServer_constant_VSYNC_MAILBOX: @@ -1144,7 +1144,7 @@ Behaves like :ref:`VSYNC_DISABLED` Displays the most recent image in the queue on vertical blanking intervals, while rendering to the other images (no tearing is visible). Framerate is unlimited (nonwithstanding :ref:`Engine.max_fps`). -Although not guaranteed, the images can be rendered as fast as possible, which may reduce input lag (also called "Fast" V-Sync mode). :ref:`VSYNC_MAILBOX` works best when at least twice as many frames as the display refresh rate are rendered. +Although not guaranteed, the images can be rendered as fast as possible, which may reduce input lag (also called "Fast" V-Sync mode). :ref:`VSYNC_MAILBOX` works best when at least twice as many frames as the display refresh rate are rendered. Not supported when using the Compatibility rendering method. .. rst-class:: classref-item-separator @@ -2263,7 +2263,7 @@ Sets number of state of an multistate item. See :ref:`global_menu_add_multistate void **global_menu_set_item_radio_checkable** **(** :ref:`String` menu_root, :ref:`int` idx, :ref:`bool` checkable **)** -Sets the type of the item at the specified index ``idx`` to radio button. If ``false``, sets the type of the item to plain text +Sets the type of the item at the specified index ``idx`` to radio button. If ``false``, sets the type of the item to plain text. \ **Note:** This is purely cosmetic; you must add the logic for checking/unchecking items in radio groups. @@ -3603,6 +3603,8 @@ See :ref:`VSyncMode` for possible values and how t Depending on the platform and used renderer, the engine will fall back to :ref:`VSYNC_ENABLED` if the desired mode is not supported. +\ **Note:** V-Sync modes other than :ref:`VSYNC_ENABLED` are only supported in the Forward+ and Mobile rendering methods, not Compatibility. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_engine.rst b/classes/class_engine.rst index aeeb2d579..b4c1b1209 100644 --- a/classes/class_engine.rst +++ b/classes/class_engine.rst @@ -94,10 +94,12 @@ Methods +---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_in_physics_frame` **(** **)** |const| | +---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | void | :ref:`register_script_language` **(** :ref:`ScriptLanguage` language **)** | + | :ref:`Error` | :ref:`register_script_language` **(** :ref:`ScriptLanguage` language **)** | +---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`register_singleton` **(** :ref:`StringName` name, :ref:`Object` instance **)** | +---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Error` | :ref:`unregister_script_language` **(** :ref:`ScriptLanguage` language **)** | + +---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`unregister_singleton` **(** :ref:`StringName` name **)** | +---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -644,10 +646,18 @@ Returns ``true`` if the game is inside the fixed process and physics phase of th .. rst-class:: classref-method -void **register_script_language** **(** :ref:`ScriptLanguage` language **)** +:ref:`Error` **register_script_language** **(** :ref:`ScriptLanguage` language **)** Registers a :ref:`ScriptLanguage` instance to be available with ``ScriptServer``. +Returns: + +- :ref:`@GlobalScope.OK` on success + +- :ref:`@GlobalScope.ERR_UNAVAILABLE` if ``ScriptServer`` has reached it limit and cannot register any new language + +- :ref:`@GlobalScope.ERR_ALREADY_EXISTS` if ``ScriptServer`` already contains a language with similar extension/name/type + .. rst-class:: classref-item-separator ---- @@ -664,6 +674,24 @@ Registers the given object as a singleton, globally available under ``name``. ---- +.. _class_Engine_method_unregister_script_language: + +.. rst-class:: classref-method + +:ref:`Error` **unregister_script_language** **(** :ref:`ScriptLanguage` language **)** + +Unregisters the :ref:`ScriptLanguage` instance from ``ScriptServer``. + +Returns: + +- :ref:`@GlobalScope.OK` on success + +- :ref:`@GlobalScope.ERR_DOES_NOT_EXIST` if the language is already not registered in ``ScriptServer`` + +.. rst-class:: classref-item-separator + +---- + .. _class_Engine_method_unregister_singleton: .. rst-class:: classref-method diff --git a/classes/class_environment.rst b/classes/class_environment.rst index 625bdcb1e..17744e725 100644 --- a/classes/class_environment.rst +++ b/classes/class_environment.rst @@ -604,6 +604,8 @@ The global contrast value of the rendered scene (default value is 1). Effective If ``true``, enables the ``adjustment_*`` properties provided by this resource. If ``false``, modifications to the ``adjustment_*`` properties will have no effect on the rendered scene. +\ **Note:** Adjustments are only supported in the Forward+ and Mobile rendering methods, not Compatibility. + .. rst-class:: classref-item-separator ---- @@ -1001,6 +1003,8 @@ The bloom's intensity. If set to a value higher than ``0``, this will make glow If ``true``, the glow effect is enabled. +\ **Note:** Glow is only supported in the Forward+ and Mobile rendering methods, not Compatibility. When using the Mobile rendering method, glow will look different due to the lower dynamic range available in the Mobile rendering method. + .. rst-class:: classref-item-separator ---- @@ -1050,7 +1054,7 @@ The bleed scale of the HDR glow. - void **set_glow_hdr_bleed_threshold** **(** :ref:`float` value **)** - :ref:`float` **get_glow_hdr_bleed_threshold** **(** **)** -The lower threshold of the HDR glow. When using the OpenGL renderer (which doesn't support HDR), this needs to be below ``1.0`` for glow to be visible. A value of ``0.9`` works well in this case. +The lower threshold of the HDR glow. When using the Mobile rendering method (which only supports a lower dynamic range up to ``2.0``), this may need to be below ``1.0`` for glow to be visible. A value of ``0.9`` works well in this case. This value also needs to be decreased below ``1.0`` when using glow in 2D, as 2D rendering is performed in SDR. .. rst-class:: classref-item-separator @@ -1067,7 +1071,7 @@ The lower threshold of the HDR glow. When using the OpenGL renderer (which doesn - void **set_glow_intensity** **(** :ref:`float` value **)** - :ref:`float` **get_glow_intensity** **(** **)** -The overall brightness multiplier of the glow effect. When using the OpenGL renderer, this should be increased to ``1.5`` to compensate for the lack of HDR rendering. +The overall brightness multiplier of the glow effect. When using the Mobile rendering method (which only supports a lower dynamic range up to ``2.0``), this should be increased to ``1.5`` to compensate. .. rst-class:: classref-item-separator @@ -1273,7 +1277,7 @@ If ``true``, glow levels will be normalized so that summed together their intens - void **set_glow_strength** **(** :ref:`float` value **)** - :ref:`float` **get_glow_strength** **(** **)** -The strength of the glow effect. This applies as the glow is blurred across the screen and increases the distance and intensity of the blur. When using the OpenGL renderer, this should be increased to 1.3 to compensate for the lack of HDR rendering. +The strength of the glow effect. This applies as the glow is blurred across the screen and increases the distance and intensity of the blur. When using the Mobile rendering method, this should be increased to compensate for the lower dynamic range. .. rst-class:: classref-item-separator @@ -1364,6 +1368,8 @@ The number of cascades to use for SDFGI (between 1 and 8). A higher number of ca If ``true``, enables signed distance field global illumination for meshes that have their :ref:`GeometryInstance3D.gi_mode` set to :ref:`GeometryInstance3D.GI_MODE_STATIC`. SDFGI is a real-time global illumination technique that works well with procedurally generated and user-built levels, including in situations where geometry is created during gameplay. The signed distance field is automatically generated around the camera as it moves. Dynamic lights are supported, but dynamic occluders and emissive surfaces are not. +\ **Note:** SDFGI is only supported in the Forward+ rendering method, not Mobile or Compatibility. + \ **Performance:** SDFGI is relatively demanding on the GPU and is not suited to low-end hardware such as integrated graphics (consider :ref:`LightmapGI` instead). To improve SDFGI performance, enable :ref:`ProjectSettings.rendering/global_illumination/gi/use_half_resolution` in the Project Settings. \ **Note:** Meshes should have sufficiently thick walls to avoid light leaks (avoid one-sided walls). For interior levels, enclose your level geometry in a sufficiently large box and bridge the loops to close the mesh. @@ -1610,6 +1616,8 @@ Sets the strength of the additional level of detail for the screen-space ambient If ``true``, the screen-space ambient occlusion effect is enabled. This darkens objects' corners and cavities to simulate ambient light not reaching the entire object as in real life. This works well for small, dynamic objects, but baked lighting or ambient occlusion textures will do a better job at displaying ambient occlusion on large static objects. Godot uses a form of SSAO called Adaptive Screen Space Ambient Occlusion which is itself a form of Horizon Based Ambient Occlusion. +\ **Note:** SSAO is only supported in the Forward+ rendering method, not Mobile or Compatibility. + .. rst-class:: classref-item-separator ---- @@ -1729,6 +1737,8 @@ The amount that the screen-space ambient occlusion effect is allowed to blur ove If ``true``, the screen-space indirect lighting effect is enabled. Screen space indirect lighting is a form of indirect lighting that allows diffuse light to bounce between nearby objects. Screen-space indirect lighting works very similarly to screen-space ambient occlusion, in that it only affects a limited range. It is intended to be used along with a form of proper global illumination like SDFGI or :ref:`VoxelGI`. Screen-space indirect lighting is not affected by individual light's :ref:`Light3D.light_indirect_energy`. +\ **Note:** SSIL is only supported in the Forward+ rendering method, not Mobile or Compatibility. + .. rst-class:: classref-item-separator ---- @@ -1831,6 +1841,8 @@ The depth tolerance for screen-space reflections. If ``true``, screen-space reflections are enabled. Screen-space reflections are more accurate than reflections from :ref:`VoxelGI`\ s or :ref:`ReflectionProbe`\ s, but are slower and can't reflect surfaces occluded by others. +\ **Note:** SSR is only supported in the Forward+ rendering method, not Mobile or Compatibility. + .. rst-class:: classref-item-separator ---- @@ -2075,7 +2087,7 @@ The brightness of the emitted light from the volumetric fog. Enables the volumetric fog effect. Volumetric fog uses a screen-aligned froxel buffer to calculate accurate volumetric scattering in the short to medium range. Volumetric fog interacts with :ref:`FogVolume`\ s and lights to calculate localized and global fog. Volumetric fog uses a PBR single-scattering model based on extinction, scattering, and emission which it exposes to users as density, albedo, and emission. -\ **Note:** Volumetric fog is only available in the forward plus renderer. It is not available in the mobile renderer or the compatibility renderer. +\ **Note:** Volumetric fog is only supported in the Forward+ rendering method, not Mobile or Compatibility. .. rst-class:: classref-item-separator diff --git a/classes/class_fileaccess.rst b/classes/class_fileaccess.rst index ead53ce8d..e13b40848 100644 --- a/classes/class_fileaccess.rst +++ b/classes/class_fileaccess.rst @@ -689,6 +689,8 @@ Returns a SHA-256 :ref:`String` representing the file at the given Returns the next :ref:`Variant` value from the file. If ``allow_objects`` is ``true``, decoding objects is allowed. +Internally, this uses the same decoding mechanism as the :ref:`@GlobalScope.bytes_to_var` method. + \ **Warning:** Deserialized objects can contain code which gets executed. Do not use this option if the serialized object comes from untrusted sources to avoid potential security threats such as remote code execution. .. rst-class:: classref-item-separator @@ -1002,6 +1004,8 @@ void **store_var** **(** :ref:`Variant` value, :ref:`bool` method. + \ **Note:** Not all properties are included. Only properties that are configured with the :ref:`@GlobalScope.PROPERTY_USAGE_STORAGE` flag set will be serialized. You can add a new usage flag to a property by overriding the :ref:`Object._get_property_list` method in your class. You can also check how property usage is configured by calling :ref:`Object._get_property_list`. See :ref:`PropertyUsageFlags` for the possible usage flags. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` diff --git a/classes/class_font.rst b/classes/class_font.rst index 73003242d..54a2f5069 100644 --- a/classes/class_font.rst +++ b/classes/class_font.rst @@ -400,7 +400,7 @@ Returns the spacing for the given ``type`` (see :ref:`SpacingType` **get_string_size** **(** :ref:`String` text, :ref:`HorizontalAlignment` alignment=0, :ref:`float` width=-1, :ref:`int` font_size=16, :ref:`JustificationFlag` jst_flags=3, :ref:`Direction` direction=0, :ref:`Orientation` orientation=0 **)** |const| -Returns the size of a bounding box of a single-line string, taking kerning and advance into account. See also :ref:`get_multiline_string_size` and :ref:`draw_string`. +Returns the size of a bounding box of a single-line string, taking kerning, advance and subpixel positioning into account. See also :ref:`get_multiline_string_size` and :ref:`draw_string`. For example, to get the string size as displayed by a single-line Label, use: @@ -418,6 +418,8 @@ For example, to get the string size as displayed by a single-line Label, use: +\ **Note:** Since kerning, advance and subpixel positioning are taken into account by :ref:`get_string_size`, using separate :ref:`get_string_size` calls on substrings of a string then adding the results together will return a different result compared to using a single :ref:`get_string_size` call on the full string. + \ **Note:** Real height of the string is context-dependent and can be significantly different from the value returned by :ref:`get_height`. .. rst-class:: classref-item-separator diff --git a/classes/class_fontvariation.rst b/classes/class_fontvariation.rst index 9a24778a8..5e3c66edd 100644 --- a/classes/class_fontvariation.rst +++ b/classes/class_fontvariation.rst @@ -176,7 +176,7 @@ Extra spacing at the bottom of the line in pixels. - void **set_spacing** **(** :ref:`SpacingType` spacing, :ref:`int` value **)** - :ref:`int` **get_spacing** **(** **)** -Extra spacing between graphical glyphs +Extra spacing between graphical glyphs. .. rst-class:: classref-item-separator diff --git a/classes/class_graphedit.rst b/classes/class_graphedit.rst index 763e1be32..0940b2e46 100644 --- a/classes/class_graphedit.rst +++ b/classes/class_graphedit.rst @@ -19,6 +19,8 @@ GraphEdit is a control responsible for displaying and manipulating graph-like da Description ----------- +**Note:** Please be aware that this node will undergo extensive refactoring in a future 4.x version involving compatibility-breaking API changes. + GraphEdit provides tools for creation, manipulation, and display of various graphs. Its main purpose in the engine is to power the visual programming systems, such as visual shaders, but it is also available for use in user projects. GraphEdit by itself is only an empty container, representing an infinite grid where :ref:`GraphNode`\ s can be placed. Each :ref:`GraphNode` represent a node in the graph, a single unit of data in the connected scheme. GraphEdit, in turn, helps to control various interactions with nodes and between nodes. When the user attempts to connect, disconnect, or close a :ref:`GraphNode`, a signal is emitted in the GraphEdit, but no action is taken by default. It is the responsibility of the programmer utilizing this control to implement the necessary logic to determine how each request should be handled. diff --git a/classes/class_graphnode.rst b/classes/class_graphnode.rst index 15c710e2e..784a50a29 100644 --- a/classes/class_graphnode.rst +++ b/classes/class_graphnode.rst @@ -19,6 +19,8 @@ GraphNode is a :ref:`Container` control that represents a singl Description ----------- +**Note:** Please be aware that this node will undergo extensive refactoring in a future 4.x version involving compatibility-breaking API changes. + GraphNode allows to create nodes for a :ref:`GraphEdit` graph with customizable content based on its child :ref:`Control`\ s. GraphNode is a :ref:`Container` and is responsible for placing its children on screen. This works similar to :ref:`VBoxContainer`. Children, in turn, provide GraphNode with so-called slots, each of which can have a connection port on either side. This is similar to how :ref:`TabContainer` uses children to create the tabs. Each GraphNode slot is defined by its index and can provide the node with up to two ports: one on the left, and one on the right. By convention the left port is also referred to as the input port and the right port is referred to as the output port. Each port can be enabled and configured individually, using different type and color. The type is an arbitrary value that you can define using your own considerations. The parent :ref:`GraphEdit` will receive this information on each connect and disconnect request. diff --git a/classes/class_httprequest.rst b/classes/class_httprequest.rst index 23cca7afd..4972f8174 100644 --- a/classes/class_httprequest.rst +++ b/classes/class_httprequest.rst @@ -171,8 +171,7 @@ Can be used to make HTTP requests, i.e. download or upload files or web content GD.PushError("Couldn't load the image."); } - var texture = new ImageTexture(); - texture.CreateFromImage(image); + var texture = ImageTexture.CreateFromImage(image); // Display the image in a TextureRect node. var textureRect = new TextureRect(); diff --git a/classes/class_image.rst b/classes/class_image.rst index 9d118dfc3..bb85bd150 100644 --- a/classes/class_image.rst +++ b/classes/class_image.rst @@ -1623,8 +1623,7 @@ Sets the :ref:`Color` of the pixel at ``(x, y)`` to ``color``. var img_width = 10 var img_height = 5 - var img = Image.new() - img.create(img_width, img_height, false, Image.FORMAT_RGBA8) + var img = Image.create(img_width, img_height, false, Image.FORMAT_RGBA8) img.set_pixel(1, 2, Color.RED) # Sets the color at (1, 2) to red. @@ -1632,8 +1631,7 @@ Sets the :ref:`Color` of the pixel at ``(x, y)`` to ``color``. int imgWidth = 10; int imgHeight = 5; - var img = new Image(); - img.Create(imgWidth, imgHeight, false, Image.Format.Rgba8); + var img = Image.Create(imgWidth, imgHeight, false, Image.Format.Rgba8); img.SetPixel(1, 2, Colors.Red); // Sets the color at (1, 2) to red. @@ -1662,8 +1660,7 @@ Sets the :ref:`Color` of the pixel at ``point`` to ``color``. var img_width = 10 var img_height = 5 - var img = Image.new() - img.create(img_width, img_height, false, Image.FORMAT_RGBA8) + var img = Image.create(img_width, img_height, false, Image.FORMAT_RGBA8) img.set_pixelv(Vector2i(1, 2), Color.RED) # Sets the color at (1, 2) to red. @@ -1671,8 +1668,7 @@ Sets the :ref:`Color` of the pixel at ``point`` to ``color``. int imgWidth = 10; int imgHeight = 5; - var img = new Image(); - img.Create(imgWidth, imgHeight, false, Image.Format.Rgba8); + var img = Image.Create(imgWidth, imgHeight, false, Image.Format.Rgba8); img.SetPixelv(new Vector2I(1, 2), Colors.Red); // Sets the color at (1, 2) to red. diff --git a/classes/class_light2d.rst b/classes/class_light2d.rst index eaced9f97..ef065ac34 100644 --- a/classes/class_light2d.rst +++ b/classes/class_light2d.rst @@ -262,7 +262,9 @@ The Light2D's energy value. The larger the value, the stronger the light. - void **set_item_cull_mask** **(** :ref:`int` value **)** - :ref:`int` **get_item_cull_mask** **(** **)** -The layer mask. Only objects with a matching mask will be affected by the Light2D. +The layer mask. Only objects with a matching :ref:`CanvasItem.light_mask` will be affected by the Light2D. See also :ref:`shadow_item_cull_mask`, which affects which objects can cast shadows. + +\ **Note:** :ref:`range_item_cull_mask` is ignored by :ref:`DirectionalLight2D`, which will always light a 2D node regardless of the 2D node's :ref:`CanvasItem.light_mask`. .. rst-class:: classref-item-separator @@ -415,7 +417,7 @@ Smoothing value for shadows. Higher values will result in softer shadows, at the - void **set_item_shadow_cull_mask** **(** :ref:`int` value **)** - :ref:`int` **get_item_shadow_cull_mask** **(** **)** -The shadow mask. Used with :ref:`LightOccluder2D` to cast shadows. Only occluders with a matching light mask will cast shadows. +The shadow mask. Used with :ref:`LightOccluder2D` to cast shadows. Only occluders with a matching :ref:`CanvasItem.light_mask` will cast shadows. See also :ref:`range_item_cull_mask`, which affects which objects can *receive* the light. .. rst-class:: classref-section-separator diff --git a/classes/class_light3d.rst b/classes/class_light3d.rst index 8e7a81c11..e8c388b00 100644 --- a/classes/class_light3d.rst +++ b/classes/class_light3d.rst @@ -450,10 +450,12 @@ If ``true``, the light only appears in the editor and will not be visible at run - void **set_param** **(** :ref:`Param` param, :ref:`float` value **)** - :ref:`float` **get_param** **(** :ref:`Param` param **)** |const| -The light's angular size in degrees. Increasing this will make shadows softer at greater distances. Only available for :ref:`DirectionalLight3D`\ s. For reference, the Sun from the Earth is approximately ``0.5``. +The light's angular size in degrees. Increasing this will make shadows softer at greater distances (also called percentage-closer soft shadows, or PCSS). Only available for :ref:`DirectionalLight3D`\ s. For reference, the Sun from the Earth is approximately ``0.5``. Increasing this value above ``0.0`` for lights with shadows enabled will have a noticeable performance cost due to PCSS. \ **Note:** :ref:`light_angular_distance` is not affected by :ref:`Node3D.scale` (the light's scale or its parent's scale). +\ **Note:** PCSS for directional lights is only supported in the Forward+ rendering method, not Mobile or Compatibility. + .. rst-class:: classref-item-separator ---- @@ -619,6 +621,8 @@ If ``true``, the light's effect is reversed, darkening areas and casting bright \ **Note:** Unlike :ref:`BaseMaterial3D` whose filter mode can be adjusted on a per-material basis, the filter mode for light projector textures is set globally with :ref:`ProjectSettings.rendering/textures/light_projectors/filter`. +\ **Note:** Light projector textures are only supported in the Forward+ and Mobile rendering methods, not Compatibility. + .. rst-class:: classref-item-separator ---- @@ -634,10 +638,12 @@ If ``true``, the light's effect is reversed, darkening areas and casting bright - void **set_param** **(** :ref:`Param` param, :ref:`float` value **)** - :ref:`float` **get_param** **(** :ref:`Param` param **)** |const| -The size of the light in Godot units. Only available for :ref:`OmniLight3D`\ s and :ref:`SpotLight3D`\ s. Increasing this value will make the light fade out slower and shadows appear blurrier. This can be used to simulate area lights to an extent. +The size of the light in Godot units. Only available for :ref:`OmniLight3D`\ s and :ref:`SpotLight3D`\ s. Increasing this value will make the light fade out slower and shadows appear blurrier (also called percentage-closer soft shadows, or PCSS). This can be used to simulate area lights to an extent. Increasing this value above ``0.0`` for lights with shadows enabled will have a noticeable performance cost due to PCSS. \ **Note:** :ref:`light_size` is not affected by :ref:`Node3D.scale` (the light's scale or its parent's scale). +\ **Note:** PCSS for positional lights is only supported in the Forward+ and Mobile rendering methods, not Compatibility. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_marshalls.rst b/classes/class_marshalls.rst index 2bd74fa41..1d0c831f2 100644 --- a/classes/class_marshalls.rst +++ b/classes/class_marshalls.rst @@ -84,6 +84,8 @@ Returns a decoded string corresponding to the Base64-encoded string ``base64_str Returns a decoded :ref:`Variant` corresponding to the Base64-encoded string ``base64_str``. If ``allow_objects`` is ``true``, decoding objects is allowed. +Internally, this uses the same decoding mechanism as the :ref:`@GlobalScope.bytes_to_var` method. + \ **Warning:** Deserialized objects can contain code which gets executed. Do not use this option if the serialized object comes from untrusted sources to avoid potential security threats such as remote code execution. .. rst-class:: classref-item-separator @@ -122,6 +124,8 @@ Returns a Base64-encoded string of the UTF-8 string ``utf8_str``. Returns a Base64-encoded string of the :ref:`Variant` ``variant``. If ``full_objects`` is ``true``, encoding objects is allowed (and can potentially include code). +Internally, this uses the same encoding mechanism as the :ref:`@GlobalScope.var_to_bytes` method. + .. |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.)` diff --git a/classes/class_navigationserver2d.rst b/classes/class_navigationserver2d.rst index e2bad98f5..91cd5a6a4 100644 --- a/classes/class_navigationserver2d.rst +++ b/classes/class_navigationserver2d.rst @@ -12,7 +12,7 @@ NavigationServer2D **Inherits:** :ref:`Object` -Server interface for low-level 2D navigation access +Server interface for low-level 2D navigation access. .. rst-class:: classref-introduction-group diff --git a/classes/class_navigationserver3d.rst b/classes/class_navigationserver3d.rst index 0f2e9ac7e..e700b5949 100644 --- a/classes/class_navigationserver3d.rst +++ b/classes/class_navigationserver3d.rst @@ -12,7 +12,7 @@ NavigationServer3D **Inherits:** :ref:`Object` -Server interface for low-level 3D navigation access +Server interface for low-level 3D navigation access. .. rst-class:: classref-introduction-group diff --git a/classes/class_ninepatchrect.rst b/classes/class_ninepatchrect.rst index 9f815f107..bf51022ab 100644 --- a/classes/class_ninepatchrect.rst +++ b/classes/class_ninepatchrect.rst @@ -113,8 +113,6 @@ Stretches the center texture across the NinePatchRect. This may cause the textur Repeats the center texture across the NinePatchRect. This won't cause any visible distortion. The texture must be seamless for this to work without displaying artifacts between edges. -\ **Note:** Only supported when using the Vulkan renderer. When using the OpenGL renderer, this will behave like :ref:`AXIS_STRETCH_MODE_STRETCH`. - .. _class_NinePatchRect_constant_AXIS_STRETCH_MODE_TILE_FIT: .. rst-class:: classref-enumeration-constant @@ -123,8 +121,6 @@ Repeats the center texture across the NinePatchRect. This won't cause any visibl Repeats the center texture across the NinePatchRect, but will also stretch the texture to make sure each tile is visible in full. This may cause the texture to be distorted, but less than :ref:`AXIS_STRETCH_MODE_STRETCH`. The texture must be seamless for this to work without displaying artifacts between edges. -\ **Note:** Only supported when using the Vulkan renderer. When using the OpenGL renderer, this will behave like :ref:`AXIS_STRETCH_MODE_STRETCH`. - .. rst-class:: classref-section-separator ---- diff --git a/classes/class_object.rst b/classes/class_object.rst index 8433180ae..54ff310e4 100644 --- a/classes/class_object.rst +++ b/classes/class_object.rst @@ -713,7 +713,7 @@ Calls the ``method`` on the object and returns the result. Unlike :ref:`call` on each call +\ **Note:** In C#, ``method`` must be in snake_case when referring to built-in Godot methods. Prefer using the names exposed in the ``MethodName`` class to avoid allocating a new :ref:`StringName` on each call. .. rst-class:: classref-item-separator diff --git a/classes/class_omnilight3d.rst b/classes/class_omnilight3d.rst index 93c9dd1b9..499877702 100644 --- a/classes/class_omnilight3d.rst +++ b/classes/class_omnilight3d.rst @@ -21,6 +21,8 @@ Description An Omnidirectional light is a type of :ref:`Light3D` that emits light in all directions. The light is attenuated by distance and this attenuation can be configured by changing its energy, radius, and attenuation parameters. +\ **Note:** When using the Mobile rendering method, only 8 omni lights can be displayed on each mesh resource. Attempting to display more than 8 omni lights on a single mesh resource will result in omni lights flickering in and out as the camera moves. When using the Compatibility rendering method, only 8 omni lights can be displayed on each mesh resource by default, but this can be increased by adjusting :ref:`ProjectSettings.rendering/limits/opengl/max_lights_per_object`. + \ **Note:** When using the Mobile or Compatibility rendering methods, omni lights will only correctly affect meshes whose visibility AABB intersects with the light's AABB. If using a shader to deform the mesh in a way that makes it go outside its AABB, :ref:`GeometryInstance3D.extra_cull_margin` must be increased on the mesh. Otherwise, the light may not be visible on the mesh. .. rst-class:: classref-introduction-group diff --git a/classes/class_packetpeer.rst b/classes/class_packetpeer.rst index 568fa4ee9..e4b7e0ca6 100644 --- a/classes/class_packetpeer.rst +++ b/classes/class_packetpeer.rst @@ -136,6 +136,8 @@ Returns the error state of the last packet received (via :ref:`get_packet` method. + \ **Warning:** Deserialized objects can contain code which gets executed. Do not use this option if the serialized object comes from untrusted sources to avoid potential security threats such as remote code execution. .. rst-class:: classref-item-separator @@ -162,6 +164,8 @@ Sends a raw packet. Sends a :ref:`Variant` as a packet. If ``full_objects`` is ``true``, encoding objects is allowed (and can potentially include code). +Internally, this uses the same encoding mechanism as the :ref:`@GlobalScope.var_to_bytes` method. + .. |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.)` diff --git a/classes/class_physicsdirectspacestate3d.rst b/classes/class_physicsdirectspacestate3d.rst index b475bb390..add7f8194 100644 --- a/classes/class_physicsdirectspacestate3d.rst +++ b/classes/class_physicsdirectspacestate3d.rst @@ -43,7 +43,7 @@ Methods +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`PackedFloat32Array` | :ref:`cast_motion` **(** :ref:`PhysicsShapeQueryParameters3D` parameters **)** | +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`PackedVector2Array[]` | :ref:`collide_shape` **(** :ref:`PhysicsShapeQueryParameters3D` parameters, :ref:`int` max_results=32 **)** | + | :ref:`PackedVector3Array[]` | :ref:`collide_shape` **(** :ref:`PhysicsShapeQueryParameters3D` parameters, :ref:`int` max_results=32 **)** | +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Dictionary` | :ref:`get_rest_info` **(** :ref:`PhysicsShapeQueryParameters3D` parameters **)** | +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -83,7 +83,7 @@ Returns an array with the safe and unsafe proportions (between 0 and 1) of the m .. rst-class:: classref-method -:ref:`PackedVector2Array[]` **collide_shape** **(** :ref:`PhysicsShapeQueryParameters3D` parameters, :ref:`int` max_results=32 **)** +:ref:`PackedVector3Array[]` **collide_shape** **(** :ref:`PhysicsShapeQueryParameters3D` parameters, :ref:`int` max_results=32 **)** Checks the intersections of a shape, given through a :ref:`PhysicsShapeQueryParameters3D` object, against the space. The resulting array contains a list of points where the shape intersects another. Like with :ref:`intersect_shape`, the number of returned results can be limited to save processing time. diff --git a/classes/class_physicsserver2d.rst b/classes/class_physicsserver2d.rst index 8304cb927..34804ead3 100644 --- a/classes/class_physicsserver2d.rst +++ b/classes/class_physicsserver2d.rst @@ -21,7 +21,21 @@ Server interface for low-level 2D physics access. Description ----------- -PhysicsServer2D is the server responsible for all 2D physics. It can create many kinds of physics objects, but does not insert them on the node tree. +PhysicsServer2D is the server responsible for all 2D physics. It can directly create and manipulate all physics objects: + +- A *space* is a self-contained world for a physics simulation. It contains bodies, areas, and joints. Its state can be queried for collision and intersection information, and several parameters of the simulation can be modified. + +- A *shape* is a geometric figure such as a circle, a rectangle, a capsule, or a polygon. It can be used for collision detection by adding it to a body/area, possibly with an extra transformation relative to the body/area's origin. Bodies/areas can have multiple (transformed) shapes added to them, and a single shape can be added to bodies/areas multiple times with different local transformations. + +- A *body* is a physical object which can be in static, kinematic, or rigid mode. Its state (such as position and velocity) can be queried and updated. A force integration callback can be set to customize the body's physics. + +- An *area* is a region in space which can be used to detect bodies and areas entering and exiting it. A body monitoring callback can be set to report entering/exiting body shapes, and similarly an area monitoring callback can be set. Gravity and damping can be overridden within the area by setting area parameters. + +- A *joint* is a constraint, either between two bodies or on one body relative to a point. Parameters such as the joint bias and the rest length of a spring joint can be adjusted. + +Physics objects in the physics server may be created and manipulated independently; they do not have to be tied to nodes in the scene tree. + +\ **Note:** All the physics nodes use the physics server internally. Adding a physics node to the scene tree will cause a corresponding physics object to be created in the physics server. A rigid body node registers a callback that updates the node's transform with the transform of the respective body object in the physics server (every physics update). An area node registers a callback to inform the area node about overlaps with the respective area object in the physics server. The raycast node queries the direct state of the relevant space in the physics server. .. rst-class:: classref-reftable-group @@ -286,7 +300,7 @@ enum **SpaceParameter**: :ref:`SpaceParameter` **SPACE_PARAM_CONTACT_RECYCLE_RADIUS** = ``0`` -Constant to set/get the maximum distance a pair of bodies has to move before their collision status has to be recalculated. +Constant to set/get the maximum distance a pair of bodies has to move before their collision status has to be recalculated. The default value of this parameter is :ref:`ProjectSettings.physics/2d/solver/contact_recycle_radius`. .. _class_PhysicsServer2D_constant_SPACE_PARAM_CONTACT_MAX_SEPARATION: @@ -294,7 +308,7 @@ Constant to set/get the maximum distance a pair of bodies has to move before the :ref:`SpaceParameter` **SPACE_PARAM_CONTACT_MAX_SEPARATION** = ``1`` -Constant to set/get the maximum distance a shape can be from another before they are considered separated and the contact is discarded. +Constant to set/get the maximum distance a shape can be from another before they are considered separated and the contact is discarded. The default value of this parameter is :ref:`ProjectSettings.physics/2d/solver/contact_max_separation`. .. _class_PhysicsServer2D_constant_SPACE_PARAM_CONTACT_MAX_ALLOWED_PENETRATION: @@ -302,7 +316,7 @@ Constant to set/get the maximum distance a shape can be from another before they :ref:`SpaceParameter` **SPACE_PARAM_CONTACT_MAX_ALLOWED_PENETRATION** = ``2`` -Constant to set/get the maximum distance a shape can penetrate another shape before it is considered a collision. +Constant to set/get the maximum distance a shape can penetrate another shape before it is considered a collision. The default value of this parameter is :ref:`ProjectSettings.physics/2d/solver/contact_max_allowed_penetration`. .. _class_PhysicsServer2D_constant_SPACE_PARAM_CONTACT_DEFAULT_BIAS: @@ -310,7 +324,7 @@ Constant to set/get the maximum distance a shape can penetrate another shape bef :ref:`SpaceParameter` **SPACE_PARAM_CONTACT_DEFAULT_BIAS** = ``3`` -Constant to set/get the default solver bias for all physics contacts. A solver bias is a factor controlling how much two objects "rebound", after overlapping, to avoid leaving them in that state because of numerical imprecision. +Constant to set/get the default solver bias for all physics contacts. A solver bias is a factor controlling how much two objects "rebound", after overlapping, to avoid leaving them in that state because of numerical imprecision. The default value of this parameter is :ref:`ProjectSettings.physics/2d/solver/default_contact_bias`. .. _class_PhysicsServer2D_constant_SPACE_PARAM_BODY_LINEAR_VELOCITY_SLEEP_THRESHOLD: @@ -318,7 +332,7 @@ Constant to set/get the default solver bias for all physics contacts. A solver b :ref:`SpaceParameter` **SPACE_PARAM_BODY_LINEAR_VELOCITY_SLEEP_THRESHOLD** = ``4`` -Constant to set/get the threshold linear velocity of activity. A body marked as potentially inactive for both linear and angular velocity will be put to sleep after the time given. +Constant to set/get the threshold linear velocity of activity. A body marked as potentially inactive for both linear and angular velocity will be put to sleep after the time given. The default value of this parameter is :ref:`ProjectSettings.physics/2d/sleep_threshold_linear`. .. _class_PhysicsServer2D_constant_SPACE_PARAM_BODY_ANGULAR_VELOCITY_SLEEP_THRESHOLD: @@ -326,7 +340,7 @@ Constant to set/get the threshold linear velocity of activity. A body marked as :ref:`SpaceParameter` **SPACE_PARAM_BODY_ANGULAR_VELOCITY_SLEEP_THRESHOLD** = ``5`` -Constant to set/get the threshold angular velocity of activity. A body marked as potentially inactive for both linear and angular velocity will be put to sleep after the time given. +Constant to set/get the threshold angular velocity of activity. A body marked as potentially inactive for both linear and angular velocity will be put to sleep after the time given. The default value of this parameter is :ref:`ProjectSettings.physics/2d/sleep_threshold_angular`. .. _class_PhysicsServer2D_constant_SPACE_PARAM_BODY_TIME_TO_SLEEP: @@ -334,7 +348,7 @@ Constant to set/get the threshold angular velocity of activity. A body marked as :ref:`SpaceParameter` **SPACE_PARAM_BODY_TIME_TO_SLEEP** = ``6`` -Constant to set/get the maximum time of activity. A body marked as potentially inactive for both linear and angular velocity will be put to sleep after this time. +Constant to set/get the maximum time of activity. A body marked as potentially inactive for both linear and angular velocity will be put to sleep after this time. The default value of this parameter is :ref:`ProjectSettings.physics/2d/time_before_sleep`. .. _class_PhysicsServer2D_constant_SPACE_PARAM_CONSTRAINT_DEFAULT_BIAS: @@ -342,7 +356,7 @@ Constant to set/get the maximum time of activity. A body marked as potentially i :ref:`SpaceParameter` **SPACE_PARAM_CONSTRAINT_DEFAULT_BIAS** = ``7`` -Constant to set/get the default solver bias for all physics constraints. A solver bias is a factor controlling how much two objects "rebound", after violating a constraint, to avoid leaving them in that state because of numerical imprecision. +Constant to set/get the default solver bias for all physics constraints. A solver bias is a factor controlling how much two objects "rebound", after violating a constraint, to avoid leaving them in that state because of numerical imprecision. The default value of this parameter is :ref:`ProjectSettings.physics/2d/solver/default_constraint_bias`. .. _class_PhysicsServer2D_constant_SPACE_PARAM_SOLVER_ITERATIONS: @@ -350,7 +364,7 @@ Constant to set/get the default solver bias for all physics constraints. A solve :ref:`SpaceParameter` **SPACE_PARAM_SOLVER_ITERATIONS** = ``8`` -Constant to set/get the number of solver iterations for all contacts and constraints. The greater the number of iterations, the more accurate the collisions will be. However, a greater number of iterations requires more CPU power, which can decrease performance. +Constant to set/get the number of solver iterations for all contacts and constraints. The greater the number of iterations, the more accurate the collisions will be. However, a greater number of iterations requires more CPU power, which can decrease performance. The default value of this parameter is :ref:`ProjectSettings.physics/2d/solver/solver_iterations`. .. rst-class:: classref-item-separator @@ -416,7 +430,7 @@ This is the constant for creating capsule shapes. A capsule shape is defined by :ref:`ShapeType` **SHAPE_CONVEX_POLYGON** = ``6`` -This is the constant for creating convex polygon shapes. A polygon is defined by a list of points. It can be used for intersections and inside/outside checks. Unlike the :ref:`CollisionPolygon2D.polygon` property, polygons modified with :ref:`shape_set_data` do not verify that the points supplied form is a convex polygon. +This is the constant for creating convex polygon shapes. A polygon is defined by a list of points. It can be used for intersections and inside/outside checks. .. _class_PhysicsServer2D_constant_SHAPE_CONCAVE_POLYGON: @@ -450,7 +464,7 @@ enum **AreaParameter**: :ref:`AreaParameter` **AREA_PARAM_GRAVITY_OVERRIDE_MODE** = ``0`` -Constant to set/get gravity override mode in an area. See :ref:`AreaSpaceOverrideMode` for possible values. +Constant to set/get gravity override mode in an area. See :ref:`AreaSpaceOverrideMode` for possible values. The default value of this parameter is :ref:`AREA_SPACE_OVERRIDE_DISABLED`. .. _class_PhysicsServer2D_constant_AREA_PARAM_GRAVITY: @@ -458,7 +472,7 @@ Constant to set/get gravity override mode in an area. See :ref:`AreaSpaceOverrid :ref:`AreaParameter` **AREA_PARAM_GRAVITY** = ``1`` -Constant to set/get gravity strength in an area. +Constant to set/get gravity strength in an area. The default value of this parameter is ``9.80665``. .. _class_PhysicsServer2D_constant_AREA_PARAM_GRAVITY_VECTOR: @@ -466,7 +480,7 @@ Constant to set/get gravity strength in an area. :ref:`AreaParameter` **AREA_PARAM_GRAVITY_VECTOR** = ``2`` -Constant to set/get gravity vector/center in an area. +Constant to set/get gravity vector/center in an area. The default value of this parameter is ``Vector2(0, -1)``. .. _class_PhysicsServer2D_constant_AREA_PARAM_GRAVITY_IS_POINT: @@ -474,7 +488,7 @@ Constant to set/get gravity vector/center in an area. :ref:`AreaParameter` **AREA_PARAM_GRAVITY_IS_POINT** = ``3`` -Constant to set/get whether the gravity vector of an area is a direction, or a center point. +Constant to set/get whether the gravity vector of an area is a direction, or a center point. The default value of this parameter is ``false``. .. _class_PhysicsServer2D_constant_AREA_PARAM_GRAVITY_POINT_UNIT_DISTANCE: @@ -484,7 +498,7 @@ Constant to set/get whether the gravity vector of an area is a direction, or a c Constant to set/get the distance at which the gravity strength is equal to the gravity controlled by :ref:`AREA_PARAM_GRAVITY`. For example, on a planet 100 pixels in radius with a surface gravity of 4.0 px/s², set the gravity to 4.0 and the unit distance to 100.0. The gravity will have falloff according to the inverse square law, so in the example, at 200 pixels from the center the gravity will be 1.0 px/s² (twice the distance, 1/4th the gravity), at 50 pixels it will be 16.0 px/s² (half the distance, 4x the gravity), and so on. -The above is true only when the unit distance is a positive number. When the unit distance is set to 0.0, the gravity will be constant regardless of distance. +The above is true only when the unit distance is a positive number. When the unit distance is set to 0.0, the gravity will be constant regardless of distance. The default value of this parameter is ``0.0``. .. _class_PhysicsServer2D_constant_AREA_PARAM_LINEAR_DAMP_OVERRIDE_MODE: @@ -492,7 +506,7 @@ The above is true only when the unit distance is a positive number. When the uni :ref:`AreaParameter` **AREA_PARAM_LINEAR_DAMP_OVERRIDE_MODE** = ``5`` -Constant to set/get linear damping override mode in an area. See :ref:`AreaSpaceOverrideMode` for possible values. +Constant to set/get linear damping override mode in an area. See :ref:`AreaSpaceOverrideMode` for possible values. The default value of this parameter is :ref:`AREA_SPACE_OVERRIDE_DISABLED`. .. _class_PhysicsServer2D_constant_AREA_PARAM_LINEAR_DAMP: @@ -500,7 +514,7 @@ Constant to set/get linear damping override mode in an area. See :ref:`AreaSpace :ref:`AreaParameter` **AREA_PARAM_LINEAR_DAMP** = ``6`` -Constant to set/get the linear damping factor of an area. +Constant to set/get the linear damping factor of an area. The default value of this parameter is ``0.1``. .. _class_PhysicsServer2D_constant_AREA_PARAM_ANGULAR_DAMP_OVERRIDE_MODE: @@ -508,7 +522,7 @@ Constant to set/get the linear damping factor of an area. :ref:`AreaParameter` **AREA_PARAM_ANGULAR_DAMP_OVERRIDE_MODE** = ``7`` -Constant to set/get angular damping override mode in an area. See :ref:`AreaSpaceOverrideMode` for possible values. +Constant to set/get angular damping override mode in an area. See :ref:`AreaSpaceOverrideMode` for possible values. The default value of this parameter is :ref:`AREA_SPACE_OVERRIDE_DISABLED`. .. _class_PhysicsServer2D_constant_AREA_PARAM_ANGULAR_DAMP: @@ -516,7 +530,7 @@ Constant to set/get angular damping override mode in an area. See :ref:`AreaSpac :ref:`AreaParameter` **AREA_PARAM_ANGULAR_DAMP** = ``8`` -Constant to set/get the angular damping factor of an area. +Constant to set/get the angular damping factor of an area. The default value of this parameter is ``1.0``. .. _class_PhysicsServer2D_constant_AREA_PARAM_PRIORITY: @@ -524,7 +538,7 @@ Constant to set/get the angular damping factor of an area. :ref:`AreaParameter` **AREA_PARAM_PRIORITY** = ``9`` -Constant to set/get the priority (order of processing) of an area. +Constant to set/get the priority (order of processing) of an area. The default value of this parameter is ``0``. .. rst-class:: classref-item-separator @@ -634,7 +648,7 @@ enum **BodyParameter**: :ref:`BodyParameter` **BODY_PARAM_BOUNCE** = ``0`` -Constant to set/get a body's bounce factor. +Constant to set/get a body's bounce factor. The default value of this parameter is ``0.0``. .. _class_PhysicsServer2D_constant_BODY_PARAM_FRICTION: @@ -642,7 +656,7 @@ Constant to set/get a body's bounce factor. :ref:`BodyParameter` **BODY_PARAM_FRICTION** = ``1`` -Constant to set/get a body's friction. +Constant to set/get a body's friction. The default value of this parameter is ``1.0``. .. _class_PhysicsServer2D_constant_BODY_PARAM_MASS: @@ -650,7 +664,11 @@ Constant to set/get a body's friction. :ref:`BodyParameter` **BODY_PARAM_MASS** = ``2`` -Constant to set/get a body's mass. +Constant to set/get a body's mass. The default value of this parameter is ``1.0``. If the body's mode is set to :ref:`BODY_MODE_RIGID`, then setting this parameter will have the following additional effects: + +- If the parameter :ref:`BODY_PARAM_CENTER_OF_MASS` has never been set explicitly, then the value of that parameter will be recalculated based on the body's shapes. + +- If the parameter :ref:`BODY_PARAM_INERTIA` is set to a value ``<= 0.0``, then the value of that parameter will be recalculated based on the body's shapes, mass, and center of mass. .. _class_PhysicsServer2D_constant_BODY_PARAM_INERTIA: @@ -658,7 +676,7 @@ Constant to set/get a body's mass. :ref:`BodyParameter` **BODY_PARAM_INERTIA** = ``3`` -Constant to set/get a body's inertia. +Constant to set/get a body's inertia. The default value of this parameter is ``0.0``. If the body's inertia is set to a value ``<= 0.0``, then the inertia will be recalculated based on the body's shapes, mass, and center of mass. .. _class_PhysicsServer2D_constant_BODY_PARAM_CENTER_OF_MASS: @@ -666,7 +684,7 @@ Constant to set/get a body's inertia. :ref:`BodyParameter` **BODY_PARAM_CENTER_OF_MASS** = ``4`` -Constant to set/get a body's center of mass position in the body's local coordinate system. +Constant to set/get a body's center of mass position in the body's local coordinate system. The default value of this parameter is ``Vector2(0,0)``. If this parameter is never set explicitly, then it is recalculated based on the body's shapes when setting the parameter :ref:`BODY_PARAM_MASS` or when calling :ref:`body_set_space`. .. _class_PhysicsServer2D_constant_BODY_PARAM_GRAVITY_SCALE: @@ -674,7 +692,7 @@ Constant to set/get a body's center of mass position in the body's local coordin :ref:`BodyParameter` **BODY_PARAM_GRAVITY_SCALE** = ``5`` -Constant to set/get a body's gravity multiplier. +Constant to set/get a body's gravity multiplier. The default value of this parameter is ``1.0``. .. _class_PhysicsServer2D_constant_BODY_PARAM_LINEAR_DAMP_MODE: @@ -682,7 +700,7 @@ Constant to set/get a body's gravity multiplier. :ref:`BodyParameter` **BODY_PARAM_LINEAR_DAMP_MODE** = ``6`` -Constant to set/get a body's linear damping mode. See :ref:`BodyDampMode` for possible values. +Constant to set/get a body's linear damping mode. See :ref:`BodyDampMode` for possible values. The default value of this parameter is :ref:`BODY_DAMP_MODE_COMBINE`. .. _class_PhysicsServer2D_constant_BODY_PARAM_ANGULAR_DAMP_MODE: @@ -690,7 +708,7 @@ Constant to set/get a body's linear damping mode. See :ref:`BodyDampMode` **BODY_PARAM_ANGULAR_DAMP_MODE** = ``7`` -Constant to set/get a body's angular damping mode. See :ref:`BodyDampMode` for possible values. +Constant to set/get a body's angular damping mode. See :ref:`BodyDampMode` for possible values. The default value of this parameter is :ref:`BODY_DAMP_MODE_COMBINE`. .. _class_PhysicsServer2D_constant_BODY_PARAM_LINEAR_DAMP: @@ -698,7 +716,7 @@ Constant to set/get a body's angular damping mode. See :ref:`BodyDampMode` **BODY_PARAM_LINEAR_DAMP** = ``8`` -Constant to set/get a body's linear damping factor. +Constant to set/get a body's linear damping factor. The default value of this parameter is ``0.0``. .. _class_PhysicsServer2D_constant_BODY_PARAM_ANGULAR_DAMP: @@ -706,7 +724,7 @@ Constant to set/get a body's linear damping factor. :ref:`BodyParameter` **BODY_PARAM_ANGULAR_DAMP** = ``9`` -Constant to set/get a body's angular damping factor. +Constant to set/get a body's angular damping factor. The default value of this parameter is ``0.0``. .. _class_PhysicsServer2D_constant_BODY_PARAM_MAX: @@ -850,7 +868,9 @@ enum **JointParam**: :ref:`JointParam` **JOINT_PARAM_BIAS** = ``0`` +Constant to set/get how fast the joint pulls the bodies back to satisfy the joint constraint. The lower the value, the more the two bodies can pull on the joint. The default value of this parameter is ``0.0``. +\ **Note:** In Godot Physics, this parameter is only used for pin joints and groove joints. .. _class_PhysicsServer2D_constant_JOINT_PARAM_MAX_BIAS: @@ -858,7 +878,9 @@ enum **JointParam**: :ref:`JointParam` **JOINT_PARAM_MAX_BIAS** = ``1`` +Constant to set/get the maximum speed with which the joint can apply corrections. The default value of this parameter is ``3.40282e+38``. +\ **Note:** In Godot Physics, this parameter is only used for groove joints. .. _class_PhysicsServer2D_constant_JOINT_PARAM_MAX_FORCE: @@ -866,7 +888,9 @@ enum **JointParam**: :ref:`JointParam` **JOINT_PARAM_MAX_FORCE** = ``2`` +Constant to set/get the maximum force that the joint can use to act on the two bodies. The default value of this parameter is ``3.40282e+38``. +\ **Note:** In Godot Physics, this parameter is only used for groove joints. .. rst-class:: classref-item-separator @@ -884,7 +908,7 @@ enum **PinJointParam**: :ref:`PinJointParam` **PIN_JOINT_SOFTNESS** = ``0`` - +Constant to set/get a how much the bond of the pin joint can flex. The default value of this parameter is ``0.0``. .. rst-class:: classref-item-separator @@ -902,7 +926,7 @@ enum **DampedSpringParam**: :ref:`DampedSpringParam` **DAMPED_SPRING_REST_LENGTH** = ``0`` -Sets the resting length of the spring joint. The joint will always try to go to back this length when pulled apart. +Sets the resting length of the spring joint. The joint will always try to go to back this length when pulled apart. The default value of this parameter is the distance between the joint's anchor points. .. _class_PhysicsServer2D_constant_DAMPED_SPRING_STIFFNESS: @@ -910,7 +934,7 @@ Sets the resting length of the spring joint. The joint will always try to go to :ref:`DampedSpringParam` **DAMPED_SPRING_STIFFNESS** = ``1`` -Sets the stiffness of the spring joint. The joint applies a force equal to the stiffness times the distance from its resting length. +Sets the stiffness of the spring joint. The joint applies a force equal to the stiffness times the distance from its resting length. The default value of this parameter is ``20.0``. .. _class_PhysicsServer2D_constant_DAMPED_SPRING_DAMPING: @@ -918,7 +942,7 @@ Sets the stiffness of the spring joint. The joint applies a force equal to the s :ref:`DampedSpringParam` **DAMPED_SPRING_DAMPING** = ``2`` -Sets the damping ratio of the spring joint. A value of 0 indicates an undamped spring, while 1 causes the system to reach equilibrium as fast as possible (critical damping). +Sets the damping ratio of the spring joint. A value of 0 indicates an undamped spring, while 1 causes the system to reach equilibrium as fast as possible (critical damping). The default value of this parameter is ``1.5``. .. rst-class:: classref-item-separator @@ -936,7 +960,7 @@ enum **CCDMode**: :ref:`CCDMode` **CCD_MODE_DISABLED** = ``0`` -Disables continuous collision detection. This is the fastest way to detect body collisions, but can miss small, fast-moving objects. +Disables continuous collision detection. This is the fastest way to detect body collisions, but it can miss small and/or fast-moving objects. .. _class_PhysicsServer2D_constant_CCD_MODE_CAST_RAY: @@ -1029,7 +1053,7 @@ Method Descriptions void **area_add_shape** **(** :ref:`RID` area, :ref:`RID` shape, :ref:`Transform2D` transform=Transform2D(1, 0, 0, 1, 0, 0), :ref:`bool` disabled=false **)** -Adds a shape to the area, along with a transform matrix. Shapes are usually referenced by their index, so you should track which shape has a given index. +Adds a shape to the area, with the given local transform. The shape (together with its ``transform`` and ``disabled`` properties) is added to an array of shapes, and the shapes of an area are usually referenced by their index in this array. .. rst-class:: classref-item-separator @@ -1041,9 +1065,7 @@ Adds a shape to the area, along with a transform matrix. Shapes are usually refe void **area_attach_canvas_instance_id** **(** :ref:`RID` area, :ref:`int` id **)** -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Attaches the ``ObjectID`` of a canvas to the area. Use :ref:`Object.get_instance_id` to get the ``ObjectID`` of a :ref:`CanvasLayer`. .. rst-class:: classref-item-separator @@ -1055,7 +1077,7 @@ void **area_attach_canvas_instance_id** **(** :ref:`RID` area, :ref:` void **area_attach_object_instance_id** **(** :ref:`RID` area, :ref:`int` id **)** -Assigns the area to a descendant of :ref:`Object`, so it can exist in the node tree. +Attaches the ``ObjectID`` of an :ref:`Object` to the area. Use :ref:`Object.get_instance_id` to get the ``ObjectID`` of a :ref:`CollisionObject2D`. .. rst-class:: classref-item-separator @@ -1067,7 +1089,7 @@ Assigns the area to a descendant of :ref:`Object`, so it can exist void **area_clear_shapes** **(** :ref:`RID` area **)** -Removes all shapes from an area. It does not delete the shapes, so they can be reassigned later. +Removes all shapes from the area. This does not delete the shapes themselves, so they can continue to be used elsewhere or added back later. .. rst-class:: classref-item-separator @@ -1079,7 +1101,7 @@ Removes all shapes from an area. It does not delete the shapes, so they can be r :ref:`RID` **area_create** **(** **)** -Creates an :ref:`Area2D`. After creating an :ref:`Area2D` with this method, assign it to a space using :ref:`area_set_space` to use the created :ref:`Area2D` in the physics world. +Creates a 2D area object in the physics server, and returns the :ref:`RID` that identifies it. Use :ref:`area_add_shape` to add shapes to it, use :ref:`area_set_transform` to set its transform, and use :ref:`area_set_space` to add the area to a space. .. rst-class:: classref-item-separator @@ -1091,9 +1113,7 @@ Creates an :ref:`Area2D`. After creating an :ref:`Area2D` **area_get_canvas_instance_id** **(** :ref:`RID` area **)** |const| -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Returns the ``ObjectID`` of the canvas attached to the area. Use :ref:`@GlobalScope.instance_from_id` to retrieve a :ref:`CanvasLayer` from a nonzero ``ObjectID``. .. rst-class:: classref-item-separator @@ -1105,7 +1125,7 @@ Creates an :ref:`Area2D`. After creating an :ref:`Area2D` **area_get_collision_layer** **(** :ref:`RID` area **)** |const| -Returns the physics layer or layers an area belongs to. +Returns the physics layer or layers the area belongs to, as a bitmask. .. rst-class:: classref-item-separator @@ -1117,7 +1137,7 @@ Returns the physics layer or layers an area belongs to. :ref:`int` **area_get_collision_mask** **(** :ref:`RID` area **)** |const| -Returns the physics layer or layers an area can contact with. +Returns the physics layer or layers the area can contact with, as a bitmask. .. rst-class:: classref-item-separator @@ -1129,7 +1149,7 @@ Returns the physics layer or layers an area can contact with. :ref:`int` **area_get_object_instance_id** **(** :ref:`RID` area **)** |const| -Gets the instance ID of the object the area is assigned to. +Returns the ``ObjectID`` attached to the area. Use :ref:`@GlobalScope.instance_from_id` to retrieve an :ref:`Object` from a nonzero ``ObjectID``. .. rst-class:: classref-item-separator @@ -1141,7 +1161,7 @@ Gets the instance ID of the object the area is assigned to. :ref:`Variant` **area_get_param** **(** :ref:`RID` area, :ref:`AreaParameter` param **)** |const| -Returns an area parameter value. See :ref:`AreaParameter` for a list of available parameters. +Returns the value of the given area parameter. See :ref:`AreaParameter` for the list of available parameters. .. rst-class:: classref-item-separator @@ -1153,7 +1173,7 @@ Returns an area parameter value. See :ref:`AreaParameter` **area_get_shape** **(** :ref:`RID` area, :ref:`int` shape_idx **)** |const| -Returns the :ref:`RID` of the nth shape of an area. +Returns the :ref:`RID` of the shape with the given index in the area's array of shapes. .. rst-class:: classref-item-separator @@ -1165,7 +1185,7 @@ Returns the :ref:`RID` of the nth shape of an area. :ref:`int` **area_get_shape_count** **(** :ref:`RID` area **)** |const| -Returns the number of shapes assigned to an area. +Returns the number of shapes added to the area. .. rst-class:: classref-item-separator @@ -1177,7 +1197,7 @@ Returns the number of shapes assigned to an area. :ref:`Transform2D` **area_get_shape_transform** **(** :ref:`RID` area, :ref:`int` shape_idx **)** |const| -Returns the transform matrix of a shape within an area. +Returns the local transform matrix of the shape with the given index in the area's array of shapes. .. rst-class:: classref-item-separator @@ -1189,7 +1209,7 @@ Returns the transform matrix of a shape within an area. :ref:`RID` **area_get_space** **(** :ref:`RID` area **)** |const| -Returns the space assigned to the area. +Returns the :ref:`RID` of the space assigned to the area. Returns ``RID()`` if no space is assigned. .. rst-class:: classref-item-separator @@ -1201,7 +1221,7 @@ Returns the space assigned to the area. :ref:`Transform2D` **area_get_transform** **(** :ref:`RID` area **)** |const| -Returns the transform matrix for an area. +Returns the transform matrix of the area. .. rst-class:: classref-item-separator @@ -1213,7 +1233,7 @@ Returns the transform matrix for an area. void **area_remove_shape** **(** :ref:`RID` area, :ref:`int` shape_idx **)** -Removes a shape from an area. It does not delete the shape, so it can be reassigned later. +Removes the shape with the given index from the area's array of shapes. The shape itself is not deleted, so it can continue to be used elsewhere or added back later. As a result of this operation, the area's shapes which used to have indices higher than ``shape_idx`` will have their index decreased by one. .. rst-class:: classref-item-separator @@ -1225,9 +1245,19 @@ Removes a shape from an area. It does not delete the shape, so it can be reassig void **area_set_area_monitor_callback** **(** :ref:`RID` area, :ref:`Callable` callback **)** -.. container:: contribute +Sets the area's area monitor callback. This callback will be called when any other (shape of an) area enters or exits (a shape of) the given area, and must take the following five parameters: - There is currently no description for this method. Please help us by :ref:`contributing one `! +1. an integer ``status``: either :ref:`AREA_BODY_ADDED` or :ref:`AREA_BODY_REMOVED` depending on whether the other area's shape entered or exited the area, + +2. an :ref:`RID` ``area_rid``: the :ref:`RID` of the other area that entered or exited the area, + +3. an integer ``instance_id``: the ``ObjectID`` attached to the other area, + +4. an integer ``area_shape_idx``: the index of the shape of the other area that entered or exited the area, + +5. an integer ``self_shape_idx``: the index of the shape of the area where the other area entered or exited. + +By counting (or keeping track of) the shapes that enter and exit, it can be determined if an area (with all its shapes) is entering for the first time or exiting for the last time. .. rst-class:: classref-item-separator @@ -1239,7 +1269,7 @@ void **area_set_area_monitor_callback** **(** :ref:`RID` area, :ref:` void **area_set_collision_layer** **(** :ref:`RID` area, :ref:`int` layer **)** -Assigns the area to one or many physics layers. +Assigns the area to one or many physics layers, via a bitmask. .. rst-class:: classref-item-separator @@ -1251,7 +1281,7 @@ Assigns the area to one or many physics layers. void **area_set_collision_mask** **(** :ref:`RID` area, :ref:`int` mask **)** -Sets which physics layers the area will monitor. +Sets which physics layers the area will monitor, via a bitmask. .. rst-class:: classref-item-separator @@ -1263,17 +1293,19 @@ Sets which physics layers the area will monitor. void **area_set_monitor_callback** **(** :ref:`RID` area, :ref:`Callable` callback **)** -Sets the function to call when any body/area enters or exits the area. This callback will be called for any object interacting with the area, and takes five parameters: +Sets the area's body monitor callback. This callback will be called when any other (shape of a) body enters or exits (a shape of) the given area, and must take the following five parameters: -1: :ref:`AREA_BODY_ADDED` or :ref:`AREA_BODY_REMOVED`, depending on whether the object entered or exited the area. +1. an integer ``status``: either :ref:`AREA_BODY_ADDED` or :ref:`AREA_BODY_REMOVED` depending on whether the other body shape entered or exited the area, -2: :ref:`RID` of the object that entered/exited the area. +2. an :ref:`RID` ``body_rid``: the :ref:`RID` of the body that entered or exited the area, -3: Instance ID of the object that entered/exited the area. +3. an integer ``instance_id``: the ``ObjectID`` attached to the body, -4: The shape index of the object that entered/exited the area. +4. an integer ``body_shape_idx``: the index of the shape of the body that entered or exited the area, -5: The shape index of the area where the object entered/exited. +5. an integer ``self_shape_idx``: the index of the shape of the area where the body entered or exited. + +By counting (or keeping track of) the shapes that enter and exit, it can be determined if a body (with all its shapes) is entering for the first time or exiting for the last time. .. rst-class:: classref-item-separator @@ -1285,9 +1317,7 @@ Sets the function to call when any body/area enters or exits the area. This call void **area_set_monitorable** **(** :ref:`RID` area, :ref:`bool` monitorable **)** -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Sets whether the area is monitorable or not. If ``monitorable`` is ``true``, the area monitoring callback of other areas will be called when this area enters or exits them. .. rst-class:: classref-item-separator @@ -1299,7 +1329,7 @@ void **area_set_monitorable** **(** :ref:`RID` area, :ref:`bool` area, :ref:`AreaParameter` param, :ref:`Variant` value **)** -Sets the value for an area parameter. See :ref:`AreaParameter` for a list of available parameters. +Sets the value of the given area parameter. See :ref:`AreaParameter` for the list of available parameters. .. rst-class:: classref-item-separator @@ -1311,7 +1341,7 @@ Sets the value for an area parameter. See :ref:`AreaParameter` area, :ref:`int` shape_idx, :ref:`RID` shape **)** -Substitutes a given area shape by another. The old shape is selected by its index, the new one by its :ref:`RID`. +Replaces the area's shape at the given index by another shape, while not affecting the ``transform`` and ``disabled`` properties at the same index. .. rst-class:: classref-item-separator @@ -1323,7 +1353,7 @@ Substitutes a given area shape by another. The old shape is selected by its inde void **area_set_shape_disabled** **(** :ref:`RID` area, :ref:`int` shape_idx, :ref:`bool` disabled **)** -Disables a given shape in an area. +Sets the disabled property of the area's shape with the given index. If ``disabled`` is ``true``, then the shape will not detect any other shapes entering or exiting it. .. rst-class:: classref-item-separator @@ -1335,7 +1365,7 @@ Disables a given shape in an area. void **area_set_shape_transform** **(** :ref:`RID` area, :ref:`int` shape_idx, :ref:`Transform2D` transform **)** -Sets the transform matrix for an area shape. +Sets the local transform matrix of the area's shape with the given index. .. rst-class:: classref-item-separator @@ -1347,7 +1377,9 @@ Sets the transform matrix for an area shape. void **area_set_space** **(** :ref:`RID` area, :ref:`RID` space **)** -Assigns a space to the area. +Adds the area to the given space, after removing the area from the previously assigned space (if any). + +\ **Note:** To remove an area from a space without immediately adding it back elsewhere, use ``PhysicsServer2D.area_set_space(area, RID())``. .. rst-class:: classref-item-separator @@ -1359,7 +1391,7 @@ Assigns a space to the area. void **area_set_transform** **(** :ref:`RID` area, :ref:`Transform2D` transform **)** -Sets the transform matrix for an area. +Sets the transform matrix of the area. .. rst-class:: classref-item-separator @@ -1371,7 +1403,7 @@ Sets the transform matrix for an area. void **body_add_collision_exception** **(** :ref:`RID` body, :ref:`RID` excepted_body **)** -Adds a body to the list of bodies exempt from collisions. +Adds ``excepted_body`` to the body's list of collision exceptions, so that collisions with it are ignored. .. rst-class:: classref-item-separator @@ -1383,7 +1415,7 @@ Adds a body to the list of bodies exempt from collisions. void **body_add_constant_central_force** **(** :ref:`RID` body, :ref:`Vector2` force **)** -Adds a constant directional force without affecting rotation that keeps being applied over time until cleared with ``body_set_constant_force(body, Vector2(0, 0))``. +Adds a constant directional force to the body. The force does not affect rotation. The force remains applied over time until cleared with ``PhysicsServer2D.body_set_constant_force(body, Vector2(0, 0))``. This is equivalent to using :ref:`body_add_constant_force` at the body's center of mass. @@ -1397,7 +1429,7 @@ This is equivalent to using :ref:`body_add_constant_force` body, :ref:`Vector2` force, :ref:`Vector2` position=Vector2(0, 0) **)** -Adds a constant positioned force to the body that keeps being applied over time until cleared with ``body_set_constant_force(body, Vector2(0, 0))``. +Adds a constant positioned force to the body. The force can affect rotation if ``position`` is different from the body's center of mass. The force remains applied over time until cleared with ``PhysicsServer2D.body_set_constant_force(body, Vector2(0, 0))``. \ ``position`` is the offset from the body origin in global coordinates. @@ -1411,7 +1443,7 @@ Adds a constant positioned force to the body that keeps being applied over time void **body_add_constant_torque** **(** :ref:`RID` body, :ref:`float` torque **)** -Adds a constant rotational force without affecting position that keeps being applied over time until cleared with ``body_set_constant_torque(body, 0)``. +Adds a constant rotational force to the body. The force does not affect position. The force remains applied over time until cleared with ``PhysicsServer2D.body_set_constant_torque(body, 0)``. .. rst-class:: classref-item-separator @@ -1423,7 +1455,7 @@ Adds a constant rotational force without affecting position that keeps being app void **body_add_shape** **(** :ref:`RID` body, :ref:`RID` shape, :ref:`Transform2D` transform=Transform2D(1, 0, 0, 1, 0, 0), :ref:`bool` disabled=false **)** -Adds a shape to the body, along with a transform matrix. Shapes are usually referenced by their index, so you should track which shape has a given index. +Adds a shape to the area, with the given local transform. The shape (together with its ``transform`` and ``disabled`` properties) is added to an array of shapes, and the shapes of a body are usually referenced by their index in this array. .. rst-class:: classref-item-separator @@ -1435,7 +1467,7 @@ Adds a shape to the body, along with a transform matrix. Shapes are usually refe void **body_apply_central_force** **(** :ref:`RID` body, :ref:`Vector2` force **)** -Applies a directional force without affecting rotation. A force is time dependent and meant to be applied every physics update. +Applies a directional force to the body, at the body's center of mass. The force does not affect rotation. A force is time dependent and meant to be applied every physics update. This is equivalent to using :ref:`body_apply_force` at the body's center of mass. @@ -1449,7 +1481,7 @@ This is equivalent to using :ref:`body_apply_force` body, :ref:`Vector2` impulse **)** -Applies a directional impulse without affecting rotation. +Applies a directional impulse to the body, at the body's center of mass. The impulse does not affect rotation. An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason, it should only be used when simulating one-time impacts (use the "_force" functions otherwise). @@ -1465,7 +1497,7 @@ This is equivalent to using :ref:`body_apply_impulse` body, :ref:`Vector2` force, :ref:`Vector2` position=Vector2(0, 0) **)** -Applies a positioned force to the body. A force is time dependent and meant to be applied every physics update. +Applies a positioned force to the body. The force can affect rotation if ``position`` is different from the body's center of mass. A force is time dependent and meant to be applied every physics update. \ ``position`` is the offset from the body origin in global coordinates. @@ -1479,7 +1511,7 @@ Applies a positioned force to the body. A force is time dependent and meant to b void **body_apply_impulse** **(** :ref:`RID` body, :ref:`Vector2` impulse, :ref:`Vector2` position=Vector2(0, 0) **)** -Applies a positioned impulse to the body. +Applies a positioned impulse to the body. The impulse can affect rotation if ``position`` is different from the body's center of mass. An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason, it should only be used when simulating one-time impacts (use the "_force" functions otherwise). @@ -1495,7 +1527,7 @@ An impulse is time-independent! Applying an impulse every frame would result in void **body_apply_torque** **(** :ref:`RID` body, :ref:`float` torque **)** -Applies a rotational force without affecting position. A force is time dependent and meant to be applied every physics update. +Applies a rotational force to the body. The force does not affect position. A force is time dependent and meant to be applied every physics update. .. rst-class:: classref-item-separator @@ -1507,7 +1539,7 @@ Applies a rotational force without affecting position. A force is time dependent void **body_apply_torque_impulse** **(** :ref:`RID` body, :ref:`float` impulse **)** -Applies a rotational impulse to the body without affecting the position. +Applies a rotational impulse to the body. The impulse does not affect position. An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason, it should only be used when simulating one-time impacts (use the "_force" functions otherwise). @@ -1521,9 +1553,7 @@ An impulse is time-independent! Applying an impulse every frame would result in void **body_attach_canvas_instance_id** **(** :ref:`RID` body, :ref:`int` id **)** -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Attaches the ``ObjectID`` of a canvas to the body. Use :ref:`Object.get_instance_id` to get the ``ObjectID`` of a :ref:`CanvasLayer`. .. rst-class:: classref-item-separator @@ -1535,7 +1565,7 @@ void **body_attach_canvas_instance_id** **(** :ref:`RID` body, :ref:` void **body_attach_object_instance_id** **(** :ref:`RID` body, :ref:`int` id **)** -Assigns the area to a descendant of :ref:`Object`, so it can exist in the node tree. +Attaches the ``ObjectID`` of an :ref:`Object` to the body. Use :ref:`Object.get_instance_id` to get the ``ObjectID`` of a :ref:`CollisionObject2D`. .. rst-class:: classref-item-separator @@ -1547,7 +1577,7 @@ Assigns the area to a descendant of :ref:`Object`, so it can exist void **body_clear_shapes** **(** :ref:`RID` body **)** -Removes all shapes from a body. +Removes all shapes from the body. This does not delete the shapes themselves, so they can continue to be used elsewhere or added back later. .. rst-class:: classref-item-separator @@ -1559,7 +1589,7 @@ Removes all shapes from a body. :ref:`RID` **body_create** **(** **)** -Creates a physics body. +Creates a 2D body object in the physics server, and returns the :ref:`RID` that identifies it. Use :ref:`body_add_shape` to add shapes to it, use :ref:`body_set_state` to set its transform, and use :ref:`body_set_space` to add the body to a space. .. rst-class:: classref-item-separator @@ -1571,9 +1601,7 @@ Creates a physics body. :ref:`int` **body_get_canvas_instance_id** **(** :ref:`RID` body **)** |const| -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Returns the ``ObjectID`` of the canvas attached to the body. Use :ref:`@GlobalScope.instance_from_id` to retrieve a :ref:`CanvasLayer` from a nonzero ``ObjectID``. .. rst-class:: classref-item-separator @@ -1585,7 +1613,7 @@ Creates a physics body. :ref:`int` **body_get_collision_layer** **(** :ref:`RID` body **)** |const| -Returns the physics layer or layers a body belongs to. +Returns the physics layer or layers the body belongs to, as a bitmask. .. rst-class:: classref-item-separator @@ -1597,7 +1625,7 @@ Returns the physics layer or layers a body belongs to. :ref:`int` **body_get_collision_mask** **(** :ref:`RID` body **)** |const| -Returns the physics layer or layers a body can collide with. +Returns the physics layer or layers the body can collide with, as a bitmask. .. rst-class:: classref-item-separator @@ -1609,7 +1637,7 @@ Returns the physics layer or layers a body can collide with. :ref:`float` **body_get_collision_priority** **(** :ref:`RID` body **)** |const| -Returns the body's collision priority. +Returns the body's collision priority. This is used in the depenetration phase of :ref:`body_test_motion`. The higher the priority is, the lower the penetration into the body will be. .. rst-class:: classref-item-separator @@ -1621,7 +1649,7 @@ Returns the body's collision priority. :ref:`Vector2` **body_get_constant_force** **(** :ref:`RID` body **)** |const| -Returns the body's total constant positional forces applied during each physics update. +Returns the body's total constant positional force applied during each physics update. See :ref:`body_add_constant_force` and :ref:`body_add_constant_central_force`. @@ -1635,7 +1663,7 @@ See :ref:`body_add_constant_force` **body_get_constant_torque** **(** :ref:`RID` body **)** |const| -Returns the body's total constant rotational forces applied during each physics update. +Returns the body's total constant rotational force applied during each physics update. See :ref:`body_add_constant_torque`. @@ -1649,7 +1677,7 @@ See :ref:`body_add_constant_torque` **body_get_continuous_collision_detection_mode** **(** :ref:`RID` body **)** |const| -Returns the continuous collision detection mode. +Returns the body's continuous collision detection mode (see :ref:`CCDMode`). .. rst-class:: classref-item-separator @@ -1661,7 +1689,7 @@ Returns the continuous collision detection mode. :ref:`PhysicsDirectBodyState2D` **body_get_direct_state** **(** :ref:`RID` body **)** -Returns the :ref:`PhysicsDirectBodyState2D` of the body. Returns ``null`` if the body is destroyed or removed from the physics space. +Returns the :ref:`PhysicsDirectBodyState2D` of the body. Returns ``null`` if the body is destroyed or not assigned to a space. .. rst-class:: classref-item-separator @@ -1673,7 +1701,7 @@ Returns the :ref:`PhysicsDirectBodyState2D` of t :ref:`int` **body_get_max_contacts_reported** **(** :ref:`RID` body **)** |const| -Returns the maximum contacts that can be reported. See :ref:`body_set_max_contacts_reported`. +Returns the maximum number of contacts that the body can report. See :ref:`body_set_max_contacts_reported`. .. rst-class:: classref-item-separator @@ -1685,7 +1713,7 @@ Returns the maximum contacts that can be reported. See :ref:`body_set_max_contac :ref:`BodyMode` **body_get_mode** **(** :ref:`RID` body **)** |const| -Returns the body mode. +Returns the body's mode (see :ref:`BodyMode`). .. rst-class:: classref-item-separator @@ -1697,7 +1725,7 @@ Returns the body mode. :ref:`int` **body_get_object_instance_id** **(** :ref:`RID` body **)** |const| -Gets the instance ID of the object the area is assigned to. +Returns the ``ObjectID`` attached to the body. Use :ref:`@GlobalScope.instance_from_id` to retrieve an :ref:`Object` from a nonzero ``ObjectID``. .. rst-class:: classref-item-separator @@ -1709,7 +1737,7 @@ Gets the instance ID of the object the area is assigned to. :ref:`Variant` **body_get_param** **(** :ref:`RID` body, :ref:`BodyParameter` param **)** |const| -Returns the value of a body parameter. See :ref:`BodyParameter` for a list of available parameters. +Returns the value of the given body parameter. See :ref:`BodyParameter` for the list of available parameters. .. rst-class:: classref-item-separator @@ -1721,7 +1749,7 @@ Returns the value of a body parameter. See :ref:`BodyParameter` **body_get_shape** **(** :ref:`RID` body, :ref:`int` shape_idx **)** |const| -Returns the :ref:`RID` of the nth shape of a body. +Returns the :ref:`RID` of the shape with the given index in the body's array of shapes. .. rst-class:: classref-item-separator @@ -1733,7 +1761,7 @@ Returns the :ref:`RID` of the nth shape of a body. :ref:`int` **body_get_shape_count** **(** :ref:`RID` body **)** |const| -Returns the number of shapes assigned to a body. +Returns the number of shapes added to the body. .. rst-class:: classref-item-separator @@ -1745,7 +1773,7 @@ Returns the number of shapes assigned to a body. :ref:`Transform2D` **body_get_shape_transform** **(** :ref:`RID` body, :ref:`int` shape_idx **)** |const| -Returns the transform matrix of a body shape. +Returns the local transform matrix of the shape with the given index in the area's array of shapes. .. rst-class:: classref-item-separator @@ -1757,7 +1785,7 @@ Returns the transform matrix of a body shape. :ref:`RID` **body_get_space** **(** :ref:`RID` body **)** |const| -Returns the :ref:`RID` of the space assigned to a body. +Returns the :ref:`RID` of the space assigned to the body. Returns ``RID()`` if no space is assigned. .. rst-class:: classref-item-separator @@ -1769,7 +1797,7 @@ Returns the :ref:`RID` of the space assigned to a body. :ref:`Variant` **body_get_state** **(** :ref:`RID` body, :ref:`BodyState` state **)** |const| -Returns a body state. +Returns the value of the given state of the body. See :ref:`BodyState` for the list of available states. .. rst-class:: classref-item-separator @@ -1781,7 +1809,7 @@ Returns a body state. :ref:`bool` **body_is_omitting_force_integration** **(** :ref:`RID` body **)** |const| -Returns whether a body uses a callback function to calculate its own physics (see :ref:`body_set_force_integration_callback`). +Returns ``true`` if the body uses a callback function to calculate its own physics (see :ref:`body_set_force_integration_callback`). .. rst-class:: classref-item-separator @@ -1793,7 +1821,7 @@ Returns whether a body uses a callback function to calculate its own physics (se void **body_remove_collision_exception** **(** :ref:`RID` body, :ref:`RID` excepted_body **)** -Removes a body from the list of bodies exempt from collisions. +Removes ``excepted_body`` from the body's list of collision exceptions, so that collisions with it are no longer ignored. .. rst-class:: classref-item-separator @@ -1805,7 +1833,7 @@ Removes a body from the list of bodies exempt from collisions. void **body_remove_shape** **(** :ref:`RID` body, :ref:`int` shape_idx **)** -Removes a shape from a body. The shape is not deleted, so it can be reused afterwards. +Removes the shape with the given index from the body's array of shapes. The shape itself is not deleted, so it can continue to be used elsewhere or added back later. As a result of this operation, the body's shapes which used to have indices higher than ``shape_idx`` will have their index decreased by one. .. rst-class:: classref-item-separator @@ -1817,7 +1845,7 @@ Removes a shape from a body. The shape is not deleted, so it can be reused after void **body_reset_mass_properties** **(** :ref:`RID` body **)** -Restores the default inertia and center of mass based on shapes to cancel any custom values previously set using :ref:`body_set_param`. +Restores the default inertia and center of mass of the body based on its shapes. This undoes any custom values previously set using :ref:`body_set_param`. .. rst-class:: classref-item-separator @@ -1829,7 +1857,7 @@ Restores the default inertia and center of mass based on shapes to cancel any cu void **body_set_axis_velocity** **(** :ref:`RID` body, :ref:`Vector2` axis_velocity **)** -Sets an axis velocity. The velocity in the given vector axis will be set as the given vector length. This is useful for jumping behavior. +Modifies the body's linear velocity so that its projection to the axis ``axis_velocity.normalized()`` is exactly ``axis_velocity.length()``. This is useful for jumping behavior. .. rst-class:: classref-item-separator @@ -1841,7 +1869,7 @@ Sets an axis velocity. The velocity in the given vector axis will be set as the void **body_set_collision_layer** **(** :ref:`RID` body, :ref:`int` layer **)** -Sets the physics layer or layers a body belongs to. +Sets the physics layer or layers the body belongs to, via a bitmask. .. rst-class:: classref-item-separator @@ -1853,7 +1881,7 @@ Sets the physics layer or layers a body belongs to. void **body_set_collision_mask** **(** :ref:`RID` body, :ref:`int` mask **)** -Sets the physics layer or layers a body can collide with. +Sets the physics layer or layers the body can collide with, via a bitmask. .. rst-class:: classref-item-separator @@ -1865,7 +1893,7 @@ Sets the physics layer or layers a body can collide with. void **body_set_collision_priority** **(** :ref:`RID` body, :ref:`float` priority **)** -Sets the body's collision priority. +Sets the body's collision priority. This is used in the depenetration phase of :ref:`body_test_motion`. The higher the priority is, the lower the penetration into the body will be. .. rst-class:: classref-item-separator @@ -1877,7 +1905,7 @@ Sets the body's collision priority. void **body_set_constant_force** **(** :ref:`RID` body, :ref:`Vector2` force **)** -Sets the body's total constant positional forces applied during each physics update. +Sets the body's total constant positional force applied during each physics update. See :ref:`body_add_constant_force` and :ref:`body_add_constant_central_force`. @@ -1891,7 +1919,7 @@ See :ref:`body_add_constant_force` body, :ref:`float` torque **)** -Sets the body's total constant rotational forces applied during each physics update. +Sets the body's total constant rotational force applied during each physics update. See :ref:`body_add_constant_torque`. @@ -1907,7 +1935,7 @@ void **body_set_continuous_collision_detection_mode** **(** :ref:`RID Sets the continuous collision detection mode using one of the :ref:`CCDMode` constants. -Continuous collision detection tries to predict where a moving body will collide, instead of moving it and correcting its movement if it collided. +Continuous collision detection tries to predict where a moving body would collide in between physics updates, instead of moving it and correcting its movement if it collided. .. rst-class:: classref-item-separator @@ -1919,13 +1947,15 @@ Continuous collision detection tries to predict where a moving body will collide void **body_set_force_integration_callback** **(** :ref:`RID` body, :ref:`Callable` callable, :ref:`Variant` userdata=null **)** -Sets the function used to calculate physics for an object, if that object allows it (see :ref:`body_set_omit_force_integration`). +Sets the function used to calculate physics for the body, if that body allows it (see :ref:`body_set_omit_force_integration`). -The force integration function takes 2 arguments: +The force integration function takes the following two parameters: -\ ``state:`` :ref:`PhysicsDirectBodyState2D` used to retrieve and modify the body's state. +1. a :ref:`PhysicsDirectBodyState2D` ``state``: used to retrieve and modify the body's state, -\ ``userdata:`` Optional user data, if it was passed when calling ``body_set_force_integration_callback``. +2. a :ref:`Variant` ``userdata``: optional user data. + +\ **Note:** This callback is currently not called in Godot Physics. .. rst-class:: classref-item-separator @@ -1937,7 +1967,7 @@ The force integration function takes 2 arguments: void **body_set_max_contacts_reported** **(** :ref:`RID` body, :ref:`int` amount **)** -Sets the maximum contacts to report. Bodies can keep a log of the contacts with other bodies. This is enabled by setting the maximum number of contacts reported to a number greater than 0. +Sets the maximum number of contacts that the body can report. If ``amount`` is greater than zero, then the body will keep track of at most this many contacts with other bodies. .. rst-class:: classref-item-separator @@ -1949,7 +1979,7 @@ Sets the maximum contacts to report. Bodies can keep a log of the contacts with void **body_set_mode** **(** :ref:`RID` body, :ref:`BodyMode` mode **)** -Sets the body mode using one of the :ref:`BodyMode` constants. +Sets the body's mode. See :ref:`BodyMode` for the list of available modes. .. rst-class:: classref-item-separator @@ -1961,7 +1991,7 @@ Sets the body mode using one of the :ref:`BodyMode` body, :ref:`bool` enable **)** -Sets whether a body uses a callback function to calculate its own physics (see :ref:`body_set_force_integration_callback`). +Sets whether the body uses a callback function to calculate its own physics (see :ref:`body_set_force_integration_callback`). .. rst-class:: classref-item-separator @@ -1973,7 +2003,7 @@ Sets whether a body uses a callback function to calculate its own physics (see : void **body_set_param** **(** :ref:`RID` body, :ref:`BodyParameter` param, :ref:`Variant` value **)** -Sets a body parameter. See :ref:`BodyParameter` for a list of available parameters. +Sets the value of the given body parameter. See :ref:`BodyParameter` for the list of available parameters. .. rst-class:: classref-item-separator @@ -1985,7 +2015,7 @@ Sets a body parameter. See :ref:`BodyParameter` body, :ref:`int` shape_idx, :ref:`RID` shape **)** -Substitutes a given body shape by another. The old shape is selected by its index, the new one by its :ref:`RID`. +Replaces the body's shape at the given index by another shape, while not affecting the ``transform``, ``disabled``, and one-way collision properties at the same index. .. rst-class:: classref-item-separator @@ -1997,7 +2027,7 @@ Substitutes a given body shape by another. The old shape is selected by its inde void **body_set_shape_as_one_way_collision** **(** :ref:`RID` body, :ref:`int` shape_idx, :ref:`bool` enable, :ref:`float` margin **)** -Enables one way collision on body if ``enable`` is ``true``. +Sets the one-way collision properties of the body's shape with the given index. If ``enable`` is ``true``, the one-way collision direction given by the shape's local upward axis ``body_get_shape_transform(body, shape_idx).y`` will be used to ignore collisions with the shape in the opposite direction, and to ensure depenetration of kinematic bodies happens in this direction. .. rst-class:: classref-item-separator @@ -2009,7 +2039,7 @@ Enables one way collision on body if ``enable`` is ``true``. void **body_set_shape_disabled** **(** :ref:`RID` body, :ref:`int` shape_idx, :ref:`bool` disabled **)** -Disables shape in body if ``disabled`` is ``true``. +Sets the disabled property of the body's shape with the given index. If ``disabled`` is ``true``, then the shape will be ignored in all collision detection. .. rst-class:: classref-item-separator @@ -2021,7 +2051,7 @@ Disables shape in body if ``disabled`` is ``true``. void **body_set_shape_transform** **(** :ref:`RID` body, :ref:`int` shape_idx, :ref:`Transform2D` transform **)** -Sets the transform matrix for a body shape. +Sets the local transform matrix of the body's shape with the given index. .. rst-class:: classref-item-separator @@ -2033,7 +2063,13 @@ Sets the transform matrix for a body shape. void **body_set_space** **(** :ref:`RID` body, :ref:`RID` space **)** -Assigns a space to the body (see :ref:`space_create`). +Adds the body to the given space, after removing the body from the previously assigned space (if any). If the body's mode is set to :ref:`BODY_MODE_RIGID`, then adding the body to a space will have the following additional effects: + +- If the parameter :ref:`BODY_PARAM_CENTER_OF_MASS` has never been set explicitly, then the value of that parameter will be recalculated based on the body's shapes. + +- If the parameter :ref:`BODY_PARAM_INERTIA` is set to a value ``<= 0.0``, then the value of that parameter will be recalculated based on the body's shapes, mass, and center of mass. + +\ **Note:** To remove a body from a space without immediately adding it back elsewhere, use ``PhysicsServer2D.body_set_space(body, RID())``. .. rst-class:: classref-item-separator @@ -2045,9 +2081,9 @@ Assigns a space to the body (see :ref:`space_create` body, :ref:`BodyState` state, :ref:`Variant` value **)** -Sets a body state using one of the :ref:`BodyState` constants. +Sets the value of a body's state. See :ref:`BodyState` for the list of available states. -Note that the method doesn't take effect immediately. The state will change on the next physics frame. +\ **Note:** The state change doesn't take effect immediately. The state will change on the next physics frame. .. rst-class:: classref-item-separator @@ -2059,7 +2095,7 @@ Note that the method doesn't take effect immediately. The state will change on t :ref:`bool` **body_test_motion** **(** :ref:`RID` body, :ref:`PhysicsTestMotionParameters2D` parameters, :ref:`PhysicsTestMotionResult2D` result=null **)** -Returns ``true`` if a collision would result from moving along a motion vector from a given point in space. :ref:`PhysicsTestMotionParameters2D` is passed to set motion parameters. :ref:`PhysicsTestMotionResult2D` can be passed to return additional information. +Returns ``true`` if a collision would result from moving the body along a motion vector from a given point in space. See :ref:`PhysicsTestMotionParameters2D` for the available motion parameters. Optionally a :ref:`PhysicsTestMotionResult2D` object can be passed, which will be used to store the information about the resulting collision. .. rst-class:: classref-item-separator @@ -2071,9 +2107,7 @@ Returns ``true`` if a collision would result from moving along a motion vector f :ref:`RID` **capsule_shape_create** **(** **)** -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Creates a 2D capsule shape in the physics server, and returns the :ref:`RID` that identifies it. Use :ref:`shape_set_data` to set the capsule's height and radius. .. rst-class:: classref-item-separator @@ -2085,9 +2119,7 @@ Returns ``true`` if a collision would result from moving along a motion vector f :ref:`RID` **circle_shape_create** **(** **)** -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Creates a 2D circle shape in the physics server, and returns the :ref:`RID` that identifies it. Use :ref:`shape_set_data` to set the circle's radius. .. rst-class:: classref-item-separator @@ -2099,9 +2131,7 @@ Returns ``true`` if a collision would result from moving along a motion vector f :ref:`RID` **concave_polygon_shape_create** **(** **)** -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Creates a 2D concave polygon shape in the physics server, and returns the :ref:`RID` that identifies it. Use :ref:`shape_set_data` to set the concave polygon's segments. .. rst-class:: classref-item-separator @@ -2113,9 +2143,7 @@ Returns ``true`` if a collision would result from moving along a motion vector f :ref:`RID` **convex_polygon_shape_create** **(** **)** -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Creates a 2D convex polygon shape in the physics server, and returns the :ref:`RID` that identifies it. Use :ref:`shape_set_data` to set the convex polygon's points. .. rst-class:: classref-item-separator @@ -2127,7 +2155,7 @@ Returns ``true`` if a collision would result from moving along a motion vector f :ref:`float` **damped_spring_joint_get_param** **(** :ref:`RID` joint, :ref:`DampedSpringParam` param **)** |const| -Returns the value of a damped spring joint parameter. See :ref:`DampedSpringParam` for a list of available parameters. +Returns the value of the given damped spring joint parameter. See :ref:`DampedSpringParam` for the list of available parameters. .. rst-class:: classref-item-separator @@ -2139,7 +2167,7 @@ Returns the value of a damped spring joint parameter. See :ref:`DampedSpringPara void **damped_spring_joint_set_param** **(** :ref:`RID` joint, :ref:`DampedSpringParam` param, :ref:`float` value **)** -Sets a damped spring joint parameter. See :ref:`DampedSpringParam` for a list of available parameters. +Sets the value of the given damped spring joint parameter. See :ref:`DampedSpringParam` for the list of available parameters. .. rst-class:: classref-item-separator @@ -2151,7 +2179,7 @@ Sets a damped spring joint parameter. See :ref:`DampedSpringParam` rid **)** -Destroys any of the objects created by PhysicsServer2D. If the :ref:`RID` passed is not one of the objects that can be created by PhysicsServer2D, an error will be sent to the console. +Destroys any of the objects created by PhysicsServer2D. If the :ref:`RID` passed is not one of the objects that can be created by PhysicsServer2D, an error will be printed to the console. .. rst-class:: classref-item-separator @@ -2163,7 +2191,7 @@ Destroys any of the objects created by PhysicsServer2D. If the :ref:`RID` **get_process_info** **(** :ref:`ProcessInfo` process_info **)** -Returns information about the current state of the 2D physics engine. See :ref:`ProcessInfo` for a list of available states. +Returns information about the current state of the 2D physics engine. See :ref:`ProcessInfo` for the list of available states. .. rst-class:: classref-item-separator @@ -2175,9 +2203,7 @@ Returns information about the current state of the 2D physics engine. See :ref:` void **joint_clear** **(** :ref:`RID` joint **)** -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Destroys the joint with the given :ref:`RID`, creates a new uninitialized joint, and makes the :ref:`RID` refer to this new joint. .. rst-class:: classref-item-separator @@ -2189,9 +2215,7 @@ void **joint_clear** **(** :ref:`RID` joint **)** :ref:`RID` **joint_create** **(** **)** -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Creates a 2D joint in the physics server, and returns the :ref:`RID` that identifies it. To set the joint type, use :ref:`joint_make_damped_spring`, :ref:`joint_make_groove` or :ref:`joint_make_pin`. Use :ref:`joint_set_param` to set generic joint parameters. .. rst-class:: classref-item-separator @@ -2215,7 +2239,7 @@ Sets whether the bodies attached to the :ref:`Joint2D` will colli :ref:`float` **joint_get_param** **(** :ref:`RID` joint, :ref:`JointParam` param **)** |const| -Returns the value of a joint parameter. +Returns the value of the given joint parameter. See :ref:`JointParam` for the list of available parameters. .. rst-class:: classref-item-separator @@ -2227,7 +2251,7 @@ Returns the value of a joint parameter. :ref:`JointType` **joint_get_type** **(** :ref:`RID` joint **)** |const| -Returns a joint's type (see :ref:`JointType`). +Returns the joint's type (see :ref:`JointType`). .. rst-class:: classref-item-separator @@ -2251,9 +2275,7 @@ Returns whether the bodies attached to the :ref:`Joint2D` will co void **joint_make_damped_spring** **(** :ref:`RID` joint, :ref:`Vector2` anchor_a, :ref:`Vector2` anchor_b, :ref:`RID` body_a, :ref:`RID` body_b **)** -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Makes the joint a damped spring joint, attached at the point ``anchor_a`` (given in global coordinates) on the body ``body_a`` and at the point ``anchor_b`` (given in global coordinates) on the body ``body_b``. To set the parameters which are specific to the damped spring, see :ref:`damped_spring_joint_set_param`. .. rst-class:: classref-item-separator @@ -2265,9 +2287,7 @@ void **joint_make_damped_spring** **(** :ref:`RID` joint, :ref:`Vecto void **joint_make_groove** **(** :ref:`RID` joint, :ref:`Vector2` groove1_a, :ref:`Vector2` groove2_a, :ref:`Vector2` anchor_b, :ref:`RID` body_a, :ref:`RID` body_b **)** -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Makes the joint a groove joint. .. rst-class:: classref-item-separator @@ -2279,9 +2299,7 @@ void **joint_make_groove** **(** :ref:`RID` joint, :ref:`Vector2` joint, :ref:`Vector2` anchor, :ref:`RID` body_a, :ref:`RID` body_b **)** -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Makes the joint a pin joint. If ``body_b`` is ``RID()``, then ``body_a`` is pinned to the point ``anchor`` (given in global coordinates); otherwise, ``body_a`` is pinned to ``body_b`` at the point ``anchor`` (given in global coordinates). To set the parameters which are specific to the pin joint, see :ref:`pin_joint_set_param`. .. rst-class:: classref-item-separator @@ -2293,7 +2311,7 @@ void **joint_make_pin** **(** :ref:`RID` joint, :ref:`Vector2` joint, :ref:`JointParam` param, :ref:`float` value **)** -Sets a joint parameter. See :ref:`JointParam` for a list of available parameters. +Sets the value of the given joint parameter. See :ref:`JointParam` for the list of available parameters. .. rst-class:: classref-item-separator @@ -2329,9 +2347,7 @@ Sets a pin joint parameter. See :ref:`PinJointParam` **rectangle_shape_create** **(** **)** -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Creates a 2D rectangle shape in the physics server, and returns the :ref:`RID` that identifies it. Use :ref:`shape_set_data` to set the rectangle's half-extents. .. rst-class:: classref-item-separator @@ -2343,9 +2359,7 @@ Sets a pin joint parameter. See :ref:`PinJointParam` **segment_shape_create** **(** **)** -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Creates a 2D segment shape in the physics server, and returns the :ref:`RID` that identifies it. Use :ref:`shape_set_data` to set the segment's start and end points. .. rst-class:: classref-item-separator @@ -2357,9 +2371,7 @@ Sets a pin joint parameter. See :ref:`PinJointParam` **separation_ray_shape_create** **(** **)** -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Creates a 2D separation ray shape in the physics server, and returns the :ref:`RID` that identifies it. Use :ref:`shape_set_data` to set the shape's ``length`` and ``slide_on_slope`` properties. .. rst-class:: classref-item-separator @@ -2371,7 +2383,7 @@ Sets a pin joint parameter. See :ref:`PinJointParam` active **)** -Activates or deactivates the 2D physics engine. +Activates or deactivates the 2D physics server. If ``active`` is ``false``, then the physics server will not do anything in its physics step. .. rst-class:: classref-item-separator @@ -2383,7 +2395,7 @@ Activates or deactivates the 2D physics engine. :ref:`Variant` **shape_get_data** **(** :ref:`RID` shape **)** |const| -Returns the shape data. +Returns the shape data that defines the configuration of the shape, such as the half-extents of a rectangle or the segments of a concave shape. See :ref:`shape_set_data` for the precise format of this data in each case. .. rst-class:: classref-item-separator @@ -2395,7 +2407,7 @@ Returns the shape data. :ref:`ShapeType` **shape_get_type** **(** :ref:`RID` shape **)** |const| -Returns a shape's type (see :ref:`ShapeType`). +Returns the shape's type (see :ref:`ShapeType`). .. rst-class:: classref-item-separator @@ -2407,7 +2419,25 @@ Returns a shape's type (see :ref:`ShapeType`). void **shape_set_data** **(** :ref:`RID` shape, :ref:`Variant` data **)** -Sets the shape data that defines its shape and size. The data to be passed depends on the kind of shape created :ref:`shape_get_type`. +Sets the shape data that defines the configuration of the shape. The ``data`` to be passed depends on the shape's type (see :ref:`shape_get_type`): + +- :ref:`SHAPE_WORLD_BOUNDARY`: an array of length two containing a :ref:`Vector2` ``normal`` direction and a ``float`` distance ``d``, + +- :ref:`SHAPE_SEPARATION_RAY`: a dictionary containing the key ``length`` with a ``float`` value and the key ``slide_on_slope`` with a ``bool`` value, + +- :ref:`SHAPE_SEGMENT`: a :ref:`Rect2` ``rect`` containing the first point of the segment in ``rect.position`` and the second point of the segment in ``rect.size``, + +- :ref:`SHAPE_CIRCLE`: a ``float`` ``radius``, + +- :ref:`SHAPE_RECTANGLE`: a :ref:`Vector2` ``half_extents``, + +- :ref:`SHAPE_CAPSULE`: an array of length two (or a :ref:`Vector2`) containing a ``float`` ``height`` and a ``float`` ``radius``, + +- :ref:`SHAPE_CONVEX_POLYGON`: either a :ref:`PackedVector2Array` of points defining a convex polygon in counterclockwise order (the clockwise outward normal of each segment formed by consecutive points is calculated internally), or a :ref:`PackedFloat32Array` of length divisible by four so that every 4-tuple of ``float``\ s contains the coordinates of a point followed by the coordinates of the clockwise outward normal vector to the segment between the current point and the next point, + +- :ref:`SHAPE_CONCAVE_POLYGON`: a :ref:`PackedVector2Array` of length divisible by two (each pair of points forms one segment). + +\ **Warning**: In the case of :ref:`SHAPE_CONVEX_POLYGON`, this method does not check if the points supplied actually form a convex polygon (unlike the :ref:`CollisionPolygon2D.polygon` property). .. rst-class:: classref-item-separator @@ -2419,7 +2449,7 @@ Sets the shape data that defines its shape and size. The data to be passed depen :ref:`RID` **space_create** **(** **)** -Creates a space. A space is a collection of parameters for the physics engine that can be assigned to an area or a body. It can be assigned to an area with :ref:`area_set_space`, or to a body with :ref:`body_set_space`. +Creates a 2D space in the physics server, and returns the :ref:`RID` that identifies it. A space contains bodies and areas, and controls the stepping of the physics simulation of the objects in it. .. rst-class:: classref-item-separator @@ -2431,7 +2461,7 @@ Creates a space. A space is a collection of parameters for the physics engine th :ref:`PhysicsDirectSpaceState2D` **space_get_direct_state** **(** :ref:`RID` space **)** -Returns the state of a space, a :ref:`PhysicsDirectSpaceState2D`. This object can be used to make collision/intersection queries. +Returns the state of a space, a :ref:`PhysicsDirectSpaceState2D`. This object can be used for collision/intersection queries. .. rst-class:: classref-item-separator @@ -2443,7 +2473,7 @@ Returns the state of a space, a :ref:`PhysicsDirectSpaceState2D` **space_get_param** **(** :ref:`RID` space, :ref:`SpaceParameter` param **)** |const| -Returns the value of a space parameter. +Returns the value of the given space parameter. See :ref:`SpaceParameter` for the list of available parameters. .. rst-class:: classref-item-separator @@ -2455,7 +2485,7 @@ Returns the value of a space parameter. :ref:`bool` **space_is_active** **(** :ref:`RID` space **)** |const| -Returns whether the space is active. +Returns ``true`` if the space is active. .. rst-class:: classref-item-separator @@ -2467,7 +2497,7 @@ Returns whether the space is active. void **space_set_active** **(** :ref:`RID` space, :ref:`bool` active **)** -Marks a space as active. It will not have an effect, unless it is assigned to an area or body. +Activates or deactivates the space. If ``active`` is ``false``, then the physics server will not do anything with this space in its physics step. .. rst-class:: classref-item-separator @@ -2479,7 +2509,7 @@ Marks a space as active. It will not have an effect, unless it is assigned to an void **space_set_param** **(** :ref:`RID` space, :ref:`SpaceParameter` param, :ref:`float` value **)** -Sets the value for a space parameter. See :ref:`SpaceParameter` for a list of available parameters. +Sets the value of the given space parameter. See :ref:`SpaceParameter` for the list of available parameters. .. rst-class:: classref-item-separator @@ -2491,9 +2521,7 @@ Sets the value for a space parameter. See :ref:`SpaceParameter` **world_boundary_shape_create** **(** **)** -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Creates a 2D world boundary shape in the physics server, and returns the :ref:`RID` that identifies it. Use :ref:`shape_set_data` to set the shape's normal direction and distance properties. .. |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_pointlight2d.rst b/classes/class_pointlight2d.rst index 2cb36c393..5e3b4e91c 100644 --- a/classes/class_pointlight2d.rst +++ b/classes/class_pointlight2d.rst @@ -19,7 +19,7 @@ Positional 2D light source. Description ----------- -Casts light in a 2D environment. This light's shape is defined by a (usually grayscale) texture +Casts light in a 2D environment. This light's shape is defined by a (usually grayscale) texture. .. rst-class:: classref-introduction-group diff --git a/classes/class_projectsettings.rst b/classes/class_projectsettings.rst index 261c3c258..b7af4cd30 100644 --- a/classes/class_projectsettings.rst +++ b/classes/class_projectsettings.rst @@ -197,8 +197,6 @@ Properties +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`debug/gdscript/warnings/static_called_on_instance` | ``1`` | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`debug/gdscript/warnings/treat_warnings_as_errors` | ``false`` | - +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`debug/gdscript/warnings/unassigned_variable` | ``1`` | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`debug/gdscript/warnings/unassigned_variable_op_assign` | ``1`` | @@ -2361,18 +2359,6 @@ When set to ``warn`` or ``error``, produces a warning or an error respectively w ---- -.. _class_ProjectSettings_property_debug/gdscript/warnings/treat_warnings_as_errors: - -.. rst-class:: classref-property - -:ref:`bool` **debug/gdscript/warnings/treat_warnings_as_errors** = ``false`` - -If ``true``, all warnings will be reported as if they are errors. - -.. rst-class:: classref-item-separator - ----- - .. _class_ProjectSettings_property_debug/gdscript/warnings/unassigned_variable: .. rst-class:: classref-property @@ -3263,7 +3249,9 @@ Sets the V-Sync mode for the main game window. See :ref:`VSyncMode` for possible values and how they affect the behavior of your application. -Depending on the platform and used renderer, the engine will fall back to ``Enabled`` if the desired mode is not supported. +Depending on the platform and used renderer, the engine will fall back to **Enabled** if the desired mode is not supported. + +\ **Note:** V-Sync modes other than **Enabled** are only supported in the Forward+ and Mobile rendering methods, not Compatibility. \ **Note:** This property is only read when the project starts. To change the V-Sync mode at runtime, call :ref:`DisplayServer.window_set_vsync_mode` instead. @@ -3621,7 +3609,7 @@ Path to a custom :ref:`Font` resource to use as default for all GUI :ref:`int` **gui/theme/default_font_antialiasing** = ``1`` -Font anti-aliasing mode. See :ref:`FontFile.antialiasing`, +Font anti-aliasing mode. See :ref:`FontFile.antialiasing`. .. rst-class:: classref-item-separator @@ -4169,7 +4157,7 @@ macOS specific override for the shortcut to delete a word. :ref:`Dictionary` **input/ui_text_caret_add_above** -Default :ref:`InputEventAction` to add an additional caret above every caret of a text +Default :ref:`InputEventAction` to add an additional caret above every caret of a text. .. rst-class:: classref-item-separator @@ -4181,7 +4169,7 @@ Default :ref:`InputEventAction` to add an additional car :ref:`Dictionary` **input/ui_text_caret_add_above.macos** -macOS specific override for the shortcut to add a caret above every caret +macOS specific override for the shortcut to add a caret above every caret. .. rst-class:: classref-item-separator @@ -4193,7 +4181,7 @@ macOS specific override for the shortcut to add a caret above every caret :ref:`Dictionary` **input/ui_text_caret_add_below** -Default :ref:`InputEventAction` to add an additional caret below every caret of a text +Default :ref:`InputEventAction` to add an additional caret below every caret of a text. .. rst-class:: classref-item-separator @@ -4205,7 +4193,7 @@ Default :ref:`InputEventAction` to add an additional car :ref:`Dictionary` **input/ui_text_caret_add_below.macos** -macOS specific override for the shortcut to add a caret below every caret +macOS specific override for the shortcut to add a caret below every caret. .. rst-class:: classref-item-separator @@ -6907,7 +6895,7 @@ Optional name for the 3D render layer 13. If left empty, the layer will display :ref:`String` **layer_names/3d_render/layer_14** = ``""`` -Optional name for the 3D render layer 14. If left empty, the layer will display as "Layer 14" +Optional name for the 3D render layer 14. If left empty, the layer will display as "Layer 14". .. rst-class:: classref-item-separator @@ -7869,6 +7857,8 @@ The number of fixed iterations per second. This controls how often physics simul Sets the number of MSAA samples to use for 2D/Canvas rendering (as a power of two). MSAA is used to reduce aliasing around the edges of polygons. A higher MSAA value results in smoother edges but can be significantly slower on some hardware. This has no effect on shader-induced aliasing or texture aliasing. +\ **Note:** MSAA is only supported in the Forward+ and Mobile rendering methods, not Compatibility. + .. rst-class:: classref-item-separator ---- @@ -7881,6 +7871,8 @@ Sets the number of MSAA samples to use for 2D/Canvas rendering (as a power of tw Sets the number of MSAA samples to use for 3D rendering (as a power of two). MSAA is used to reduce aliasing around the edges of polygons. A higher MSAA value results in smoother edges but can be significantly slower on some hardware. See also bilinear scaling 3d :ref:`rendering/scaling_3d/mode` for supersampling, which provides higher quality but is much more expensive. This has no effect on shader-induced aliasing or texture aliasing. +\ **Note:** MSAA is only supported in the Forward+ and Mobile rendering methods, not Compatibility. + .. rst-class:: classref-item-separator ---- @@ -7895,6 +7887,8 @@ Sets the screen-space antialiasing mode for the default screen :ref:`Viewport`. +\ **Note:** Screen-space antialiasing is only supported in the Forward+ and Mobile rendering methods, not Compatibility. + .. rst-class:: classref-item-separator ---- @@ -7923,7 +7917,9 @@ In some cases, debanding may introduce a slightly noticeable dithering pattern. Enables Temporal Anti-Aliasing for the default screen :ref:`Viewport`. TAA works by jittering the camera and accumulating the images of the last rendered frames, motion vector rendering is used to account for camera and object motion. Enabling TAA can make the image blurrier, which is partially counteracted by automatically using a negative mipmap LOD bias (see :ref:`rendering/textures/default_filters/texture_mipmap_bias`). -\ **Note:** The implementation is not complete yet, some visual instances such as particles and skinned meshes may show artifacts. +\ **Note:** The implementation is not complete yet. Some visual instances such as particles and skinned meshes may show ghosting artifacts in motion. + +\ **Note:** TAA is only supported in the Forward+ rendering method, not Mobile or Compatibility. .. rst-class:: classref-item-separator @@ -7949,9 +7945,9 @@ Enables Temporal Anti-Aliasing for the default screen :ref:`Viewport` **rendering/anti_aliasing/screen_space_roughness_limiter/enabled** = ``true`` -.. container:: contribute +If ``true``, enables a spatial filter to limit roughness in areas with high-frequency detail. This can help reduce specular aliasing to an extent, though not as much as enabling :ref:`rendering/anti_aliasing/quality/use_taa`. This filter has a small performance cost, so consider disabling it if it doesn't benefit your scene noticeably. - There is currently no description for this property. Please help us by :ref:`contributing one `! +\ **Note:** TAA is only supported in the Forward+ and Mobile rendering methods, not Compatibility. .. rst-class:: classref-item-separator @@ -8027,7 +8023,7 @@ Disables :ref:`rendering/driver/depth_prepass/enable`. Setting this low will slightly reduce memory usage, may decrease shader compile times, and may result in faster rendering on low-end, mobile, or web devices. +\ **Note:** This setting is only effective when using the Compatibility rendering method, not Forward+ and Mobile. + .. rst-class:: classref-item-separator ---- @@ -8893,6 +8891,8 @@ Max number of omnilights and spotlights renderable per object. At the default va Max number of elements renderable in a frame. If more elements than this are visible per frame, they will not be drawn. Keep in mind elements refer to mesh surfaces and not meshes themselves. Setting this low will slightly reduce memory usage and may decrease shader compile times, particularly on web. For most uses, the default value is suitable, but consider lowering as much as possible on web export. +\ **Note:** This setting is only effective when using the Compatibility rendering method, not Forward+ and Mobile. + .. rst-class:: classref-item-separator ---- @@ -8905,6 +8905,8 @@ Max number of elements renderable in a frame. If more elements than this are vis Max number of positional lights renderable in a frame. If more lights than this number are used, they will be ignored. Setting this low will slightly reduce memory usage and may decrease shader compile times, particularly on web. For most uses, the default value is suitable, but consider lowering as much as possible on web export. +\ **Note:** This setting is only effective when using the Compatibility rendering method, not Forward+ and Mobile. + .. rst-class:: classref-item-separator ---- @@ -9301,7 +9303,9 @@ Determines how sharp the upscaled image will be when using the FSR upscaling mod :ref:`int` **rendering/scaling_3d/mode** = ``0`` -Sets the scaling 3D mode. Bilinear scaling renders at different resolution to either undersample or supersample the viewport. FidelityFX Super Resolution 1.0, abbreviated to FSR, is an upscaling technology that produces high quality images at fast framerates by using a spatially aware upscaling algorithm. FSR is slightly more expensive than bilinear, but it produces significantly higher image quality. FSR should be used where possible. +Sets the scaling 3D mode. Bilinear scaling renders at different resolution to either undersample or supersample the viewport. FidelityFX Super Resolution 1.0, abbreviated to FSR, is an upscaling technology that produces high quality images at fast framerates by using a spatially-aware upscaling algorithm. FSR is slightly more expensive than bilinear, but it produces significantly higher image quality. On particularly low-end GPUs, the added cost of FSR may not be worth it (compared to using bilinear scaling with a slightly higher resolution scale to match performance). + +\ **Note:** FSR is only effective when using the Forward+ rendering method, not Mobile or Compatibility. If using an incompatible rendering method, FSR will fall back to bilinear scaling. .. rst-class:: classref-item-separator @@ -9419,6 +9423,8 @@ Lower-end override for :ref:`rendering/shading/overrides/force_lambert_over_burl If ``true``, forces vertex shading for all rendering. This can increase performance a lot, but also reduces quality immensely. Can be used to optimize performance on low-end mobile devices. +\ **Note:** This setting currently has no effect, as vertex shading is not implemented yet. + .. rst-class:: classref-item-separator ---- @@ -9431,6 +9437,8 @@ If ``true``, forces vertex shading for all rendering. This can increase performa Lower-end override for :ref:`rendering/shading/overrides/force_vertex_shading` on mobile devices, due to performance concerns or driver support. +\ **Note:** This setting currently has no effect, as vertex shading is not implemented yet. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_reflectionprobe.rst b/classes/class_reflectionprobe.rst index d2cacd5fa..397cb5b93 100644 --- a/classes/class_reflectionprobe.rst +++ b/classes/class_reflectionprobe.rst @@ -25,6 +25,8 @@ The **ReflectionProbe** is used to create high-quality reflections at a low perf \ **Note:** Unlike :ref:`VoxelGI` and SDFGI, **ReflectionProbe**\ s only source their environment from a :ref:`WorldEnvironment` node. If you specify an :ref:`Environment` resource within a :ref:`Camera3D` node, it will be ignored by the **ReflectionProbe**. This can lead to incorrect lighting within the **ReflectionProbe**. +\ **Note:** Reflection probes are only supported in the Forward+ and Mobile rendering methods, not Compatibility. When using the Mobile rendering method, only 8 reflection probes can be displayed on each mesh resource. Attempting to display more than 8 reflection probes on a single mesh resource will result in reflection probes flickering in and out as the camera moves. + \ **Note:** When using the Mobile rendering method, reflection probes will only correctly affect meshes whose visibility AABB intersects with the reflection probe's AABB. If using a shader to deform the mesh in a way that makes it go outside its AABB, :ref:`GeometryInstance3D.extra_cull_margin` must be increased on the mesh. Otherwise, the reflection probe may not be visible on the mesh. .. rst-class:: classref-introduction-group diff --git a/classes/class_renderingdevice.rst b/classes/class_renderingdevice.rst index 7ef653132..f326a0eb8 100644 --- a/classes/class_renderingdevice.rst +++ b/classes/class_renderingdevice.rst @@ -27,7 +27,7 @@ Internally, **RenderingDevice** is used in Godot to provide support for several \ **Local RenderingDevices:** Using :ref:`RenderingServer.create_local_rendering_device`, you can create "secondary" rendering devices to perform drawing and GPU compute operations on separate threads. -\ **Note:** **RenderingDevice** is not available when running in headless mode or when using the OpenGL renderer. +\ **Note:** **RenderingDevice** is not available when running in headless mode or when using the Compatibility rendering method. .. rst-class:: classref-reftable-group @@ -42,7 +42,7 @@ Methods +------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`buffer_clear` **(** :ref:`RID` buffer, :ref:`int` offset, :ref:`int` size_bytes, :ref:`BarrierMask` post_barrier=7 **)** | +------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`PackedByteArray` | :ref:`buffer_get_data` **(** :ref:`RID` buffer **)** | + | :ref:`PackedByteArray` | :ref:`buffer_get_data` **(** :ref:`RID` buffer, :ref:`int` offset_bytes=0, :ref:`int` size_bytes=0 **)** | +------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`buffer_update` **(** :ref:`RID` buffer, :ref:`int` offset, :ref:`int` size_bytes, :ref:`PackedByteArray` data, :ref:`BarrierMask` post_barrier=7 **)** | +------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -4316,11 +4316,9 @@ void **barrier** **(** :ref:`BarrierMask` from .. rst-class:: classref-method -:ref:`PackedByteArray` **buffer_get_data** **(** :ref:`RID` buffer **)** +:ref:`PackedByteArray` **buffer_get_data** **(** :ref:`RID` buffer, :ref:`int` offset_bytes=0, :ref:`int` size_bytes=0 **)** -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Returns a copy of the data of the specified ``buffer``, optionally ``offset_bytes`` and ``size_bytes`` can be set to copy only a portion of the buffer. .. rst-class:: classref-item-separator diff --git a/classes/class_rigidbody2d.rst b/classes/class_rigidbody2d.rst index 765190c88..ce631ad44 100644 --- a/classes/class_rigidbody2d.rst +++ b/classes/class_rigidbody2d.rst @@ -616,6 +616,34 @@ The body's moment of inertia. This is like mass, but for rotation: it determines If set to ``0``, inertia is automatically computed (default value). +\ **Note:** This value does not change when inertia is automatically computed. Use :ref:`PhysicsServer2D` to get the computed inertia. + + +.. tabs:: + + .. code-tab:: gdscript + + @onready var ball = $Ball + + func get_ball_inertia(): + return 1.0 / PhysicsServer2D.body_get_direct_state(ball.get_rid()).inverse_inertia + + .. code-tab:: csharp + + private RigidBody2D _ball; + + public override void _Ready() + { + _ball = GetNode("Ball"); + } + + private float GetBallInertia() + { + return 1.0f / PhysicsServer2D.BodyGetDirectState(_ball.GetRid()).InverseInertia; + } + + + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_rigidbody3d.rst b/classes/class_rigidbody3d.rst index 08eb75bfb..6d47f40d4 100644 --- a/classes/class_rigidbody3d.rst +++ b/classes/class_rigidbody3d.rst @@ -586,6 +586,34 @@ The body's moment of inertia. This is like mass, but for rotation: it determines If set to ``Vector3.ZERO``, inertia is automatically computed (default value). +\ **Note:** This value does not change when inertia is automatically computed. Use :ref:`PhysicsServer3D` to get the computed inertia. + + +.. tabs:: + + .. code-tab:: gdscript + + @onready var ball = $Ball + + func get_ball_inertia(): + return PhysicsServer3D.body_get_direct_state(ball.get_rid()).inverse_inertia.inverse() + + .. code-tab:: csharp + + private RigidBody3D _ball; + + public override void _Ready() + { + _ball = GetNode("Ball"); + } + + private Vector3 GetBallInertia() + { + return PhysicsServer3D.BodyGetDirectState(_ball.GetRid()).InverseInertia.Inverse(); + } + + + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_skeleton3d.rst b/classes/class_skeleton3d.rst index c04e16e0c..8a8c3db45 100644 --- a/classes/class_skeleton3d.rst +++ b/classes/class_skeleton3d.rst @@ -703,7 +703,7 @@ Sets the global pose transform, ``pose``, for the bone at ``bone_idx``. \ ``amount`` is the interpolation strength that will be used when applying the pose, and ``persistent`` determines if the applied pose will remain. -\ **Note:** The pose transform needs to be a global pose! To convert a world transform from a :ref:`Node3D` to a global bone pose, multiply the :ref:`Transform3D.affine_inverse` of the node's :ref:`Node3D.global_transform` by the desired world transform +\ **Note:** The pose transform needs to be a global pose! To convert a world transform from a :ref:`Node3D` to a global bone pose, multiply the :ref:`Transform3D.affine_inverse` of the node's :ref:`Node3D.global_transform` by the desired world transform. .. rst-class:: classref-item-separator diff --git a/classes/class_spotlight3d.rst b/classes/class_spotlight3d.rst index ab3e6525b..02c17e0ad 100644 --- a/classes/class_spotlight3d.rst +++ b/classes/class_spotlight3d.rst @@ -21,6 +21,8 @@ Description A Spotlight is a type of :ref:`Light3D` node that emits lights in a specific direction, in the shape of a cone. The light is attenuated through the distance. This attenuation can be configured by changing the energy, radius and attenuation parameters of :ref:`Light3D`. +\ **Note:** When using the Mobile rendering method, only 8 spot lights can be displayed on each mesh resource. Attempting to display more than 8 spot lights on a single mesh resource will result in spot lights flickering in and out as the camera moves. When using the Compatibility rendering method, only 8 spot lights can be displayed on each mesh resource by default, but this can be increased by adjusting :ref:`ProjectSettings.rendering/limits/opengl/max_lights_per_object`. + \ **Note:** When using the Mobile or Compatibility rendering methods, spot lights will only correctly affect meshes whose visibility AABB intersects with the light's AABB. If using a shader to deform the mesh in a way that makes it go outside its AABB, :ref:`GeometryInstance3D.extra_cull_margin` must be increased on the mesh. Otherwise, the light may not be visible on the mesh. .. rst-class:: classref-introduction-group diff --git a/classes/class_streampeer.rst b/classes/class_streampeer.rst index d8e4f09c3..b8296519a 100644 --- a/classes/class_streampeer.rst +++ b/classes/class_streampeer.rst @@ -328,6 +328,8 @@ Gets an UTF-8 string with byte-length ``bytes`` from the stream (this decodes th Gets a Variant from the stream. If ``allow_objects`` is ``true``, decoding objects is allowed. +Internally, this uses the same decoding mechanism as the :ref:`@GlobalScope.bytes_to_var` method. + \ **Warning:** Deserialized objects can contain code which gets executed. Do not use this option if the serialized object comes from untrusted sources to avoid potential security threats such as remote code execution. .. rst-class:: classref-item-separator @@ -540,6 +542,8 @@ void **put_var** **(** :ref:`Variant` value, :ref:`bool` method. + .. |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.)` diff --git a/classes/class_string.rst b/classes/class_string.rst index 1b7c3ff3b..5fc1ac5a8 100644 --- a/classes/class_string.rst +++ b/classes/class_string.rst @@ -593,8 +593,8 @@ Returns the index of the **first** occurrence of ``what`` in this string, or ``- GD.Print("Team".Find("I")); // Prints -1 GD.Print("Potato".Find("t")); // Prints 2 - GD.print("Potato".Find("t", 3)); // Prints 4 - GD.print("Potato".Find("t", 5)); // Prints -1 + GD.Print("Potato".Find("t", 3)); // Prints 4 + GD.Print("Potato".Find("t", 5)); // Prints -1 @@ -645,6 +645,8 @@ Some additional handling is performed when ``values`` is an :ref:`Array` tutorial. +\ **Note:** In C#, it's recommended to `interpolate strings with "$" `__, instead. + .. rst-class:: classref-item-separator ---- @@ -1060,7 +1062,7 @@ Returns the concatenation of ``parts``' elements, with each element separated by var fruits = new string[] {"Apple", "Orange", "Pear", "Kiwi"}; // In C#, this method is static. - GD.Print(string.Join(", ", fruits); // Prints "Apple, Orange, Pear, Kiwi" + GD.Print(string.Join(", ", fruits)); // Prints "Apple, Orange, Pear, Kiwi" GD.Print(string.Join("---", fruits)); // Prints "Apple---Orange---Pear---Kiwi" @@ -2001,9 +2003,7 @@ Returns ``true`` if this **String** is not equivalent to the given :ref:`StringN :ref:`String` **operator %** **(** :ref:`Variant` right **)** -Formats the **String**, replacing the placeholders with one or more parameters. - -To pass multiple parameters, ``right`` needs to be an :ref:`Array`. +Formats the **String**, replacing the placeholders with one or more parameters. To pass multiple parameters, ``right`` needs to be an :ref:`Array`. :: @@ -2014,10 +2014,10 @@ To pass multiple parameters, ``right`` needs to be an :ref:`Array`. var speed = 40.3485 print(my_message % [location, speed]) # Prints "Travelling to Deep Valley, at 40.35 km/h." -In C#, there is no direct equivalent to this operator. Use the :ref:`format` method, instead. - For more information, see the :doc:`GDScript format strings <../tutorials/scripting/gdscript/gdscript_format_string>` tutorial. +\ **Note:** In C#, this operator is not available. Instead, see `how to interpolate strings with "$" `__. + .. rst-class:: classref-item-separator ---- @@ -2040,9 +2040,7 @@ Appends ``right`` at the end of this **String**, also known as a string concaten :ref:`String` **operator +** **(** :ref:`StringName` right **)** -.. container:: contribute - - There is currently no description for this operator. Please help us by :ref:`contributing one `! +Appends ``right`` at the end of this **String**, returning a **String**. This is also known as a string concatenation. .. rst-class:: classref-item-separator diff --git a/classes/class_stringname.rst b/classes/class_stringname.rst index 016dd108d..4a14374b6 100644 --- a/classes/class_stringname.rst +++ b/classes/class_stringname.rst @@ -19,7 +19,7 @@ Description **StringName**\ s are immutable strings designed for general-purpose representation of unique names (also called "string interning"). **StringName** ensures that only one instance of a given name exists (so two **StringName**\ s with the same value are the same object). Comparing them is much faster than with regular :ref:`String`\ s, because only the pointers are compared, not the whole strings. -You will usually just pass a :ref:`String` to methods expecting a **StringName** and it will be automatically converted, but you may occasionally want to construct a **StringName** ahead of time with **StringName** or, in GDScript, the literal syntax ``&"example"``. +You will usually just pass a :ref:`String` to methods expecting a **StringName** and it will be automatically converted, but you may occasionally want to construct a **StringName** ahead of time with the **StringName** constructor or, in GDScript, the literal syntax ``&"example"``. See also :ref:`NodePath`, which is a similar concept specifically designed to store pre-parsed node paths. @@ -547,8 +547,8 @@ Returns the index of the **first** occurrence of ``what`` in this string, or ``- GD.Print("Team".Find("I")); // Prints -1 GD.Print("Potato".Find("t")); // Prints 2 - GD.print("Potato".Find("t", 3)); // Prints 4 - GD.print("Potato".Find("t", 5)); // Prints -1 + GD.Print("Potato".Find("t", 3)); // Prints 4 + GD.Print("Potato".Find("t", 5)); // Prints -1 @@ -599,6 +599,8 @@ Some additional handling is performed when ``values`` is an :ref:`Array` tutorial. +\ **Note:** In C#, it's recommended to `interpolate strings with "$" `__, instead. + .. rst-class:: classref-item-separator ---- @@ -1000,7 +1002,7 @@ Returns the concatenation of ``parts``' elements, with each element separated by var fruits = new string[] {"Apple", "Orange", "Pear", "Kiwi"}; // In C#, this method is static. - GD.Print(string.Join(", ", fruits); // Prints "Apple, Orange, Pear, Kiwi" + GD.Print(string.Join(", ", fruits)); // Prints "Apple, Orange, Pear, Kiwi" GD.Print(string.Join("---", fruits)); // Prints "Apple---Orange---Pear---Kiwi" @@ -1844,9 +1846,11 @@ Returns ``true`` if the **StringName** and ``right`` do not refer to the same na :ref:`String` **operator %** **(** :ref:`Variant` right **)** -.. container:: contribute +Formats the **StringName**, replacing the placeholders with one or more parameters, returning a :ref:`String`. To pass multiple parameters, ``right`` needs to be an :ref:`Array`. - There is currently no description for this operator. Please help us by :ref:`contributing one `! +For more information, see the :doc:`GDScript format strings <../tutorials/scripting/gdscript/gdscript_format_string>` tutorial. + +\ **Note:** In C#, this operator is not available. Instead, see `how to interpolate strings with "$" `__. .. rst-class:: classref-item-separator @@ -1858,9 +1862,7 @@ Returns ``true`` if the **StringName** and ``right`` do not refer to the same na :ref:`String` **operator +** **(** :ref:`String` right **)** -.. container:: contribute - - There is currently no description for this operator. Please help us by :ref:`contributing one `! +Appends ``right`` at the end of this **StringName**, returning a :ref:`String`. This is also known as a string concatenation. .. rst-class:: classref-item-separator @@ -1872,9 +1874,7 @@ Returns ``true`` if the **StringName** and ``right`` do not refer to the same na :ref:`String` **operator +** **(** :ref:`StringName` right **)** -.. container:: contribute - - There is currently no description for this operator. Please help us by :ref:`contributing one `! +Appends ``right`` at the end of this **StringName**, returning a :ref:`String`. This is also known as a string concatenation. .. rst-class:: classref-item-separator diff --git a/classes/class_textedit.rst b/classes/class_textedit.rst index b9e977fc5..369492eaa 100644 --- a/classes/class_textedit.rst +++ b/classes/class_textedit.rst @@ -2353,7 +2353,7 @@ You can add custom menu items or remove standard ones. Make sure your IDs don't :ref:`int` **get_minimap_line_at_pos** **(** :ref:`Vector2i` position **)** |const| -Returns the equivalent minimap line at ``position`` +Returns the equivalent minimap line at ``position``. .. rst-class:: classref-item-separator @@ -2429,7 +2429,7 @@ Returns the local position and size for the grapheme at the given ``line`` and ` :ref:`int` **get_saved_version** **(** **)** |const| -Returns the last tagged saved version from :ref:`tag_saved_version` +Returns the last tagged saved version from :ref:`tag_saved_version`. .. rst-class:: classref-item-separator @@ -3350,7 +3350,7 @@ Sets the tab size for the **TextEdit** to use. void **set_tooltip_request_func** **(** :ref:`Callable` callback **)** -Provide custom tooltip text. The callback method must take the following args: ``hovered_word: String`` +Provide custom tooltip text. The callback method must take the following args: ``hovered_word: String``. .. rst-class:: classref-item-separator diff --git a/classes/class_texturelayered.rst b/classes/class_texturelayered.rst index c86cff274..4f0db755a 100644 --- a/classes/class_texturelayered.rst +++ b/classes/class_texturelayered.rst @@ -29,7 +29,7 @@ All images need to have the same width, height and number of mipmap levels. A **TextureLayered** can be loaded with :ref:`ResourceLoader.load`. -Internally, Godot maps these files to their respective counterparts in the target rendering driver (Vulkan, GLES3). +Internally, Godot maps these files to their respective counterparts in the target rendering driver (Vulkan, OpenGL3). .. rst-class:: classref-reftable-group diff --git a/classes/class_tilemap.rst b/classes/class_tilemap.rst index 7ada44b65..925b704a0 100644 --- a/classes/class_tilemap.rst +++ b/classes/class_tilemap.rst @@ -105,6 +105,8 @@ Methods +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_layers_count` **(** **)** |const| | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`RID` | :ref:`get_navigation_map` **(** :ref:`int` layer **)** |const| | + +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector2i` | :ref:`get_neighbor_cell` **(** :ref:`Vector2i` coords, :ref:`CellNeighbor` neighbor **)** |const| | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`TileMapPattern` | :ref:`get_pattern` **(** :ref:`int` layer, :ref:`Vector2i[]` coords_array **)** | @@ -149,6 +151,8 @@ Methods +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_layer_z_index` **(** :ref:`int` layer, :ref:`int` z_index **)** | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | void | :ref:`set_navigation_map` **(** :ref:`int` layer, :ref:`RID` map **)** | + +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_pattern` **(** :ref:`int` layer, :ref:`Vector2i` position, :ref:`TileMapPattern` pattern **)** | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -551,6 +555,22 @@ Returns the number of layers in the TileMap. ---- +.. _class_TileMap_method_get_navigation_map: + +.. rst-class:: classref-method + +:ref:`RID` **get_navigation_map** **(** :ref:`int` layer **)** |const| + +Returns the :ref:`NavigationServer2D` navigation map :ref:`RID` currently assigned to the specified TileMap ``layer``. + +By default the TileMap uses the default :ref:`World2D` navigation map for the first TileMap layer. For each additional TileMap layer a new navigation map is created for the additional layer. + +In order to make :ref:`NavigationAgent2D` switch between TileMap layer navigation maps use :ref:`NavigationAgent2D.set_navigation_map` with the navigation map received from :ref:`get_navigation_map`. + +.. rst-class:: classref-item-separator + +---- + .. _class_TileMap_method_get_neighbor_cell: .. rst-class:: classref-method @@ -581,7 +601,7 @@ Creates a new :ref:`TileMapPattern` from the given layer a :ref:`Vector2i[]` **get_surrounding_cells** **(** :ref:`Vector2i` coords **)** -Returns the list of all neighbourings cells to the one at ``coords`` +Returns the list of all neighbourings cells to the one at ``coords``. .. rst-class:: classref-item-separator @@ -669,7 +689,7 @@ Returns the map coordinates of the cell containing the given ``local_position``. :ref:`Vector2i` **map_pattern** **(** :ref:`Vector2i` position_in_tilemap, :ref:`Vector2i` coords_in_pattern, :ref:`TileMapPattern` pattern **)** -Returns for the given coordinate ``coords_in_pattern`` in a :ref:`TileMapPattern` the corresponding cell coordinates if the pattern was pasted at the ``position_in_tilemap`` coordinates (see :ref:`set_pattern`). This mapping is required as in half-offset tile shapes, the mapping might not work by calculating ``position_in_tile_map + coords_in_pattern`` +Returns for the given coordinate ``coords_in_pattern`` in a :ref:`TileMapPattern` the corresponding cell coordinates if the pattern was pasted at the ``position_in_tilemap`` coordinates (see :ref:`set_pattern`). This mapping is required as in half-offset tile shapes, the mapping might not work by calculating ``position_in_tile_map + coords_in_pattern``. .. rst-class:: classref-item-separator @@ -853,6 +873,22 @@ If ``layer`` is negative, the layers are accessed from the last one. ---- +.. _class_TileMap_method_set_navigation_map: + +.. rst-class:: classref-method + +void **set_navigation_map** **(** :ref:`int` layer, :ref:`RID` map **)** + +Assigns a :ref:`NavigationServer2D` navigation map :ref:`RID` to the specified TileMap ``layer``. + +By default the TileMap uses the default :ref:`World2D` navigation map for the first TileMap layer. For each additional TileMap layer a new navigation map is created for the additional layer. + +In order to make :ref:`NavigationAgent2D` switch between TileMap layer navigation maps use :ref:`NavigationAgent2D.set_navigation_map` with the navigation map received from :ref:`get_navigation_map`. + +.. rst-class:: classref-item-separator + +---- + .. _class_TileMap_method_set_pattern: .. rst-class:: classref-method diff --git a/classes/class_visibleonscreennotifier2d.rst b/classes/class_visibleonscreennotifier2d.rst index 9a55591f0..113125d36 100644 --- a/classes/class_visibleonscreennotifier2d.rst +++ b/classes/class_visibleonscreennotifier2d.rst @@ -25,6 +25,8 @@ The VisibleOnScreenNotifier2D detects when it is visible on the screen. It also If you want nodes to be disabled automatically when they exit the screen, use :ref:`VisibleOnScreenEnabler2D` instead. +\ **Note:** VisibleOnScreenNotifier2D uses the render culling code to determine whether it's visible on screen, which also means that its :ref:`CanvasItem.visible` must be ``true`` to work correctly. + .. rst-class:: classref-introduction-group Tutorials diff --git a/classes/class_visibleonscreennotifier3d.rst b/classes/class_visibleonscreennotifier3d.rst index d26e22538..8bad9c80a 100644 --- a/classes/class_visibleonscreennotifier3d.rst +++ b/classes/class_visibleonscreennotifier3d.rst @@ -25,7 +25,7 @@ The VisibleOnScreenNotifier3D detects when it is visible on the screen. It also If you want nodes to be disabled automatically when they exit the screen, use :ref:`VisibleOnScreenEnabler3D` instead. -\ **Note:** VisibleOnScreenNotifier3D uses an approximate heuristic for performance reasons. It doesn't take walls and other occlusion into account. The heuristic is an implementation detail and may change in future versions. If you need precise visibility checking, use another method such as adding an :ref:`Area3D` node as a child of a :ref:`Camera3D` node and/or :ref:`Vector3.dot`. +\ **Note:** VisibleOnScreenNotifier3D uses the render culling code to determine whether it's visible on screen, which also means that its :ref:`Node3D.visible` must be ``true`` to work correctly. .. rst-class:: classref-reftable-group diff --git a/classes/class_voxelgi.rst b/classes/class_voxelgi.rst index 8baecb607..6174fe36a 100644 --- a/classes/class_voxelgi.rst +++ b/classes/class_voxelgi.rst @@ -21,6 +21,8 @@ Description **VoxelGI**\ s are used to provide high-quality real-time indirect light and reflections to scenes. They precompute the effect of objects that emit light and the effect of static geometry to simulate the behavior of complex light in real-time. **VoxelGI**\ s need to be baked before having a visible effect. However, once baked, dynamic objects will receive light from them. Furthermore, lights can be fully dynamic or baked. +\ **Note:** **VoxelGI** is only supported in the Forward+ rendering method, not Mobile or Compatibility. + \ **Procedural generation:** **VoxelGI** can be baked in an exported project, which makes it suitable for procedurally generated or user-built levels as long as all the geometry is generated in advance. For games where geometry is generated at any time during gameplay, SDFGI is more suitable (see :ref:`Environment.sdfgi_enabled`). \ **Performance:** **VoxelGI** is relatively demanding on the GPU and is not suited to low-end hardware such as integrated graphics (consider :ref:`LightmapGI` instead). To improve performance, adjust :ref:`ProjectSettings.rendering/global_illumination/voxel_gi/quality` and enable :ref:`ProjectSettings.rendering/global_illumination/gi/use_half_resolution` in the Project Settings. To provide a fallback for low-end hardware, consider adding an option to disable **VoxelGI** in your project's options menus. A **VoxelGI** node can be disabled by hiding it. diff --git a/classes/class_websocketmultiplayerpeer.rst b/classes/class_websocketmultiplayerpeer.rst index 5f58ee319..a40630389 100644 --- a/classes/class_websocketmultiplayerpeer.rst +++ b/classes/class_websocketmultiplayerpeer.rst @@ -189,7 +189,7 @@ Method Descriptions Starts a new multiplayer client connecting to the given ``url``. TLS certificates will be verified against the hostname when connecting using the ``wss://`` protocol. You can pass the optional ``tls_client_options`` parameter to customize the trusted certification authorities, or disable the common name verification. See :ref:`TLSOptions.client` and :ref:`TLSOptions.client_unsafe`. -\ **Note**: It is recommended to specify the scheme part of the URL, i.e. the ``url`` should start with either ``ws://`` or ``wss://``. +\ **Note:** It is recommended to specify the scheme part of the URL, i.e. the ``url`` should start with either ``ws://`` or ``wss://``. .. rst-class:: classref-item-separator diff --git a/classes/class_window.rst b/classes/class_window.rst index c8b019681..a4ce2bfe0 100644 --- a/classes/class_window.rst +++ b/classes/class_window.rst @@ -1939,6 +1939,8 @@ Popups the **Window** at the center of the current screen, with optionally given If the **Window** is embedded, it will be centered in the parent :ref:`Viewport` instead. +\ **Note:** Calling it with the default value of ``minsize`` is equivalent to calling it with :ref:`size`. + .. rst-class:: classref-item-separator ---- @@ -1953,6 +1955,8 @@ Popups the **Window** centered inside its parent **Window**. \ ``fallback_ratio`` determines the maximum size of the **Window**, in relation to its parent. +\ **Note:** Calling it with the default value of ``minsize`` is equivalent to calling it with :ref:`size`. + .. rst-class:: classref-item-separator ----